# Concepts Source: https://docs.pinecone.io/guides/get-started/concepts Understand concepts in Pinecone and how they relate to each other. ## Organization An organization is a group of one or more [projects](#project) that use the same billing. Organizations allow one or more [users](#user) to control billing and permissions for all of the projects belonging to the organization. For more information, see [Understanding organizations](/guides/organizations/understanding-organizations). ## Project A project belongs to an [organization](#organization) and contains one or more [indexes](#index). Each project belongs to exactly one organization, but only [users](#user) who belong to the project can access the indexes in that project. [API keys](#api-key) and [Assistants](#assistant) are project-specific. For more information, see [Understanding projects](/guides/projects/understanding-projects). ## Index There are two types of [serverless indexes](/guides/index-data/indexing-overview), dense and sparse. ### Dense index Dense indexes store records that have one [dense vector](#dense-vector) each. If any records in a dense index also have a [sparse vector](#sparse-vector), the index is a [hybrid index](/guides/search/hybrid-search#use-a-single-hybrid-index). A dense vector is a series of numbers that represent the meaning and relationships of text, images, or other types of data. 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. When you query a dense index, Pinecone retrieves records containing dense vectors that are most semantically similar to the query. This is often called **semantic search**, nearest neighbor search, similarity search, or just vector search. ### Sparse index Sparse indexes store records that have one [sparse vector](#sparse-vector) each. Every sparse vector is a series of numbers that represent the words or phrases in a document. Sparse vectors 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. When you search a sparse index, Pinecone retrieves the records with sparse vectors that most exactly match the words or phrases in the query. Query terms are scored independently and then summed, with records that have the most similar vectors scored highest. This is often called **lexical search** or **keyword search**. ## Namespace A namespace is a partition within a [dense](#dense-index) or [sparse index](#sparse-index). It divides [records](#record) in an index into separate groups. All [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other [data operations](/reference/api/latest/data-plane) always target one namespace: For more information, see [Use namespaces](/guides/index-data/indexing-overview#namespaces). ## Record A record is a basic unit of data and consists of a [record ID](#record-id), a [dense vector](#dense-vector) or a [sparse vector](#sparse-vector) (depending on the type of index), and optional [metadata](#metadata). For more information, see [Upsert data](/guides/index-data/upsert-data). ### Record ID A record ID is a record's unique ID. [Use ID prefixes](/guides/index-data/data-modeling#use-structured-ids) that reflect the type of data you're storing. ### Dense vector A dense vector, also referred to as a vector embedding or simply a vector, is a series of numbers that represent the meaning and relationships of data. Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar. Dense vectors are stored in [dense indexes](#dense-index). You use a dense embedding model to convert data to dense vectors. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index. For more information about dense vectors, see [What are vector embeddings?](https://www.pinecone.io/learn/vector-embeddings/). ### Sparse vector Sparse vectors are often used to represent documents or queries in a way that captures keyword information. Each dimension in a sparse vector typically represents a word from a dictionary, and the non-zero values represent the importance of these words in the document. Sparse vectors have a large number of dimensions, but a small number of those values are non-zero. Because most values are zero, Pinecone stores sparse vectors efficiently by keeping only the non-zero values along with their corresponding indices. Sparse vectors are stored in [sparse indexes](#sparse-index) and [hybrid indexes](/guides/search/hybrid-search#use-a-single-hybrid-index). To convert data to sparse vectors, use a sparse embedding model. The embedding model can be external to Pinecone or [hosted on Pinecone infrastructure](/guides/index-data/create-an-index#embedding-models) and integrated with an index. For more information about sparse vectors, see [Sparse retrieval](https://www.pinecone.io/learn/sparse-retrieval/). ### Metadata Metadata is additional information included in a record to provide more context and enable additional [filtering capabilities](/guides/index-data/indexing-overview#metadata). For example, the original text that was embedded can be stored in the metadata. ## Other concepts Although not represented in the diagram above, Pinecone also contains the following concepts: * [API key](#api-key) * [User](#user) * [Backup or collection](#backup-or-collection) * [Pinecone Inference](#pinecone-inference) ### API key An API key is a unique token that [authenticates](/reference/api/authentication) and authorizes access to the [Pinecone APIs](/reference/api/introduction). API keys are project-specific. ### User A user is a member of organizations and projects. Users are assigned specific roles at the organization and project levels that determine the user's permissions in the [Pinecone console](https://app.pinecone.io). For more information, see [Manage organization members](/guides/organizations/manage-organization-members) and [Manage project members](/guides/projects/manage-project-members). ### Backup or collection A backup is a static copy of a serverless index. Backups only consume storage. They are non-queryable representations of a set of records. You can create a backup from an index, and you can create a new index from that backup. The new index configuration can differ from the original source index: for example, it can have a different name. However, it must have the same number of dimensions and similarity metric as the source index. For more information, see [Understanding backups](/guides/manage-data/backups-overview). ### Pinecone Inference Pinecone Inference is an API service that provides access to [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. ## Learn more * [Vector database](https://www.pinecone.io/learn/vector-database/) * [Pinecone APIs](/reference/api/introduction) * [Approximate nearest neighbor (ANN) algorithms](https://www.pinecone.io/learn/a-developers-guide-to-ann-algorithms/) * [Retrieval augmented generation (RAG)](https://www.pinecone.io/learn/retrieval-augmented-generation/) * [Image search](https://www.pinecone.io/learn/series/image-search/) * [Tokenization](https://www.pinecone.io/learn/tokenization/) # Architecture Source: https://docs.pinecone.io/guides/get-started/database-architecture Learn how Pinecone's architecture enables fast, relevant vector search at any scale. ## Overview Pinecone runs as a managed service on AWS, GCP, and Azure cloud platforms. When you send a request to Pinecone, it goes through an [API gateway](#api-gateway) that routes it to either a global [control plane](#control-plane) or a regional [data plane](#data-plane). All your vector data is stored in highly efficient, distributed [object storage](#object-storage). ### API gateway Every request to Pinecone includes an [API key](/guides/projects/manage-api-keys) that's assigned to a specific [project](/guides/projects/understanding-projects). The API gateway first validates your API key to make sure you have permission to access the project. Once validated, it routes your request to either the global control plane (for managing projects and indexes) or a regional data plane (for reading and writing data), depending on what you're trying to do. ### Control plane The global control plane manages your organizational resources like projects and indexes. It uses a dedicated database to keep track of all these objects. The control plane also handles billing, user management, and coordinates operations across different regions. ### Data plane The data plane handles all requests to write and read records in [indexes](/guides/index-data/indexing-overview) within a specific [cloud region](/guides/index-data/create-an-index#cloud-regions). Each index is divided into one or more logical [namespaces](/guides/index-data/indexing-overview#namespaces), and all your read and write requests target a specific namespace. Pinecone separates write and read operations into different paths, with each scaling independently based on demand. This separation ensures that your queries never slow down your writes, and your writes never slow down your queries. ### Object storage For each namespace in a serverless index, Pinecone organizes records into immutable files called slabs. These slabs are [optimized for fast querying](#index-builder) and stored in distributed object storage that provides virtually unlimited scalability and high availability. ## Write path ### Request log When you send a write request (to add, update, or delete records), the [data plane](#data-plane) first logs the request details with a unique sequence number (LSN). This ensures all operations happen in the correct order and provides a way to track the state of the index. Pinecone immediately returns a `200 OK` response, guaranteeing that your write is durable and won't be lost. The system then processes your write in the background. ### Index builder The index builder stores your write data in an in-memory structure called a memtable. This includes your vector data, any metadata you've attached, and the sequence number. If you're updating or deleting a record, the system also tracks how to handle the old version during queries. Periodically, the index builder moves data from the memtable to permanent storage. In [object storage](#object-storage), your data is organized into immutable files called slabs. These slabs are optimized for query performance. Smaller slabs use fast indexing techniques that provide good performance with minimal resource requirements. As slabs grow, the system merges them into larger slabs that use more sophisticated methods that provide better performance at scale. This adaptive process both optimizes query performance for each slab and amortizes the cost of more expensive indexing through the lifetime of the namespace. All read operations check the memtable first, so you can immediately search data that you've just written, even before it's moved to permanent storage. For more details, see [Query executors](#query-executors). ## Read path ### Query routers When you send a search query, the [data plane](#data-plane) first validates your request and checks that it meets system limits like [rate and object limits](/reference/api/database-limits.mdx). The query router then identifies which slabs contain relevant data and routes your query to the appropriate executors. It also searches the memtable for any recent data that hasn't been moved to permanent storage yet. ### Query executors Each query executor searches through its assigned slabs and returns the most relevant candidates to the query router. If your query includes metadata filters, the executors exclude records that don't match your criteria before finding the best matches. Most of the time, the slabs are cached in memory or on local SSD, which provides very fast query performance. If a slab isn't cached (which happens when it's accessed for the first time or hasn't been used recently), the executor fetches it from object storage and caches it for future queries. The query router then combines results from all executors, removes duplicates, merges them with results from the memtable, and returns the final set of best matches to you. # Pinecone documentation Source: https://docs.pinecone.io/guides/get-started/overview Pinecone is the leading vector database for building accurate and performant AI applications at scale in production. Set up a fully managed vector database for high-performance semantic search Create an AI assistant that answers complex questions about your proprietary data ## Workflows Use integrated embedding to upsert and search with text and have Pinecone generate vectors automatically. [Create an index](/guides/index-data/create-an-index) that is integrated with one of Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models). Dense indexes and vectors enable semantic search, while sparse indexes and vectors enable lexical search. [Prepare](/guides/index-data/data-modeling) your data for efficient ingestion, retrieval, and management in Pinecone. [Upsert](/guides/index-data/upsert-data) your source text and have Pinecone convert the text to vectors automatically. [Use namespaces to partition data](/guides/index-data/indexing-overview#namespaces) for faster queries and multitenant isolation between customers. [Search](/guides/search/search-overview) the index with a query text. Again, Pinecone uses the index's integrated model to convert the text to a vector automatically. [Filter by metadata](/guides/search/filter-by-metadata) to limit the scope of your search, [rerank results](/guides/search/rerank-results) to increase search accuracy, or add [lexical search](/guides/search/lexical-search) to capture both semantic understanding and precise keyword matches. If you use an external embedding model to generate vectors, you can upsert and search with vectors directly. Use an external embedding model to convert data into dense or sparse vectors. [Create an index](/guides/index-data/create-an-index) that matches the characteristics of your embedding model. Dense indexes and vectors enable semantic search, while sparse indexes and vectors enable lexical search. [Prepare](/guides/index-data/data-modeling) your data for efficient ingestion, retrieval, and management in Pinecone. [Load your vectors](/guides/index-data/data-ingestion-overview) and metadata into your index using Pinecone's import or upsert feature. [Use namespaces to partition data](/guides/index-data/indexing-overview#namespaces) for faster queries and multitenant isolation between customers. Use an external embedding model to convert a query text to a vector and [search](/guides/search/search-overview) the index with the vector. [Filter by metadata](/guides/search/filter-by-metadata) to limit the scope of your search, [rerank results](/guides/search/rerank-results) to increase search accuracy, or add [lexical search](/guides/search/lexical-search) to capture both semantic understanding and precise keyword matches. ## Start building Comprehensive details about the Pinecone APIs, SDKs, utilities, and architecture. Simplify vector search with integrated embedding and reranking. Hands-on notebooks and sample apps with common AI patterns and tools. Pinecone's growing number of third-party integrations. Resolve common Pinecone issues with our troubleshooting guide. News about features and changes in Pinecone and related tools. # Quickstart Source: https://docs.pinecone.io/guides/get-started/quickstart Get started with Pinecone manually, with AI assistance, or with no-code tools. Use a Pinecone SDK to create an index, upsert data, and perform semantic search. To get started in your browser, use the [Quickstart colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-quickstart.ipynb). ## 1. Sign up If you're new to Pinecone, sign up at [app.pinecone.io](https://app.pinecone.io) and choose a free plan: * [Starter plan](https://pinecone.io/pricing/): Free access to most features, but you're limited to one cloud region and need to stay under Starter plan [limits](/reference/api/database-limits). * [Standard plan trial](/guides/organizations/manage-billing/standard-trial): 21 days and \$300 in credits with access to Standard plan [features](https://www.pinecone.io/pricing/) and [higher limits](/reference/api/database-limits) that let you test Pinecone at scale. If you're already on a Starter plan, you can activate a Standard plan trial at any time (one trial per organization). After signing up, you'll receive an API key in the console. Save this key. You'll need it to authenticate your requests to Pinecone. ## 2. Install an SDK [Pinecone SDKs](/reference/pinecone-sdks) provide convenient programmatic access to the [Pinecone APIs](/reference/api/introduction). Install the SDK for your preferred language: ```shell Python theme={null} pip install pinecone ``` ```shell JavaScript theme={null} npm install @pinecone-database/pinecone ``` ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ```shell Go theme={null} go get github.com/pinecone-io/go-pinecone/v4/pinecone ``` ```shell C# theme={null} # .NET Core CLI dotnet add package Pinecone.Client # NuGet CLI nuget install Pinecone.Client ``` ## 3. Create an index In Pinecone, there are two types of indexes for storing vector data: [Dense indexes](/guides/index-data/indexing-overview#dense-indexes) store dense vectors for semantic search, and [sparse indexes](/guides/index-data/indexing-overview#sparse-indexes) store sparse vectors for lexical/keyword search. For this quickstart, [create a dense index](/guides/index-data/create-an-index#create-a-dense-index) that is integrated with an [embedding model hosted by Pinecone](/guides/index-data/create-an-index#embedding-models). With integrated models, you upsert and search with text and have Pinecone generate vectors automatically. If you prefer to use external embedding models, see [Bring your own vectors](/guides/index-data/indexing-overview#bring-your-own-vectors). ```python Python theme={null} # Import the Pinecone library from pinecone import Pinecone # Initialize a Pinecone client with your API key pc = Pinecone(api_key="{{YOUR_API_KEY}}") # Create a dense index with integrated embedding index_name = "quickstart-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} // Import 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}}' }); // Create a dense index with integrated embedding const indexName = 'quickstart-js'; await pc.createIndexForModel({ name: indexName, cloud: 'aws', region: 'us-east-1', embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_data.client.model.SearchRecordsRequestQuery; import org.openapitools.db_data.client.model.SearchRecordsResponse; import io.pinecone.proto.DescribeIndexStatsResponse; import java.util.*; public class Quickstart { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("{{YOUR_API_KEY}}").build(); String indexName = "quickstart-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("llama-text-embed-v2") .fieldMap(fieldMap); IndexModel index = pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, null ); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "{{YOUR_API_KEY}}", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "quickstart-go" index, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "llama-text-embed-v2", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } // Function to prettify responses func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("{{YOUR_API_KEY}}"); var indexName = "quickstart-dotnet"; var createIndexRequest = await pinecone.CreateIndexForModelAsync( new CreateIndexForModelRequest { Name = indexName, Cloud = CreateIndexForModelRequestCloud.Aws, Region = "us-east-1", Embed = new CreateIndexForModelRequestEmbed { Model = "llama-text-embed-v2", FieldMap = new Dictionary() { { "text", "chunk_text" } } } ); ``` ## 4. Upsert text Prepare a sample dataset of factual statements from different domains like history, physics, technology, and music. [Model the data](/guides/index-data/data-modeling) as as records with an ID, text, and category. ```python Python [expandable] theme={null} records = [ { "_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" }, { "_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" }, { "_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science" }, { "_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology" }, { "_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" }, { "_id": "rec6", "chunk_text": "Water boils at 100°C under standard atmospheric pressure.", "category": "physics" }, { "_id": "rec7", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history" }, { "_id": "rec8", "chunk_text": "Honey never spoils due to its low moisture content and acidity.", "category": "food science" }, { "_id": "rec9", "chunk_text": "The speed of light in a vacuum is approximately 299,792 km/s.", "category": "physics" }, { "_id": "rec10", "chunk_text": "Newton's laws describe the motion of objects.", "category": "physics" }, { "_id": "rec11", "chunk_text": "The human brain has approximately 86 billion neurons.", "category": "biology" }, { "_id": "rec12", "chunk_text": "The Amazon Rainforest is one of the most biodiverse places on Earth.", "category": "geography" }, { "_id": "rec13", "chunk_text": "Black holes have gravitational fields so strong that not even light can escape.", "category": "astronomy" }, { "_id": "rec14", "chunk_text": "The periodic table organizes elements based on their atomic number.", "category": "chemistry" }, { "_id": "rec15", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" }, { "_id": "rec16", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology" }, { "_id": "rec17", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" }, { "_id": "rec18", "chunk_text": "Dogs have an incredible sense of smell, much stronger than humans.", "category": "biology" }, { "_id": "rec19", "chunk_text": "The Pacific Ocean is the largest and deepest ocean on Earth.", "category": "geography" }, { "_id": "rec20", "chunk_text": "Chess is a strategic game that originated in India.", "category": "games" }, { "_id": "rec21", "chunk_text": "The Statue of Liberty was a gift from France to the United States.", "category": "history" }, { "_id": "rec22", "chunk_text": "Coffee contains caffeine, a natural stimulant.", "category": "food science" }, { "_id": "rec23", "chunk_text": "Thomas Edison invented the practical electric light bulb.", "category": "inventions" }, { "_id": "rec24", "chunk_text": "The moon influences ocean tides due to gravitational pull.", "category": "astronomy" }, { "_id": "rec25", "chunk_text": "DNA carries genetic information for all living organisms.", "category": "biology" }, { "_id": "rec26", "chunk_text": "Rome was once the center of a vast empire.", "category": "history" }, { "_id": "rec27", "chunk_text": "The Wright brothers pioneered human flight in 1903.", "category": "inventions" }, { "_id": "rec28", "chunk_text": "Bananas are a good source of potassium.", "category": "nutrition" }, { "_id": "rec29", "chunk_text": "The stock market fluctuates based on supply and demand.", "category": "economics" }, { "_id": "rec30", "chunk_text": "A compass needle points toward the magnetic north pole.", "category": "navigation" }, { "_id": "rec31", "chunk_text": "The universe is expanding, according to the Big Bang theory.", "category": "astronomy" }, { "_id": "rec32", "chunk_text": "Elephants have excellent memory and strong social bonds.", "category": "biology" }, { "_id": "rec33", "chunk_text": "The violin is a string instrument commonly used in orchestras.", "category": "music" }, { "_id": "rec34", "chunk_text": "The heart pumps blood throughout the human body.", "category": "biology" }, { "_id": "rec35", "chunk_text": "Ice cream melts when exposed to heat.", "category": "food science" }, { "_id": "rec36", "chunk_text": "Solar panels convert sunlight into electricity.", "category": "technology" }, { "_id": "rec37", "chunk_text": "The French Revolution began in 1789.", "category": "history" }, { "_id": "rec38", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" }, { "_id": "rec39", "chunk_text": "Rainbows are caused by light refracting through water droplets.", "category": "physics" }, { "_id": "rec40", "chunk_text": "Mount Everest is the tallest mountain in the world.", "category": "geography" }, { "_id": "rec41", "chunk_text": "Octopuses are highly intelligent marine creatures.", "category": "biology" }, { "_id": "rec42", "chunk_text": "The speed of sound is around 343 meters per second in air.", "category": "physics" }, { "_id": "rec43", "chunk_text": "Gravity keeps planets in orbit around the sun.", "category": "astronomy" }, { "_id": "rec44", "chunk_text": "The Mediterranean diet is considered one of the healthiest in the world.", "category": "nutrition" }, { "_id": "rec45", "chunk_text": "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", "category": "literature" }, { "_id": "rec46", "chunk_text": "The human body is made up of about 60% water.", "category": "biology" }, { "_id": "rec47", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation.", "category": "history" }, { "_id": "rec48", "chunk_text": "Vincent van Gogh painted Starry Night.", "category": "art" }, { "_id": "rec49", "chunk_text": "Airplanes fly due to the principles of lift and aerodynamics.", "category": "physics" }, { "_id": "rec50", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" } ] ``` ```javascript JavaScript [expandable] theme={null} const records = [ { "_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" }, { "_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" }, { "_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science" }, { "_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology" }, { "_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" }, { "_id": "rec6", "chunk_text": "Water boils at 100°C under standard atmospheric pressure.", "category": "physics" }, { "_id": "rec7", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history" }, { "_id": "rec8", "chunk_text": "Honey never spoils due to its low moisture content and acidity.", "category": "food science" }, { "_id": "rec9", "chunk_text": "The speed of light in a vacuum is approximately 299,792 km/s.", "category": "physics" }, { "_id": "rec10", "chunk_text": "Newton's laws describe the motion of objects.", "category": "physics" }, { "_id": "rec11", "chunk_text": "The human brain has approximately 86 billion neurons.", "category": "biology" }, { "_id": "rec12", "chunk_text": "The Amazon Rainforest is one of the most biodiverse places on Earth.", "category": "geography" }, { "_id": "rec13", "chunk_text": "Black holes have gravitational fields so strong that not even light can escape.", "category": "astronomy" }, { "_id": "rec14", "chunk_text": "The periodic table organizes elements based on their atomic number.", "category": "chemistry" }, { "_id": "rec15", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" }, { "_id": "rec16", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology" }, { "_id": "rec17", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" }, { "_id": "rec18", "chunk_text": "Dogs have an incredible sense of smell, much stronger than humans.", "category": "biology" }, { "_id": "rec19", "chunk_text": "The Pacific Ocean is the largest and deepest ocean on Earth.", "category": "geography" }, { "_id": "rec20", "chunk_text": "Chess is a strategic game that originated in India.", "category": "games" }, { "_id": "rec21", "chunk_text": "The Statue of Liberty was a gift from France to the United States.", "category": "history" }, { "_id": "rec22", "chunk_text": "Coffee contains caffeine, a natural stimulant.", "category": "food science" }, { "_id": "rec23", "chunk_text": "Thomas Edison invented the practical electric light bulb.", "category": "inventions" }, { "_id": "rec24", "chunk_text": "The moon influences ocean tides due to gravitational pull.", "category": "astronomy" }, { "_id": "rec25", "chunk_text": "DNA carries genetic information for all living organisms.", "category": "biology" }, { "_id": "rec26", "chunk_text": "Rome was once the center of a vast empire.", "category": "history" }, { "_id": "rec27", "chunk_text": "The Wright brothers pioneered human flight in 1903.", "category": "inventions" }, { "_id": "rec28", "chunk_text": "Bananas are a good source of potassium.", "category": "nutrition" }, { "_id": "rec29", "chunk_text": "The stock market fluctuates based on supply and demand.", "category": "economics" }, { "_id": "rec30", "chunk_text": "A compass needle points toward the magnetic north pole.", "category": "navigation" }, { "_id": "rec31", "chunk_text": "The universe is expanding, according to the Big Bang theory.", "category": "astronomy" }, { "_id": "rec32", "chunk_text": "Elephants have excellent memory and strong social bonds.", "category": "biology" }, { "_id": "rec33", "chunk_text": "The violin is a string instrument commonly used in orchestras.", "category": "music" }, { "_id": "rec34", "chunk_text": "The heart pumps blood throughout the human body.", "category": "biology" }, { "_id": "rec35", "chunk_text": "Ice cream melts when exposed to heat.", "category": "food science" }, { "_id": "rec36", "chunk_text": "Solar panels convert sunlight into electricity.", "category": "technology" }, { "_id": "rec37", "chunk_text": "The French Revolution began in 1789.", "category": "history" }, { "_id": "rec38", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" }, { "_id": "rec39", "chunk_text": "Rainbows are caused by light refracting through water droplets.", "category": "physics" }, { "_id": "rec40", "chunk_text": "Mount Everest is the tallest mountain in the world.", "category": "geography" }, { "_id": "rec41", "chunk_text": "Octopuses are highly intelligent marine creatures.", "category": "biology" }, { "_id": "rec42", "chunk_text": "The speed of sound is around 343 meters per second in air.", "category": "physics" }, { "_id": "rec43", "chunk_text": "Gravity keeps planets in orbit around the sun.", "category": "astronomy" }, { "_id": "rec44", "chunk_text": "The Mediterranean diet is considered one of the healthiest in the world.", "category": "nutrition" }, { "_id": "rec45", "chunk_text": "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", "category": "literature" }, { "_id": "rec46", "chunk_text": "The human body is made up of about 60% water.", "category": "biology" }, { "_id": "rec47", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation.", "category": "history" }, { "_id": "rec48", "chunk_text": "Vincent van Gogh painted Starry Night.", "category": "art" }, { "_id": "rec49", "chunk_text": "Airplanes fly due to the principles of lift and aerodynamics.", "category": "physics" }, { "_id": "rec50", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" } ]; ``` ```java Java [expandable] theme={null} // Add to the Quickstart class: ArrayList> upsertRecords = new ArrayList<>(); HashMap record1 = new HashMap<>(); record1.put("_id", "rec1"); record1.put("chunk_text", "The Eiffel Tower was completed in 1889 and stands in Paris, France."); record1.put("category", "history"); HashMap record2 = new HashMap<>(); record2.put("_id", "rec2"); record2.put("chunk_text", "Photosynthesis allows plants to convert sunlight into energy."); record2.put("category", "science"); HashMap record3 = new HashMap<>(); record3.put("_id", "rec3"); record3.put("chunk_text", "Albert Einstein developed the theory of relativity."); record3.put("category", "science"); HashMap record4 = new HashMap<>(); record4.put("_id", "rec4"); record4.put("chunk_text", "The mitochondrion is often called the powerhouse of the cell."); record4.put("category", "biology"); HashMap record5 = new HashMap<>(); record5.put("_id", "rec5"); record5.put("chunk_text", "Shakespeare wrote many famous plays, including Hamlet and Macbeth."); record5.put("category", "literature"); HashMap record6 = new HashMap<>(); record6.put("_id", "rec6"); record6.put("chunk_text", "Water boils at 100°C under standard atmospheric pressure."); record6.put("category", "physics"); HashMap record7 = new HashMap<>(); record7.put("_id", "rec7"); record7.put("chunk_text", "The Great Wall of China was built to protect against invasions."); record7.put("category", "history"); HashMap record8 = new HashMap<>(); record8.put("_id", "rec8"); record8.put("chunk_text", "Honey never spoils due to its low moisture content and acidity."); record8.put("category", "food science"); HashMap record9 = new HashMap<>(); record9.put("_id", "rec9"); record9.put("chunk_text", "The speed of light in a vacuum is approximately 299,792 km/s."); record9.put("category", "physics"); HashMap record10 = new HashMap<>(); record10.put("_id", "rec10"); record10.put("chunk_text", "Newton's laws describe the motion of objects."); record10.put("category", "physics"); HashMap record11 = new HashMap<>(); record11.put("_id", "rec11"); record11.put("chunk_text", "The human brain has approximately 86 billion neurons."); record11.put("category", "biology"); HashMap record12 = new HashMap<>(); record12.put("_id", "rec12"); record12.put("chunk_text", "The Amazon Rainforest is one of the most biodiverse places on Earth."); record12.put("category", "geography"); HashMap record13 = new HashMap<>(); record13.put("_id", "rec13"); record13.put("chunk_text", "Black holes have gravitational fields so strong that not even light can escape."); record13.put("category", "astronomy"); HashMap record14 = new HashMap<>(); record14.put("_id", "rec14"); record14.put("chunk_text", "The periodic table organizes elements based on their atomic number."); record14.put("category", "chemistry"); HashMap record15 = new HashMap<>(); record15.put("_id", "rec15"); record15.put("chunk_text", "Leonardo da Vinci painted the Mona Lisa."); record15.put("category", "art"); HashMap record16 = new HashMap<>(); record16.put("_id", "rec16"); record16.put("chunk_text", "The internet revolutionized communication and information sharing."); record16.put("category", "technology"); HashMap record17 = new HashMap<>(); record17.put("_id", "rec17"); record17.put("chunk_text", "The Pyramids of Giza are among the Seven Wonders of the Ancient World."); record17.put("category", "history"); HashMap record18 = new HashMap<>(); record18.put("_id", "rec18"); record18.put("chunk_text", "Dogs have an incredible sense of smell, much stronger than humans."); record18.put("category", "biology"); HashMap record19 = new HashMap<>(); record19.put("_id", "rec19"); record19.put("chunk_text", "The Pacific Ocean is the largest and deepest ocean on Earth."); record19.put("category", "geography"); HashMap record20 = new HashMap<>(); record20.put("_id", "rec20"); record20.put("chunk_text", "Chess is a strategic game that originated in India."); record20.put("category", "games"); HashMap record21 = new HashMap<>(); record21.put("_id", "rec21"); record21.put("chunk_text", "The Statue of Liberty was a gift from France to the United States."); record21.put("category", "history"); HashMap record22 = new HashMap<>(); record22.put("_id", "rec22"); record22.put("chunk_text", "Coffee contains caffeine, a natural stimulant."); record22.put("category", "food science"); HashMap record23 = new HashMap<>(); record23.put("_id", "rec23"); record23.put("chunk_text", "Thomas Edison invented the practical electric light bulb."); record23.put("category", "inventions"); HashMap record24 = new HashMap<>(); record24.put("_id", "rec24"); record24.put("chunk_text", "The moon influences ocean tides due to gravitational pull."); record24.put("category", "astronomy"); HashMap record25 = new HashMap<>(); record25.put("_id", "rec25"); record25.put("chunk_text", "DNA carries genetic information for all living organisms."); record25.put("category", "biology"); HashMap record26 = new HashMap<>(); record26.put("_id", "rec26"); record26.put("chunk_text", "Rome was once the center of a vast empire."); record26.put("category", "history"); HashMap record27 = new HashMap<>(); record27.put("_id", "rec27"); record27.put("chunk_text", "The Wright brothers pioneered human flight in 1903."); record27.put("category", "inventions"); HashMap record28 = new HashMap<>(); record28.put("_id", "rec28"); record28.put("chunk_text", "Bananas are a good source of potassium."); record28.put("category", "nutrition"); HashMap record29 = new HashMap<>(); record29.put("_id", "rec29"); record29.put("chunk_text", "The stock market fluctuates based on supply and demand."); record29.put("category", "economics"); HashMap record30 = new HashMap<>(); record30.put("_id", "rec30"); record30.put("chunk_text", "A compass needle points toward the magnetic north pole."); record30.put("category", "navigation"); HashMap record31 = new HashMap<>(); record31.put("_id", "rec31"); record31.put("chunk_text", "The universe is expanding, according to the Big Bang theory."); record31.put("category", "astronomy"); HashMap record32 = new HashMap<>(); record32.put("_id", "rec32"); record32.put("chunk_text", "Elephants have excellent memory and strong social bonds."); record32.put("category", "biology"); HashMap record33 = new HashMap<>(); record33.put("_id", "rec33"); record33.put("chunk_text", "The violin is a string instrument commonly used in orchestras."); record33.put("category", "music"); HashMap record34 = new HashMap<>(); record34.put("_id", "rec34"); record34.put("chunk_text", "The heart pumps blood throughout the human body."); record34.put("category", "biology"); HashMap record35 = new HashMap<>(); record35.put("_id", "rec35"); record35.put("chunk_text", "Ice cream melts when exposed to heat."); record35.put("category", "food science"); HashMap record36 = new HashMap<>(); record36.put("_id", "rec36"); record36.put("chunk_text", "Solar panels convert sunlight into electricity."); record36.put("category", "technology"); HashMap record37 = new HashMap<>(); record37.put("_id", "rec37"); record37.put("chunk_text", "The French Revolution began in 1789."); record37.put("category", "history"); HashMap record38 = new HashMap<>(); record38.put("_id", "rec38"); record38.put("chunk_text", "The Taj Mahal is a mausoleum built by Emperor Shah Jahan."); record38.put("category", "history"); HashMap record39 = new HashMap<>(); record39.put("_id", "rec39"); record39.put("chunk_text", "Rainbows are caused by light refracting through water droplets."); record39.put("category", "physics"); HashMap record40 = new HashMap<>(); record40.put("_id", "rec40"); record40.put("chunk_text", "Mount Everest is the tallest mountain in the world."); record40.put("category", "geography"); HashMap record41 = new HashMap<>(); record41.put("_id", "rec41"); record41.put("chunk_text", "Octopuses are highly intelligent marine creatures."); record41.put("category", "biology"); HashMap record42 = new HashMap<>(); record42.put("_id", "rec42"); record42.put("chunk_text", "The speed of sound is around 343 meters per second in air."); record42.put("category", "physics"); HashMap record43 = new HashMap<>(); record43.put("_id", "rec43"); record43.put("chunk_text", "Gravity keeps planets in orbit around the sun."); record43.put("category", "astronomy"); HashMap record44 = new HashMap<>(); record44.put("_id", "rec44"); record44.put("chunk_text", "The Mediterranean diet is considered one of the healthiest in the world."); record44.put("category", "nutrition"); HashMap record45 = new HashMap<>(); record45.put("_id", "rec45"); record45.put("chunk_text", "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure."); record45.put("category", "literature"); HashMap record46 = new HashMap<>(); record46.put("_id", "rec46"); record46.put("chunk_text", "The human body is made up of about 60% water."); record46.put("category", "biology"); HashMap record47 = new HashMap<>(); record47.put("_id", "rec47"); record47.put("chunk_text", "The Industrial Revolution transformed manufacturing and transportation."); record47.put("category", "history"); HashMap record48 = new HashMap<>(); record48.put("_id", "rec48"); record48.put("chunk_text", "Vincent van Gogh painted Starry Night."); record48.put("category", "art"); HashMap record49 = new HashMap<>(); record49.put("_id", "rec49"); record49.put("chunk_text", "Airplanes fly due to the principles of lift and aerodynamics."); record49.put("category", "physics"); HashMap record50 = new HashMap<>(); record50.put("_id", "rec50"); record50.put("chunk_text", "Renewable energy sources include wind, solar, and hydroelectric power."); record50.put("category", "energy"); upsertRecords.add(record1); upsertRecords.add(record2); upsertRecords.add(record3); upsertRecords.add(record4); upsertRecords.add(record5); upsertRecords.add(record6); upsertRecords.add(record7); upsertRecords.add(record8); upsertRecords.add(record9); upsertRecords.add(record10); upsertRecords.add(record11); upsertRecords.add(record12); upsertRecords.add(record13); upsertRecords.add(record14); upsertRecords.add(record15); upsertRecords.add(record16); upsertRecords.add(record17); upsertRecords.add(record18); upsertRecords.add(record19); upsertRecords.add(record20); upsertRecords.add(record21); upsertRecords.add(record22); upsertRecords.add(record23); upsertRecords.add(record24); upsertRecords.add(record25); upsertRecords.add(record26); upsertRecords.add(record27); upsertRecords.add(record28); upsertRecords.add(record29); upsertRecords.add(record30); upsertRecords.add(record31); upsertRecords.add(record32); upsertRecords.add(record33); upsertRecords.add(record34); upsertRecords.add(record35); upsertRecords.add(record36); upsertRecords.add(record37); upsertRecords.add(record38); upsertRecords.add(record39); upsertRecords.add(record40); upsertRecords.add(record41); upsertRecords.add(record42); upsertRecords.add(record43); upsertRecords.add(record44); upsertRecords.add(record45); upsertRecords.add(record46); upsertRecords.add(record47); upsertRecords.add(record48); upsertRecords.add(record49); upsertRecords.add(record50); ``` ```go Go [expandable] theme={null} // Add to the main function: records := []*pinecone.IntegratedRecord{ { "_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" }, { "_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" }, { "_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science" }, { "_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology" }, { "_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" }, { "_id": "rec6", "chunk_text": "Water boils at 100°C under standard atmospheric pressure.", "category": "physics" }, { "_id": "rec7", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history" }, { "_id": "rec8", "chunk_text": "Honey never spoils due to its low moisture content and acidity.", "category": "food science" }, { "_id": "rec9", "chunk_text": "The speed of light in a vacuum is approximately 299,792 km/s.", "category": "physics" }, { "_id": "rec10", "chunk_text": "Newton's laws describe the motion of objects.", "category": "physics" }, { "_id": "rec11", "chunk_text": "The human brain has approximately 86 billion neurons.", "category": "biology" }, { "_id": "rec12", "chunk_text": "The Amazon Rainforest is one of the most biodiverse places on Earth.", "category": "geography" }, { "_id": "rec13", "chunk_text": "Black holes have gravitational fields so strong that not even light can escape.", "category": "astronomy" }, { "_id": "rec14", "chunk_text": "The periodic table organizes elements based on their atomic number.", "category": "chemistry" }, { "_id": "rec15", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" }, { "_id": "rec16", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology" }, { "_id": "rec17", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" }, { "_id": "rec18", "chunk_text": "Dogs have an incredible sense of smell, much stronger than humans.", "category": "biology" }, { "_id": "rec19", "chunk_text": "The Pacific Ocean is the largest and deepest ocean on Earth.", "category": "geography" }, { "_id": "rec20", "chunk_text": "Chess is a strategic game that originated in India.", "category": "games" }, { "_id": "rec21", "chunk_text": "The Statue of Liberty was a gift from France to the United States.", "category": "history" }, { "_id": "rec22", "chunk_text": "Coffee contains caffeine, a natural stimulant.", "category": "food science" }, { "_id": "rec23", "chunk_text": "Thomas Edison invented the practical electric light bulb.", "category": "inventions" }, { "_id": "rec24", "chunk_text": "The moon influences ocean tides due to gravitational pull.", "category": "astronomy" }, { "_id": "rec25", "chunk_text": "DNA carries genetic information for all living organisms.", "category": "biology" }, { "_id": "rec26", "chunk_text": "Rome was once the center of a vast empire.", "category": "history" }, { "_id": "rec27", "chunk_text": "The Wright brothers pioneered human flight in 1903.", "category": "inventions" }, { "_id": "rec28", "chunk_text": "Bananas are a good source of potassium.", "category": "nutrition" }, { "_id": "rec29", "chunk_text": "The stock market fluctuates based on supply and demand.", "category": "economics" }, { "_id": "rec30", "chunk_text": "A compass needle points toward the magnetic north pole.", "category": "navigation" }, { "_id": "rec31", "chunk_text": "The universe is expanding, according to the Big Bang theory.", "category": "astronomy" }, { "_id": "rec32", "chunk_text": "Elephants have excellent memory and strong social bonds.", "category": "biology" }, { "_id": "rec33", "chunk_text": "The violin is a string instrument commonly used in orchestras.", "category": "music" }, { "_id": "rec34", "chunk_text": "The heart pumps blood throughout the human body.", "category": "biology" }, { "_id": "rec35", "chunk_text": "Ice cream melts when exposed to heat.", "category": "food science" }, { "_id": "rec36", "chunk_text": "Solar panels convert sunlight into electricity.", "category": "technology" }, { "_id": "rec37", "chunk_text": "The French Revolution began in 1789.", "category": "history" }, { "_id": "rec38", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" }, { "_id": "rec39", "chunk_text": "Rainbows are caused by light refracting through water droplets.", "category": "physics" }, { "_id": "rec40", "chunk_text": "Mount Everest is the tallest mountain in the world.", "category": "geography" }, { "_id": "rec41", "chunk_text": "Octopuses are highly intelligent marine creatures.", "category": "biology" }, { "_id": "rec42", "chunk_text": "The speed of sound is around 343 meters per second in air.", "category": "physics" }, { "_id": "rec43", "chunk_text": "Gravity keeps planets in orbit around the sun.", "category": "astronomy" }, { "_id": "rec44", "chunk_text": "The Mediterranean diet is considered one of the healthiest in the world.", "category": "nutrition" }, { "_id": "rec45", "chunk_text": "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", "category": "literature" }, { "_id": "rec46", "chunk_text": "The human body is made up of about 60% water.", "category": "biology" }, { "_id": "rec47", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation.", "category": "history" }, { "_id": "rec48", "chunk_text": "Vincent van Gogh painted Starry Night.", "category": "art" }, { "_id": "rec49", "chunk_text": "Airplanes fly due to the principles of lift and aerodynamics.", "category": "physics" }, { "_id": "rec50", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" }, } ``` ```csharp C# [expandable] theme={null} var records = new List { new UpsertRecord { Id = "rec1", AdditionalProperties = { ["chunk_text"] = "The Eiffel Tower was completed in 1889 and stands in Paris, France.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec2", AdditionalProperties = { ["chunk_text"] = "Photosynthesis allows plants to convert sunlight into energy.", ["category"] = "science", }, }, new UpsertRecord { Id = "rec3", AdditionalProperties = { ["chunk_text"] = "Albert Einstein developed the theory of relativity.", ["category"] = "science", }, }, new UpsertRecord { Id = "rec4", AdditionalProperties = { ["chunk_text"] = "The mitochondrion is often called the powerhouse of the cell.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec5", AdditionalProperties = { ["chunk_text"] = "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", ["category"] = "literature", }, }, new UpsertRecord { Id = "rec6", AdditionalProperties = { ["chunk_text"] = "Water boils at 100°C under standard atmospheric pressure.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec7", AdditionalProperties = { ["chunk_text"] = "The Great Wall of China was built to protect against invasions.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec8", AdditionalProperties = { ["chunk_text"] = "Honey never spoils due to its low moisture content and acidity.", ["category"] = "food science", }, }, new UpsertRecord { Id = "rec9", AdditionalProperties = { ["chunk_text"] = "The speed of light in a vacuum is approximately 299,792 km/s.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec10", AdditionalProperties = { ["chunk_text"] = "Newton's laws describe the motion of objects.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec11", AdditionalProperties = { ["chunk_text"] = "The human brain has approximately 86 billion neurons.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec12", AdditionalProperties = { ["chunk_text"] = "The Amazon Rainforest is one of the most biodiverse places on Earth.", ["category"] = "geography", }, }, new UpsertRecord { Id = "rec13", AdditionalProperties = { ["chunk_text"] = "Black holes have gravitational fields so strong that not even light can escape.", ["category"] = "astronomy", }, }, new UpsertRecord { Id = "rec14", AdditionalProperties = { ["chunk_text"] = "The periodic table organizes elements based on their atomic number.", ["category"] = "chemistry", }, }, new UpsertRecord { Id = "rec15", AdditionalProperties = { ["chunk_text"] = "Leonardo da Vinci painted the Mona Lisa.", ["category"] = "art", }, }, new UpsertRecord { Id = "rec16", AdditionalProperties = { ["chunk_text"] = "The internet revolutionized communication and information sharing.", ["category"] = "technology", }, }, new UpsertRecord { Id = "rec17", AdditionalProperties = { ["chunk_text"] = "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec18", AdditionalProperties = { ["chunk_text"] = "Dogs have an incredible sense of smell, much stronger than humans.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec19", AdditionalProperties = { ["chunk_text"] = "The Pacific Ocean is the largest and deepest ocean on Earth.", ["category"] = "geography", }, }, new UpsertRecord { Id = "rec20", AdditionalProperties = { ["chunk_text"] = "Chess is a strategic game that originated in India.", ["category"] = "games", }, }, new UpsertRecord { Id = "rec21", AdditionalProperties = { ["chunk_text"] = "The Statue of Liberty was a gift from France to the United States.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec22", AdditionalProperties = { ["chunk_text"] = "Coffee contains caffeine, a natural stimulant.", ["category"] = "food science", }, }, new UpsertRecord { Id = "rec23", AdditionalProperties = { ["chunk_text"] = "Thomas Edison invented the practical electric light bulb.", ["category"] = "inventions", }, }, new UpsertRecord { Id = "rec24", AdditionalProperties = { ["chunk_text"] = "The moon influences ocean tides due to gravitational pull.", ["category"] = "astronomy", }, }, new UpsertRecord { Id = "rec25", AdditionalProperties = { ["chunk_text"] = "DNA carries genetic information for all living organisms.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec26", AdditionalProperties = { ["chunk_text"] = "Rome was once the center of a vast empire.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec27", AdditionalProperties = { ["chunk_text"] = "The Wright brothers pioneered human flight in 1903.", ["category"] = "inventions", }, }, new UpsertRecord { Id = "rec28", AdditionalProperties = { ["chunk_text"] = "Bananas are a good source of potassium.", ["category"] = "nutrition", }, }, new UpsertRecord { Id = "rec29", AdditionalProperties = { ["chunk_text"] = "The stock market fluctuates based on supply and demand.", ["category"] = "economics", }, }, new UpsertRecord { Id = "rec30", AdditionalProperties = { ["chunk_text"] = "A compass needle points toward the magnetic north pole.", ["category"] = "navigation", }, }, new UpsertRecord { Id = "rec31", AdditionalProperties = { ["chunk_text"] = "The universe is expanding, according to the Big Bang theory.", ["category"] = "astronomy", }, }, new UpsertRecord { Id = "rec32", AdditionalProperties = { ["chunk_text"] = "Elephants have excellent memory and strong social bonds.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec33", AdditionalProperties = { ["chunk_text"] = "The violin is a string instrument commonly used in orchestras.", ["category"] = "music", }, }, new UpsertRecord { Id = "rec34", AdditionalProperties = { ["chunk_text"] = "The heart pumps blood throughout the human body.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec35", AdditionalProperties = { ["chunk_text"] = "Ice cream melts when exposed to heat.", ["category"] = "food science", }, }, new UpsertRecord { Id = "rec36", AdditionalProperties = { ["chunk_text"] = "Solar panels convert sunlight into electricity.", ["category"] = "technology", }, }, new UpsertRecord { Id = "rec37", AdditionalProperties = { ["chunk_text"] = "The French Revolution began in 1789.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec38", AdditionalProperties = { ["chunk_text"] = "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec39", AdditionalProperties = { ["chunk_text"] = "Rainbows are caused by light refracting through water droplets.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec40", AdditionalProperties = { ["chunk_text"] = "Mount Everest is the tallest mountain in the world.", ["category"] = "geography", }, }, new UpsertRecord { Id = "rec41", AdditionalProperties = { ["chunk_text"] = "Octopuses are highly intelligent marine creatures.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec42", AdditionalProperties = { ["chunk_text"] = "The speed of sound is around 343 meters per second in air.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec43", AdditionalProperties = { ["chunk_text"] = "Gravity keeps planets in orbit around the sun.", ["category"] = "astronomy", }, }, new UpsertRecord { Id = "rec44", AdditionalProperties = { ["chunk_text"] = "The Mediterranean diet is considered one of the healthiest in the world.", ["category"] = "nutrition", }, }, new UpsertRecord { Id = "rec45", AdditionalProperties = { ["chunk_text"] = "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", ["category"] = "literature", }, }, new UpsertRecord { Id = "rec46", AdditionalProperties = { ["chunk_text"] = "The human body is made up of about 60% water.", ["category"] = "biology", }, }, new UpsertRecord { Id = "rec47", AdditionalProperties = { ["chunk_text"] = "The Industrial Revolution transformed manufacturing and transportation.", ["category"] = "history", }, }, new UpsertRecord { Id = "rec48", AdditionalProperties = { ["chunk_text"] = "Vincent van Gogh painted Starry Night.", ["category"] = "art", }, }, new UpsertRecord { Id = "rec49", AdditionalProperties = { ["chunk_text"] = "Airplanes fly due to the principles of lift and aerodynamics.", ["category"] = "physics", }, }, new UpsertRecord { Id = "rec50", AdditionalProperties = { ["chunk_text"] = "Renewable energy sources include wind, solar, and hydroelectric power.", ["category"] = "energy", }, }, }; ``` [Upsert](/guides/index-data/upsert-data) the sample dataset into a new [namespace](/guides/index-data/indexing-overview#namespaces) in your index. Because your index is integrated with an embedding model, you provide the textual statements and Pinecone converts them to dense vectors automatically. ```python Python theme={null} # Target the index dense_index = pc.Index(index_name) # Upsert the records into a namespace dense_index.upsert_records("example-namespace", records) ``` ```javascript JavaScript theme={null} // Target the index const index = pc.index(indexName).namespace("example-namespace"); // Upsert the records into a namespace await index.upsertRecords(records); ``` ```java Java theme={null} // Add to the Quickstart class: // Target the index Index index = new Index(config, connection, "quickstart-java"); // Upsert the records into a namespace index.upsertRecords("example-namespace", upsertRecords); ``` ```go Go theme={null} // Add to the main function: // Target the index idxModel, err := pc.DescribeIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", indexName, err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v: %v", idxModel.Host, err) } // Upsert the records into a namespace err = idxConnection.UpsertRecords(ctx, records) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } ``` ```csharp C# theme={null} // Upsert the records into a namespace await index.UpsertRecordsAsync( "example-namespace", records ); ``` To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. 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](/guides/index-data/check-data-freshness) to check if the current vector count matches the number of vectors you upserted (50): ```python Python theme={null} # Wait for the upserted vectors to be indexed import time time.sleep(10) # View stats for the index stats = dense_index.describe_index_stats() print(stats) ``` ```javascript JavaScript theme={null} // Wait for the upserted vectors to be indexed await new Promise(resolve => setTimeout(resolve, 10000)); // View stats for the index const stats = await index.describeIndexStats(); console.log(stats); ``` ```java Java theme={null} // Add to the Quickstart class: // Wait for upserted vectors to be indexed Thread.sleep(5000); // View stats for the index DescribeIndexStatsResponse indexStatsResponse = index.describeIndexStats(); System.out.println(indexStatsResponse); ``` ```go Go theme={null} // Add to the main function: // View stats for the index stats, err := idxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", indexName, err) } else { fmt.Printf("%+v", prettifyStruct(*stats)) } ``` ```csharp C# theme={null} var indexStatsResponse = await index.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine(indexStatsResponse); ``` The response looks like this: ```python Python theme={null} {'dimension': 1024, 'index_fullness': 0.0, 'metric': 'cosine', 'namespaces': {'example-namespace': {'vector_count': 50}}, 'total_vector_count': 50, 'vector_type': 'dense'} ``` ```javascript JavaScript theme={null} { namespaces: { 'example-namespace': { recordCount: 50 } }, dimension: 1024, indexFullness: 0, totalRecordCount: 50 } ``` ```java Java theme={null} namespaces { key: "example-namespace" value { vector_count: 50 } } dimension: 1024 total_vector_count: 50 metric: "cosine" vector_type: "dense" ``` ```go Go theme={null} { "dimension": 1024, "index_fullness": 0, "total_vector_count": 50, "namespaces": { "example-namespace": { "vector_count": 50 } } } ``` ```csharp C# theme={null} { "namespaces": { "example-namespace": { "vectorCount": 50 } }, "dimension": 1024, "indexFullness": 0, "totalVectorCount": 50, "metric": "cosine", "vectorType": "dense" } ``` ## 5. Semantic search [Search the dense index](/guides/search/semantic-search) for ten records that are most semantically similar to the query, "Famous historical structures and monuments". Again, because your 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} # Define the query query = "Famous historical structures and monuments" # Search the dense index results = dense_index.search( namespace="example-namespace", query={ "top_k": 10, "inputs": { 'text': query } } ) # Print the results for hit in results['result']['hits']: print(f"id: {hit['_id']:<5} | score: {round(hit['_score'], 2):<5} | category: {hit['fields']['category']:<10} | text: {hit['fields']['chunk_text']:<50}") ``` ```javascript JavaScript theme={null} // Define the query const query = 'Famous historical structures and monuments'; // Search the dense index const results = await index.searchRecords({ query: { topK: 10, inputs: { text: query }, }, }); // Print the results results.result.hits.forEach(hit => { console.log(`id: ${hit.id}, score: ${hit.score.toFixed(2)}, category: ${hit.fields.category}, text: ${hit.fields.chunk_text}`); }); ``` ```java Java theme={null} // Add to the Quickstart class: // Define the query String query = "Famous historical structures and monuments"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the dense index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 10, null, null); // Print the results System.out.println(recordsResponse); ``` ```go Go theme={null} // Add to the main function: // Define the query query := "Famous historical structures and monuments" // Search the dense index res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 10, Inputs: &map[string]interface{}{ "text": query, }, }, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) ``` ```csharp C# theme={null} // Search the dense index var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 10, Inputs = new Dictionary { { "text", "Famous historical structures and monuments" } }, }, Fields = ["category", "chunk_text"], } ); Console.WriteLine(response); ``` Notice that most of the results are about historical structures and monuments. However, a few unrelated statements are included as well and are ranked high in the list, for example, a statement about Shakespeare. ```console Python theme={null} id: rec17 | score: 0.24 | category: history | text: The Pyramids of Giza are among the Seven Wonders of the Ancient World. id: rec38 | score: 0.19 | category: history | text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan. id: rec5 | score: 0.19 | category: literature | text: Shakespeare wrote many famous plays, including Hamlet and Macbeth. id: rec15 | score: 0.11 | category: art | text: Leonardo da Vinci painted the Mona Lisa. id: rec50 | score: 0.1 | category: energy | text: Renewable energy sources include wind, solar, and hydroelectric power. id: rec26 | score: 0.09 | category: history | text: Rome was once the center of a vast empire. id: rec47 | score: 0.08 | category: history | text: The Industrial Revolution transformed manufacturing and transportation. id: rec7 | score: 0.07 | category: history | text: The Great Wall of China was built to protect against invasions. id: rec1 | score: 0.07 | category: history | text: The Eiffel Tower was completed in 1889 and stands in Paris, France. id: rec3 | score: 0.07 | category: science | text: Albert Einstein developed the theory of relativity. ``` ```console JavaScript theme={null} id: rec17, score: 0.24, text: The Pyramids of Giza are among the Seven Wonders of the Ancient World., category: history id: rec38, score: 0.19, text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan., category: history id: rec5, score: 0.19, text: Shakespeare wrote many famous plays, including Hamlet and Macbeth., category: literature id: rec15, score: 0.11, text: Leonardo da Vinci painted the Mona Lisa., category: art id: rec50, score: 0.10, text: Renewable energy sources include wind, solar, and hydroelectric power., category: energy id: rec26, score: 0.09, text: Rome was once the center of a vast empire., category: history id: rec47, score: 0.08, text: The Industrial Revolution transformed manufacturing and transportation., category: history id: rec7, score: 0.07, text: The Great Wall of China was built to protect against invasions., category: history id: rec1, score: 0.07, text: The Eiffel Tower was completed in 1889 and stands in Paris, France., category: history id: rec3, score: 0.07, text: Albert Einstein developed the theory of relativity., category: science ``` ```java Java [expandable] theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec17 score: 0.77387625 fields: {category=history, chunk_text=The Pyramids of Giza are among the Seven Wonders of the Ancient World.} additionalProperties: null }, class Hit { id: rec1 score: 0.77372295 fields: {category=history, chunk_text=The Eiffel Tower was completed in 1889 and stands in Paris, France.} additionalProperties: null }, class Hit { id: rec38 score: 0.75988203 fields: {category=history, chunk_text=The Taj Mahal is a mausoleum built by Emperor Shah Jahan.} additionalProperties: null }, class Hit { id: rec5 score: 0.75516135 fields: {category=literature, chunk_text=Shakespeare wrote many famous plays, including Hamlet and Macbeth.} additionalProperties: null }, class Hit { id: rec26 score: 0.7550185 fields: {category=history, chunk_text=Rome was once the center of a vast empire.} additionalProperties: null }, class Hit { id: rec45 score: 0.73588645 fields: {category=literature, chunk_text=A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.} additionalProperties: null }, class Hit { id: rec4 score: 0.730563 fields: {category=biology, chunk_text=The mitochondrion is often called the powerhouse of the cell.} additionalProperties: null }, class Hit { id: rec7 score: 0.73037535 fields: {category=history, chunk_text=The Great Wall of China was built to protect against invasions.} additionalProperties: null }, class Hit { id: rec32 score: 0.72860974 fields: {category=biology, chunk_text=Elephants have excellent memory and strong social bonds.} additionalProperties: null }, class Hit { id: rec47 score: 0.7285921 fields: {category=history, chunk_text=The Industrial Revolution transformed manufacturing and transportation.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 rerankUnits: null additionalProperties: null } additionalProperties: null } ``` ```json Go [expandable] theme={null} { "result": { "hits": [ { "_id": "rec17", "_score": 0.24442708, "fields": { "category": "history", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World." } }, { "_id": "rec38", "_score": 0.1876694, "fields": { "category": "history", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan." } }, { "_id": "rec5", "_score": 0.18504046, "fields": { "category": "literature", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth." } }, { "_id": "rec15", "_score": 0.109251045, "fields": { "category": "art", "chunk_text": "Leonardo da Vinci painted the Mona Lisa." } }, { "_id": "rec50", "_score": 0.098952696, "fields": { "category": "energy", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power." } }, { "_id": "rec26", "_score": 0.085251465, "fields": { "category": "history", "chunk_text": "Rome was once the center of a vast empire." } }, { "_id": "rec47", "_score": 0.07533597, "fields": { "category": "history", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation." } }, { "_id": "rec7", "_score": 0.06859385, "fields": { "category": "history", "chunk_text": "The Great Wall of China was built to protect against invasions." } }, { "_id": "rec1", "_score": 0.06831257, "fields": { "category": "history", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France." } }, { "_id": "rec3", "_score": 0.06689669, "fields": { "category": "science", "chunk_text": "Albert Einstein developed the theory of relativity." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8 } } ``` ```csharp C# [expandable] theme={null} { "result": { "hits": [ { "_id": "rec17", "_score": 0.27985704, "fields": { "category": "history", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World." } }, { "_id": "rec38", "_score": 0.18836586, "fields": { "category": "history", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan." } }, { "_id": "rec5", "_score": 0.18140909, "fields": { "category": "literature", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth." } }, { "_id": "rec15", "_score": 0.09603156, "fields": { "category": "art", "chunk_text": "Leonardo da Vinci painted the Mona Lisa." } }, { "_id": "rec50", "_score": 0.091406636, "fields": { "category": "energy", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power." } }, { "_id": "rec1", "_score": 0.0828001, "fields": { "category": "history", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France." } }, { "_id": "rec26", "_score": 0.081794746, "fields": { "category": "history", "chunk_text": "Rome was once the center of a vast empire." } }, { "_id": "rec7", "_score": 0.078153394, "fields": { "category": "history", "chunk_text": "The Great Wall of China was built to protect against invasions." } }, { "_id": "rec47", "_score": 0.06604649, "fields": { "category": "history", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation." } }, { "_id": "rec21", "_score": 0.056735568, "fields": { "category": "history", "chunk_text": "The Statue of Liberty was a gift from France to the United States." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8 } } ``` ## 6. Rerank results To get a more accurate ranking, search again but this time [rerank the initial results](/guides/search/rerank-results) based on their relevance to the query. ```python Python {10-14} theme={null} # Search the dense index and rerank results reranked_results = dense_index.search( namespace="example-namespace", query={ "top_k": 10, "inputs": { 'text': query } }, rerank={ "model": "bge-reranker-v2-m3", "top_n": 10, "rank_fields": ["chunk_text"] } ) # Print the reranked results for hit in reranked_results['result']['hits']: print(f"id: {hit['_id']}, score: {round(hit['_score'], 2)}, text: {hit['fields']['chunk_text']}, category: {hit['fields']['category']}") ``` ```javascript JavaScript {7-11} theme={null} // Search the dense index and rerank results const rerankedResults = await index.searchRecords({ query: { topK: 10, inputs: { text: query }, }, rerank: { model: 'bge-reranker-v2-m3', topN: 10, rankFields: ['chunk_text'], }, }); // Print the reranked results rerankedResults.result.hits.forEach(hit => { console.log(`id: ${hit.id}, score: ${hit.score.toFixed(2)}, text: ${hit.fields.chunk_text}, category: ${hit.fields.category}`); }); ``` ```java Java {9} theme={null} // Add to the Quickstart class: // Define the rerank parameters ListrankFields = new ArrayList<>(); rankFields.add("chunk_text"); SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank() .query(query) .model("bge-reranker-v2-m3") .topN(10) .rankFields(rankFields); // Search the dense index and rerank results SearchRecordsResponse recordsResponseReranked = index.searchRecordsByText(query, "example-namespace", fields, 10, null, rerank ); // Print the reranked results System.out.println(recordsResponseReranked); ``` ```go Go {11-15} theme={null} // Add to the main function: // Search the dense index and rerank results topN := int32(10) resReranked, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 10, Inputs: &map[string]interface{}{ "text": query, }, }, Rerank: &pinecone.SearchRecordsRerank{ Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(resReranked)) ``` ```csharp C# {12-17} theme={null} // Search the dense index and rerank results var responseReranked = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 10, Inputs = new Dictionary { { "text", "Famous historical structures and monuments" } }, }, Fields = ["category", "chunk_text"], Rerank = new SearchRecordsRequestRerank { Model = "bge-reranker-v2-m3", TopN = 10, RankFields = ["chunk_text"], } } ); Console.WriteLine(responseReranked); ``` Notice that all of the most relevant results about historical structures and monuments are now ranked highest. ```console Python theme={null} id: rec1 | score: 0.11 | category: history | text: The Eiffel Tower was completed in 1889 and stands in Paris, France. id: rec38 | score: 0.06 | category: history | text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan. id: rec7 | score: 0.06 | category: history | text: The Great Wall of China was built to protect against invasions. id: rec17 | score: 0.02 | category: history | text: The Pyramids of Giza are among the Seven Wonders of the Ancient World. id: rec26 | score: 0.01 | category: history | text: Rome was once the center of a vast empire. id: rec15 | score: 0.01 | category: art | text: Leonardo da Vinci painted the Mona Lisa. id: rec5 | score: 0.0 | category: literature | text: Shakespeare wrote many famous plays, including Hamlet and Macbeth. id: rec47 | score: 0.0 | category: history | text: The Industrial Revolution transformed manufacturing and transportation. id: rec50 | score: 0.0 | category: energy | text: Renewable energy sources include wind, solar, and hydroelectric power. id: rec3 | score: 0.0 | category: science | text: Albert Einstein developed the theory of relativity. ``` ```console JavaScript theme={null} id: rec1, score: 0.11, text: The Eiffel Tower was completed in 1889 and stands in Paris, France., category: history id: rec38, score: 0.06, text: The Taj Mahal is a mausoleum built by Emperor Shah Jahan., category: history id: rec7, score: 0.06, text: The Great Wall of China was built to protect against invasions., category: history id: rec17, score: 0.02, text: The Pyramids of Giza are among the Seven Wonders of the Ancient World., category: history id: rec26, score: 0.01, text: Rome was once the center of a vast empire., category: history id: rec15, score: 0.01, text: Leonardo da Vinci painted the Mona Lisa., category: art id: rec5, score: 0.00, text: Shakespeare wrote many famous plays, including Hamlet and Macbeth., category: literature id: rec47, score: 0.00, text: The Industrial Revolution transformed manufacturing and transportation., category: history id: rec50, score: 0.00, text: Renewable energy sources include wind, solar, and hydroelectric power., category: energy id: rec3, score: 0.00, text: Albert Einstein developed the theory of relativity., category: science ``` ```java Java [expandable] theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec1 score: 0.10687689 fields: {category=history, chunk_text=The Eiffel Tower was completed in 1889 and stands in Paris, France.} additionalProperties: null }, class Hit { id: rec38 score: 0.06418265 fields: {category=history, chunk_text=The Taj Mahal is a mausoleum built by Emperor Shah Jahan.} additionalProperties: null }, class Hit { id: rec7 score: 0.062445287 fields: {category=history, chunk_text=The Great Wall of China was built to protect against invasions.} additionalProperties: null }, class Hit { id: rec17 score: 0.0153063545 fields: {category=history, chunk_text=The Pyramids of Giza are among the Seven Wonders of the Ancient World.} additionalProperties: null }, class Hit { id: rec26 score: 0.010652511 fields: {category=history, chunk_text=Rome was once the center of a vast empire.} additionalProperties: null }, class Hit { id: rec5 score: 3.194182E-5 fields: {category=literature, chunk_text=Shakespeare wrote many famous plays, including Hamlet and Macbeth.} additionalProperties: null }, class Hit { id: rec47 score: 1.7502925E-5 fields: {category=history, chunk_text=The Industrial Revolution transformed manufacturing and transportation.} additionalProperties: null }, class Hit { id: rec32 score: 1.631454E-5 fields: {category=biology, chunk_text=Elephants have excellent memory and strong social bonds.} additionalProperties: null }, class Hit { id: rec4 score: 1.6187581E-5 fields: {category=biology, chunk_text=The mitochondrion is often called the powerhouse of the cell.} additionalProperties: null }, class Hit { id: rec45 score: 1.6061611E-5 fields: {category=literature, chunk_text=A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 rerankUnits: 1 additionalProperties: null } additionalProperties: null } ``` ```json Go [expandable] theme={null} { "result": { "hits": [ { "_id": "rec1", "_score": 0.10743748, "fields": { "category": "history", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France." } }, { "_id": "rec38", "_score": 0.064535476, "fields": { "category": "history", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan." } }, { "_id": "rec7", "_score": 0.062445287, "fields": { "category": "history", "chunk_text": "The Great Wall of China was built to protect against invasions." } }, { "_id": "rec17", "_score": 0.0153063545, "fields": { "category": "history", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World." } }, { "_id": "rec26", "_score": 0.010652511, "fields": { "category": "history", "chunk_text": "Rome was once the center of a vast empire." } }, { "_id": "rec15", "_score": 0.007876706, "fields": { "category": "art", "chunk_text": "Leonardo da Vinci painted the Mona Lisa." } }, { "_id": "rec5", "_score": 0.00003194182, "fields": { "category": "literature", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth." } }, { "_id": "rec47", "_score": 0.000017502925, "fields": { "category": "history", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation." } }, { "_id": "rec50", "_score": 0.00001631454, "fields": { "category": "energy", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power." } }, { "_id": "rec3", "_score": 0.000015936621, "fields": { "category": "science", "chunk_text": "Albert Einstein developed the theory of relativity." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8, "rerank_units": 1 } } ``` ```csharp C# [expandable] theme={null} { "result": { "hits": [ { "_id": "rec1", "_score": 0.10687689, "fields": { "category": "history", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France." } }, { "_id": "rec38", "_score": 0.064535476, "fields": { "category": "history", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan." } }, { "_id": "rec7", "_score": 0.062445287, "fields": { "category": "history", "chunk_text": "The Great Wall of China was built to protect against invasions." } }, { "_id": "rec21", "_score": 0.018511046, "fields": { "category": "history", "chunk_text": "The Statue of Liberty was a gift from France to the United States." } }, { "_id": "rec17", "_score": 0.0153063545, "fields": { "category": "history", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World." } }, { "_id": "rec26", "_score": 0.010652511, "fields": { "category": "history", "chunk_text": "Rome was once the center of a vast empire." } }, { "_id": "rec15", "_score": 0.007876706, "fields": { "category": "art", "chunk_text": "Leonardo da Vinci painted the Mona Lisa." } }, { "_id": "rec5", "_score": 0.00003194182, "fields": { "category": "literature", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth." } }, { "_id": "rec47", "_score": 0.000017502925, "fields": { "category": "history", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation." } }, { "_id": "rec50", "_score": 0.00001631454, "fields": { "category": "energy", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8, "rerank_units": 1 } } ``` ## 7. Improve results [Reranking results](/guides/search/rerank-results) is one of the most effective ways to improve search accuracy and relevance, but there are many other techniques to consider. For example: * [Filtering by metadata](/guides/search/filter-by-metadata): When records contain additional metadata, you can limit the search to records matching a [filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions). * [Hybrid search](/guides/search/hybrid-search): You can add [lexical search](/guides/search/lexical-search) to capture precise keyword matches (e.g., product SKUs, email addresses, domain-specific terms) in addition to semantic matches. * [Chunking strategies](https://www.pinecone.io/learn/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. ## 8. Clean up When you no longer need your example index, delete it as follows: ```python Python theme={null} # Delete the index pc.delete_index(index_name) ``` ```javascript JavaScript theme={null} // Delete the index await pc.deleteIndex(indexName); ``` ```java Java theme={null} // Add to the Quickstart class: // Delete the index pc.deleteIndex(indexName); ``` ```go Go theme={null} // Add to the main function: // Delete the index err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Println("Index \"%v\" deleted successfully", indexName) } ``` ```csharp C# theme={null} // Delete the index await pinecone.DeleteIndexAsync(indexName); ``` For production indexes, consider [enabling deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## Next steps Learn more about storing data in Pinecone Explore different forms of vector search. Find out how to improve performance To use [Cursor](https://cursor.com/) to build sample apps that use Pinecone (quick start, semantic search, RAG, or recommendations), follow the steps below. Rather than copying code snippets, you'll work with an agent that understands Pinecone APIs and implements production-ready patterns automatically. Because this quickstart relies on AI, the exact implementation may vary each time. ## 1. Sign up If you're new to Pinecone, sign up at [app.pinecone.io](https://app.pinecone.io) and choose a free plan: * [Starter plan](https://pinecone.io/pricing/): Free access to most features, but you're limited to one cloud region and need to stay under Starter plan [limits](/reference/api/database-limits). * [Standard plan trial](/guides/organizations/manage-billing/standard-trial): 21 days and \$300 in credits with access to Standard plan [features](https://www.pinecone.io/pricing/) and [higher limits](/reference/api/database-limits) that let you test Pinecone at scale. If you're already on a Starter plan, you can activate a Standard plan trial at any time (one trial per organization). After signing up, you'll receive an API key in the console. Save this key. You'll need it to authenticate your requests to Pinecone. ## 2. Open in Cursor To get started with Pinecone in Cursor, click this button:
(e.currentTarget.style.background = "var(--primary-dark)")} onMouseOut={(e) => (e.currentTarget.style.background = "var(--brand-blue)")} > Download AGENTS.md and launch in Cursor
This opens Cursor and enters this prompt: ```text theme={null} First, download and run this remote script: curl -sSL https://docs.pinecone.io/install-agent-reference | sh Then, help me get started with Pinecone. ``` To see the contents of the install script, use a web browser to visit this URL: [https://docs.pinecone.io/install-agent-reference](https://docs.pinecone.io/install-agent-reference). When you run this prompt: 1. Cursor executes a remote script that downloads Pinecone agent reference files, extracts them into an `.agents` folder, and creates an `AGENTS.md` file. These files provide Cursor with context it can use to help you get started with Pinecone. 2. Then, Cursor helps you build a sample app of your choice (quick test, semantic search, RAG, or recommendations) in the programming language of your choice. ## Next steps After building some sample apps, use the `AGENTS.md` file to continue building with Pinecone, planning and implementing code for your own use cases. To learn more about Pinecone, check out these resources: Learn more about storing data in Pinecone Explore different forms of vector search. Find out how to improve performance Use [Claude Code](https://www.claude.com/product/claude-code) to build a Pinecone application with current best practices. Instead of copying code snippets, work with an agent that understands Pinecone APIs and implements production-ready patterns automatically. Because this quickstart relies on AI, the exact implementation may vary each time. ## 1. Sign up If you're new to Pinecone, sign up at [app.pinecone.io](https://app.pinecone.io) and choose a free plan: * [Starter plan](https://pinecone.io/pricing/): Free access to most features, but you're limited to one cloud region and need to stay under Starter plan [limits](/reference/api/database-limits). * [Standard plan trial](/guides/organizations/manage-billing/standard-trial): 21 days and \$300 in credits with access to Standard plan [features](https://www.pinecone.io/pricing/) and [higher limits](/reference/api/database-limits) that let you test Pinecone at scale. If you're already on a Starter plan, you can activate a Standard plan trial at any time (one trial per organization). After signing up, you'll receive an API key in the console. Save this key. You'll need it to authenticate your requests to Pinecone. ## 2. Download `CLAUDE.md` AI coding agents like Claude Code learn from web searches and training data, which can include outdated patterns. To ensure Claude Code uses current Pinecone APIs and best practices, you'll use a `CLAUDE.md` reference file that provides authoritative, up-to-date information about Pinecone's 2025 APIs and CLI commands. 1. Create a new project folder: ```shell theme={null} mkdir pinecone-quickstart cd pinecone-quickstart ``` 2. Download the `CLAUDE.md` reference file for your preferred programming language:
```shell Python theme={null} curl -o CLAUDE.md https://docs.pinecone.io/AGENTS-PYTHON.md ``` ```shell JavaScript theme={null} curl -o CLAUDE.md https://docs.pinecone.io/AGENTS-JAVASCRIPT.md ```
3. Start Claude Code: ```shell theme={null} claude ``` If you don't have Claude Code installed, see the [Claude Code quickstart](https://docs.claude.com/en/docs/claude-code/quickstart). 4. Verify that Claude Code has access to the `CLAUDE.md` file: ```terminal wrap theme={null} Confirm you can see the CLAUDE.md file and understand the current Pinecone best practices it contains. Summarize the key points about using Pinecone in 2025. Just give me a concise summary - don't create any additional files or examples yet. ``` ## 3. Prompt your agent Now ask your agent to help you get started with Pinecone: ```terminal wrap theme={null} Help me get started with Pinecone. ``` Your agent will first ask you to choose an option: quick test, semantic search, RAG, or recommendations. Based on your choice, it will build and test a sample application using Pinecone best practices. Finally, it will provide a succinct summary of what it did. Throughout and after the process, you can review the generated code in your IDE to understand the patterns and best practices applied. You can also ask your coding agent to explain the code to you. ## 4. Give us feedback We'd love to hear your feedback on this quickstart. Please fill out this [short survey](https://share.hsforms.com/1roCbfhevRhKBOndYpA85pw4wfik). ## Next steps * Use your coding agent to: * Learn more about the system you built. * Extend or modify it. * Plan and implement specific requirements related to your own use case. * Learn more about Pinecone: Learn more about storing data in Pinecone Explore different forms of vector search. Find out how to improve performance Create an [n8n](https://docs.n8n.io/choose-n8n/) workflow that downloads files via HTTP and lets you chat with them using Pinecone Database and OpenAI. If you're not interested in chunking and embedding your own data or figuring out which search method to use, [use n8n with Pinecone Assistant](/guides/assistant/quickstart#n8n) instead. ## 1. Get API keys Your n8n workflow will need API keys for Pinecone and OpenAI. Create a new API key in the [Pinecone console](https://app.pinecone.io/organizations/-/keys), or use the widget below to generate a key. If you don't have a Pinecone account, the widget will sign you up for the free [Starter plan](https://www.pinecone.io/pricing/).
Your generated API key: ```shell theme={null} "{{YOUR_API_KEY}}" ``` Create a new API key in the [OpenAI console](https://platform.openai.com/api-keys). ## 2. Create an index [Create an index](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless) in the Pinecone console: * Name your index `n8n-dense-index` * Under **Configuration**, check **Custom settings** and set **Dimension** to 1536. * Leave everything else as default. ## 3. Set up n8n In your n8n account, [create a new workflow](https://docs.n8n.io/workflows/create/). Copy this workflow template URL: ```shell theme={null} https://raw.githubusercontent.com/pinecone-io/n8n-templates/refs/heads/main/database-quickstart/database-quickstart.json ``` Paste the URL into the workflow editor and then click **Import** to add the workflow. * Add your Pinecone credentials: * In the **Pinecone Vector Store** node, select **Credential to connect with** > **Create new credential** and paste in your Pinecone API key. * Name the credential **Pinecone** so that other nodes reference it. * Add your OpenAI credentials: * In the **OpenAI Chat Model**, select **Credential to connect with** > **Create new credential** and paste in your OpenAI API key. The workflow is configured to download recent Pinecone release notes and upload them to your Pinecone index. Click **Execute workflow** to start the workflow. You can add your own files to the workflow by changing the URLs in the **Set file urls** node. ## 4. Chat with your docs Once the workflow is activated, ask it for the latest changes to Pinecone Database: ``` What's new in Pinecone Database? ``` ## Next steps * Use your own data: * Change the urls in **Set file urls** node to use your own files. * You may need to adjust the chunk sizes in the **Recursive Character Text Splitter** node or use a different chunking strategy. You want chunks that are big enough to contain meaningful information but not so big that the meaning is diluted or it can't fit within the context window of the embedding model. See [Chunking Strategies for LLM Applications](https://www.pinecone.io/learn/chunking-strategies/) for more info. * Customize the system message of the **AI Agent** node to reflect what the **Pinecone Vector Store Tool** will be used for. Be sure to include info on what data can be retrieved using that tool. * Customize the description of the **Pinecone Vector Store Tool** to reflect what data you are storing in the Pinecone index. * Use n8n, Pinecone Assistant, and OpenAI to [chat with your Google Drive documents](https://n8n.io/workflows/9942-rag-powered-document-chat-with-google-drive-openai-and-pinecone-assistant/). * Get help in the [Pinecone Discord community](https://discord.gg/tJ8V62S3sH) or the [Pinecone Forum](https://community.pinecone.io/). # Check data freshness Source: https://docs.pinecone.io/guides/index-data/check-data-freshness Monitor data freshness in Pinecone using log sequence numbers and vector counts. Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. This page describes two ways of checking the data freshness of a Pinecone index: * To check if a serverless index queries reflect recent writes to the index, [check the log sequence number](#check-the-log-sequence-number). * To check whether an index contains recently inserted or deleted vectors, [verify the number of vectors in the index](#verify-vector-counts). ## Check the log sequence number This method is only available for serverless indexes through the [Database API](https://docs.pinecone.io/reference/api/latest/data-plane/upsert). ### Log sequence numbers When you make a write request to a serverless index namespace, Pinecone assigns a monotonically increasing log sequence number (LSN) to the write operation. The LSN reflects upserts as well as updates and deletes to that namespace. Writes to one namespace do not increase the LSN for other namespaces. You can use LSNs to verify that specific write operations are reflected in your query responses. If the LSN contained in the query response header is greater than or equal to the LSN of the relevant write operation, then that operation is reflected in the query response. If the LSN contained in the query response header is *greater than* the LSN of the relevant write operation, then subsequent operations are also reflected in the query response. Follow the steps below to compare the LSNs for a write and a subsequent query. ### 1. Get the LSN for a write operation Every time you modify records in your namespace, the HTTP response contains the LSN for the upsert. This is contained in a header called `x-pinecone-request-lsn`. The following example demonstrates how to get the LSN for an `upsert` request using the `curl` option `-i`. This option tells curl to include headers in the displayed response. Use the same method to get the LSN for an `update` or `delete` request. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "content-type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "vec1", "values": [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], } ], "namespace": "example-namespace" }' ``` The preceding request receives a response like the following example: ```shell curl theme={null} HTTP/2 200 date: Wed, 21 Aug 2024 15:23:04 GMT content-type: application/json content-length: 66 x-pinecone-max-indexed-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-max-indexed-lsn` is 4. This means that the index has performed 4 write operations since its creation. ### 2. Get the LSN for a query Every time you query your index, the HTTP response contains the LSN for the query. This is contained in a header called `x-pinecone-max-indexed-lsn`. By checking the LSN in your query results, you can confirm that the LSN is greater than or equal to the LSN of the relevant write operation, indicating that the results of that operation are present in the query results. The following example makes a `query` request to the index: ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "namespace": "example-namespace", "topK": 3, "includeValues": true }' ``` The preceding request receives a response like the following example: ```shell theme={null} HTTP/2 200 date: Wed, 21 Aug 2024 15:33:36 GMT content-type: application/json content-length: 66 x-pinecone-max-indexed-lsn: 5 x-pinecone-request-latency-ms: 40 x-pinecone-request-id: 6683088825552978933 x-envoy-upstream-service-time: 41 grpc-status: 0 server: envoy { "results":[], "matches":[ { "id":"vec1", "score":0.891132772, "values":[0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8], } ], "namespace":"example-namespace", "usage":{"readUnits":6} } ``` In the preceding example response, the value of `x-pinecone-max-indexed-lsn` is 5. ### 3. Compare LSNs for writes and queries If the LSN of a query is greater than or equal to the LSN for a write operation, then the results of the query reflect the results of the write operation. In [step 1](#1-get-the-lsn-for-a-write-operation), the LSN contained in the response headers is 4. In [step 2](#2-get-the-lsn-for-a-query), the LSN contained in the response headers is 5. 5 is greater than or equal to 4; therefore, the results of the query reflect the results of the upsert. However, this does not guarantee that the records upserted are still present or unmodified: the write operation with LSN of 5 may have updated or deleted these records, or upserted additional records. ## Verify record counts If you insert new records or delete records, the number of records in the index may change. This means that the record count for an index can indicate whether Pinecone has indexed your latest inserts and deletes: if the record count for the index matches the count you expect after inserting or deleting records, the index is probably up-to-date. However, this is not always true. For example, if you delete the same number of records that you insert, the expected record count may remain the same. Also, some write operations, such as updates to an index configuration or vector data values, do not change the number of records in the index. To verify that your index contains the number of records you expect, [view index stats](/reference/api/latest/data-plane/describeindexstats): ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.describe_index_stats() ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const stats = await index.describeIndexStats(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.DescribeIndexStatsResponse; public class DescribeIndexStatsExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); DescribeIndexStatsResponse indexStatsResponse = index.describeIndexStats(); System.out.println(indexStatsResponse); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } stats, err := idxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("%+v", *stats) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var indexStatsResponse = await index.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine(indexStatsResponse); ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```Python Python theme={null} {'dimension': 1024, 'index_fullness': 0, 'namespaces': {'example-namespace1': {'vector_count': 4}, 'example-namespace2': {'vector_count': 4}}, 'total_vector_count': 8} ``` ```JavaScript JavaScript theme={null} Returns: { namespaces: { example-namespace1: { recordCount: 4 }, example-namespace2: { recordCount: 4 } }, dimension: 1024, indexFullness: 0, totalRecordCount: 8 } // Note: the value of totalRecordCount is the same as total_vector_count. ``` ```java Java theme={null} namespaces { key: "example-namespace1" value { vector_count: 4 } } namespaces { key: "example-namespace2" value { vector_count: 4 } } dimension: 1024 total_vector_count: 8 ``` ```go Go theme={null} { "dimension": 1024, "index_fullness": 0, "total_vector_count": 8, "namespaces": { "example-namespace1": { "vector_count": 4 }, "example-namespace2": { "vector_count": 4 } } } ``` ```csharp C# theme={null} { "namespaces": { "example-namespace1": { "vectorCount": 4 }, "example-namespace2": { "vectorCount": 4 } }, "dimension": 1024, "indexFullness": 0, "totalVectorCount": 8 } ``` ```shell curl theme={null} { "namespaces": { "example-namespace1": { "vectorCount": 4 }, "example-namespace2": { "vectorCount": 4 } }, "dimension": 1024, "indexFullness": 0, "totalVectorCount": 8 } ``` # Create an index Source: https://docs.pinecone.io/guides/index-data/create-an-index Create dense or sparse indexes for semantic and lexical search. * **Dense indexes** store dense vectors, which are numerical representations of the meaning and relationships of text, images, or other types of data. You use dense indexes for [semantic search](/guides/search/semantic-search) or in combination with sparse indexes for [hybrid search](/guides/search/hybrid-search). * **Sparse indexes** store sparse vectors, which are numerical representations of the words or phrases in a document. You use sparse indexes for [lexical search](/guides/search/lexical-search), or in combination with dense indexes for [hybrid search](/guides/search/hybrid-search). You can create an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/serverless). ## Create a dense index You can create a dense index with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding) or a dense index for storing vectors generated with an external embedding model. ### Integrated embedding Indexes with integrated embedding do not support [updating](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text. If you want to upsert and search with source text and have Pinecone convert it to dense vectors automatically, [create a dense index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows: * Provide a `name` for the index. * Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the data for embedding. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_name = "integrated-dense-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndexForModel({ name: 'integrated-dense-js', cloud: 'aws', region: 'us-east-1', embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; import java.util.Map; public class CreateIntegratedIndex { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "integrated-dense-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("llama-text-embed-v2") .fieldMap(fieldMap); Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "integrated-dense-go" deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "llama-text-embed-v2", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless integrated index: %v", idx.Name) } else { fmt.Printf("Successfully created serverless integrated index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexForModelAsync( new CreateIndexForModelRequest { Name = "integrated-dense-dotnet", Cloud = CreateIndexForModelRequestCloud.Aws, Region = "us-east-1", Embed = new CreateIndexForModelRequestEmbed { Model = "llama-text-embed-v2", FieldMap = new Dictionary() { { "text", "chunk_text" } } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } } ); ``` ```json curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes/create-for-model" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "integrated-dense-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "integrated-dense-cli" \ --metric "cosine" \ --cloud "aws" \ --region "us-east-1" \ --model "llama-text-embed-v2" \ --field_map "text=chunk_text" \ --tags "environment=development" ``` ### Bring your own vectors If you use an external embedding model to convert your data to dense vectors, [create a dense index](/reference/api/latest/control-plane/create_index) as follows: * Provide a `name` for the index. * Set the `vector_type` to `dense`. * Specify the `dimension` and similarity `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model. * Set `spec.cloud` and `spec.region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "standard-dense-py" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="dense", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'standard-dense-js', vectorType: 'dense', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "standard-dense-java"; String cloud = "aws"; String region = "us-east-1"; String vectorType = "dense"; Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( indexName, "cosine", 1536, cloud, region, DeletionProtection.DISABLED, tags, vectorType ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Serverless index indexName := "standard-dense-go" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "standard-dense-dotnet", VectorType = VectorType.Dense, Dimension = 1536, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "standard-dense-curl", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "standard-dense-cli" \ --vector_type "dense" \ --dimension 1536 \ --metric "cosine" \ --cloud "aws" \ --region "us-east-1" \ --tags "environment=development" \ --deletion_protection "disabled" ``` ## Create a sparse index You can create a sparse index with [integrated vector embedding](/guides/index-data/indexing-overview#integrated-embedding) or a sparse index for storing vectors generated with an external embedding model. ### Integrated embedding If you want to upsert and search with source text and have Pinecone convert it to sparse vectors automatically, [create a sparse index with integrated embedding](/reference/api/latest/control-plane/create_for_model) as follows: * Provide a `name` for the index. * Set `cloud` and `region` to the [cloud and region](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. * Set `embed.model` to one of [Pinecone's hosted sparse embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the text for embedding. * If needed, `embed.read_parameters` and `embed.write_parameters` can be used to override the default model embedding behavior. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_for_model) for details. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_name = "integrated-sparse-py" if not pc.has_index(index_name): pc.create_index_for_model( name=index_name, cloud="aws", region="us-east-1", embed={ "model":"pinecone-sparse-english-v0", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndexForModel({ name: 'integrated-sparse-js', cloud: 'aws', region: 'us-east-1', embed: { model: 'pinecone-sparse-english-v0', fieldMap: { text: 'chunk_text' }, }, waitUntilReady: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.CreateIndexForModelRequest; import org.openapitools.db_control.client.model.CreateIndexForModelRequestEmbed; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; import java.util.Map; public class CreateIntegratedIndex { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "integrated-sparse-java"; String region = "us-east-1"; HashMap fieldMap = new HashMap<>(); fieldMap.put("text", "chunk_text"); CreateIndexForModelRequestEmbed embed = new CreateIndexForModelRequestEmbed() .model("pinecone-sparse-english-v0") .fieldMap(fieldMap); Map tags = new HashMap<>(); tags.put("environment", "development"); pc.createIndexForModel( indexName, CreateIndexForModelRequest.CloudEnum.AWS, region, embed, DeletionProtection.DISABLED, tags ); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "integrated-sparse-go" deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateIndexForModel(ctx, &pinecone.CreateIndexForModelRequest{ Name: indexName, Cloud: pinecone.Aws, Region: "us-east-1", Embed: pinecone.CreateIndexForModelEmbed{ Model: "pinecone-sparse-english-v0", FieldMap: map[string]interface{}{"text": "chunk_text"}, }, DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless integrated index: %v", idx.Name) } else { fmt.Printf("Successfully created serverless integrated index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexForModelAsync( new CreateIndexForModelRequest { Name = "integrated-sparse-dotnet", Cloud = CreateIndexForModelRequestCloud.Aws, Region = "us-east-1", Embed = new CreateIndexForModelRequestEmbed { Model = "pinecone-sparse-english-v0", FieldMap = new Dictionary() { { "text", "chunk_text" } } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } } ); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes/create-for-model" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "integrated-sparse-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "pinecone-sparse-english-v0", "field_map": { "text": "chunk_text" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "integrated-sparse-cli" \ --cloud "aws" \ --region "us-east-1" \ --model "pinecone-sparse-english-v0" \ --field_map "text=chunk_text" \ --tags "environment=development" ``` ### Bring your own vectors If you use an external embedding model to convert your data to sparse vectors, [create a sparse index](/reference/api/latest/control-plane/create_index) as follows: * Provide a `name` for the index. * Set the `vector_type` to `sparse`. * Set the distance `metric` to `dotproduct`. Sparse indexes do not support other [distance metrics](/guides/index-data/indexing-overview#distance-metrics). * Set `spec.cloud` and `spec.region` to the cloud and region where the index should be deployed. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```python Python theme={null} from pinecone import Pinecone, ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "standard-sparse-py" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1") ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'standard-sparse-js', vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.*; public class SparseIndex { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Create sparse Index String indexName = "standard-sparse-java"; String cloud = "aws"; String region = "us-east-1"; String vectorType = "sparse"; Map tags = new HashMap<>(); tags.put("env", "test"); pinecone.createSparseServelessIndex(indexName, cloud, region, DeletionProtection.DISABLED, tags, vectorType); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "standard-sparse-go" vectorType := "sparse" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, Metric: &metric, VectorType: &vectorType, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "standard-sparse-dotnet", VectorType = VectorType.Sparse, Metric = MetricType.Dotproduct, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } } }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "standard-sparse-curl", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } } }' ``` ```bash CLI theme={null} # Target the project where you want to create the index. pc target -o "example-org" -p "example-project" # Create the index. pc index create \ --name "standard-sparse-cli" \ --vector_type "sparse" \ --metric "dotproduct" \ --cloud "aws" \ --region "us-east-1" \ --tags "environment=development" ``` ## Create an index from a backup You can create a dense or sparse index from a backup. For more details, see [Restore an index](/guides/manage-data/restore-an-index). ## Metadata indexing This feature is in [early access](/release-notes/feature-availability) and available only on the `2025-10` version of the API. The CLI does not yet support this feature. Pinecone indexes all metadata fields by default. However, large amounts of metadata can cause slower [index building](/guides/get-started/database-architecture#index-builder) as well as slower [query execution](/guides/get-started/database-architecture#query-executors), particularly when data is not cached in a query executor's memory and local SSD and must be fetched from object storage. To prevent performance issues due to excessive metadata, you can limit metadata indexing to the fields that you plan to use for [query filtering](/guides/search/filter-by-metadata). ### Set metadata indexing You can set metadata indexing during index creation or [namespace creation](/reference/api/2025-10/data-plane/createnamespace): * Index-level metadata indexing rules apply to all namespaces that don't have explicit metadata indexing rules. * Namespace-level metadata indexing rules overrides index-level metadata indexing rules. For example, let's say you want to store records that represent chunks of a document, with each record containing many metadata fields. Since you plan to use only a few of the metadata fields to filter queries, you would specify the metadata fields to index as follows. Metadata indexing cannot be changed after index or namespace creation. ```shell Index-level metadata indexing theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-index-metadata", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true }, "created_at": { "filterable": true } } } } }, "deletion_protection": "disabled" }' ``` ```shell Namespace-level metadata indexing theme={null} # To learn how to get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true }, "created_at": { "filterable": true } } } }' ``` ### Check metadata indexing To check which metadata fields are indexed, you can describe the index or namespace: ```shell Describe index theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/indexes/example-index-metadata" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```shell Describe namespace theme={null} # To learn how to get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespaces/example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response includes the `schema` object with the names of the metadata fields explicitly indexed during index or namespace creation. The response does not include unindexed metadata fields or metadata fields indexed by default. ```json Describe index theme={null} { "id": "751ab850-6e61-4f92-bd23-fa129803d207", "vector_type": "dense", "name": "example-index", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-index-fa77d8e.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": "Ready" }, "schema": { "fields": { "document_id": { "filterable": true }, "document_title": { "filterable": true }, "created_at": { "filterable": true }, "chunk_number": { "filterable": true }, "document_url": { "filterable": true } } } } }, "deletion_protection": "disabled", "tags": null } ``` ```json Describe namespace theme={null} { "name": "example-namespace", "record_count": "20000", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` ## Index options ### Cloud regions When creating an index, you must choose the cloud and region where you want the index to be hosted. The following table lists the available public clouds and regions and the plans that support them: | Cloud | Region | [Supported plans](https://www.pinecone.io/pricing/) | [Availability phase](/release-notes/feature-availability) | | ------- | ---------------------------- | --------------------------------------------------- | --------------------------------------------------------- | | `aws` | `us-east-1` (Virginia) | Starter, Standard, Enterprise | General availability | | `aws` | `us-west-2` (Oregon) | Standard, Enterprise | General availability | | `aws` | `eu-west-1` (Ireland) | Standard, Enterprise | General availability | | `gcp` | `us-central1` (Iowa) | Standard, Enterprise | General availability | | `gcp` | `europe-west4` (Netherlands) | Standard, Enterprise | General availability | | `azure` | `eastus2` (Virginia) | Standard, Enterprise | General availability | The cloud and region cannot be changed after a serverless index is created. On the free Starter plan, you can create serverless indexes in the `us-east-1` region of AWS only. To create indexes in other regions, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Similarity metrics When creating a dense index, 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/). [Sparse indexes](#sparse-indexes) must use the `dotproduct` metric. Querying indexes with this metric returns a similarity score equal to the squared Euclidean distance between the result and query vectors. This metric calculates the square of the distance between two data points in a plane. It is one of the most commonly used distance metrics. For an example, see our [IT threat detection example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/it-threat-detection.ipynb). When you use `metric='euclidean'`, the most similar results are those with the **lowest similarity score**. This is often used to find similarities between different documents. The advantage is that the scores are normalized to \[-1,1] range. For an example, see our [generative question answering example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/gen-qa-openai.ipynb). This is used to multiply two vectors. You can use it to tell us how similar the two vectors are. The more positive the answer is, the closer the two vectors are in terms of their directions. For an example, see our [semantic search example](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/semantic-search.ipynb). ### Embedding models [Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information. To transform data into vector format, you use an embedding model. Pinecone hosts several embedding models so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation. The following embedding models are hosted by Pinecone. To understand how cost is calculated for embedding, see [Embedding cost](/guides/manage-cost/understanding-cost#embedding). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model). #### multilingual-e5-large [`multilingual-e5-large`](/models/multilingual-e5-large) is an efficient dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs). **Details** * Vector type: Dense * Modality: Text * Dimension: 1024 * Recommended similarity metric: Cosine * Max sequence length: 507 tokens * Max batch size: 96 sequences For rate limits, see [Embedding tokens per minute](/reference/api/database-limits#embedding-tokens-per-minute-per-model) and [Embedding tokens per month](/reference/api/database-limits#embedding-tokens-per-month-per-model). **Parameters** The `multilingual-e5-large` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :----------- | :----- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `input_type` | string | Required | The type of input data. Accepted values: `query` or `passage`. | | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

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

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

`END` truncates the input sequence at the the `max_tokens_per_sequence` limit. `NONE` returns an error when the input exceeds the `max_tokens_per_sequence` limit. | `END` | | `return_tokens` | boolean | Optional | Whether to return the string tokens. | `false` | # Data ingestion overview Source: https://docs.pinecone.io/guides/index-data/data-ingestion-overview Learn about the different ways to ingest data into Pinecone. To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ## Import from object storage [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Upsert For ongoing ingestion into an index, either one record at a time or in batches, use the [upsert](/guides/index-data/upsert-data) operation. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records if you cannot work around import's current [limitations](/guides/index-data/import-data#import-limits). ## Ingestion cost * To understand how cost is calculated for imports, see [Import cost](/guides/manage-cost/understanding-cost#imports). * To understand how cost is calculated for upserts, see [Upsert cost](/guides/manage-cost/understanding-cost#upsert). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Data modeling Source: https://docs.pinecone.io/guides/index-data/data-modeling Learn how to structure records for efficient data retrieval and management in Pinecone. ## Record format When you upsert raw text for Pinecone to convert to vectors automatically, each record consists of the following: * **ID**: A unique string identifier for the record. * **Text**: The raw text for Pinecone to convert to a dense vector for [semantic search](/guides/search/semantic-search) or a sparse vector for [lexical search](/guides/search/lexical-search), depending on the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index. This field name must match the `embed.field_map` defined in the index. * **Metadata** (optional): All additional fields are stored as record metadata. You can filter by metadata when searching or deleting records. Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding). Example: ```json theme={null} { "_id": "document1#chunk1", "chunk_text": "First chunk of the document content...", // Text to convert to a vector. "document_id": "document1", // This and subsequent fields stored as metadata. "document_title": "Introduction to Vector Databases", "chunk_number": 1, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } ``` When you upsert pre-generated vectors, each record consists of the following: * **ID**: A unique string identifier for the record. * **Vector**: A dense vector for [semantic search](/guides/search/semantic-search), a sparse vector for [lexical search](/guides/search/lexical-search), or both for [hybrid search](/guides/search/hybrid-search) using a single hybrid index. * **Metadata** (optional): A flat JSON document containing key-value pairs with additional information (nested objects are not supported). You can filter by metadata when searching or deleting records. When importing data from object storage, records must be in Parquet format. For more details, see [Import data](/guides/index-data/import-data#prepare-your-data). Example: ```json Dense theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` ```json Sparse theme={null} { "id": "document1#chunk1", "sparse_values": { "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688], "indices": [822745112, 1009084850, ..., 3517203014, 3590924191] }, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` ```json Hybrid theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "sparse_values": { "values": [1.7958984, 0.41577148, ..., 4.4414062, 3.3554688], "indices": [822745112, 1009084850, ..., 3517203014, 3590924191] }, "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ``` ## Use structured IDs Use a structured, human-readable format for record IDs, including ID prefixes that reflect the type of data you're storing, for example: * **Document chunks**: `document_id#chunk_number` * **User data**: `user_id#data_type#item_id` * **Multi-tenant data**: `tenant_id#document_id#chunk_id` Choose a delimiter for your ID prefixes that won't appear elsewhere in your IDs. Common patterns include: * `document1#chunk1` - Using hash delimiter * `document1_chunk1` - Using underscore delimiter * `document1:chunk1` - Using colon delimiter Structuring IDs in this way provides several advantages: * **Efficiency**: Applications can quickly identify which record it should operate on. * **Clarity**: Developers can easily understand what they're looking at when examining records. * **Flexibility**: ID prefixes enable list operations for fetching and updating records. ## Include metadata Include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) that support your application's key operations, for example: * **Enable query-time filtering**: Add fields for time ranges, categories, or other criteria for [filtering searches for increased accuracy and relevance](/guides/search/filter-by-metadata). * **Link related chunks**: Use fields like `document_id` and `chunk_number` to keep track of related records and enable efficient [chunk deletion](#delete-chunks) and [document updates](#update-an-entire-document). * **Link back to original data**: Include `chunk_text` or `document_url` for traceability and user display. Metadata keys must be strings, and metadata values must be one of the following data types: * String * Number (integer or floating point, gets converted to a 64-bit floating point) * Boolean (true, false) * List of strings Pinecone supports 40 KB of metadata per record. ## Example This example demonstrates how to manage document chunks in Pinecone using structured IDs and comprehensive metadata. It covers the complete lifecycle of chunked documents: upserting, searching, fetching, updating, and deleting chunks, and updating an entire document. ### Upsert chunks When [upserting](/guides/index-data/upsert-data) documents that have been split into chunks, combine structured IDs with comprehensive metadata: Upserting raw text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding). ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_records( "example-namespace", [ { "_id": "document1#chunk1", "chunk_text": "First chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, { "_id": "document1#chunk2", "chunk_text": "Second chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, { "_id": "document1#chunk3", "chunk_text": "Third chunk of the document content...", "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 3, "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" }, ] ) ``` ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( namespace="example-namespace", vectors=[ { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } }, { "id": "document1#chunk3", "values": [0.0512237548828125, 0.041656494140625, ..., 0.02130126953125, -0.0394287109375], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 3, "chunk_text": "Third chunk of the document content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "document_type": "tutorial" } } ] ) ``` ### Search chunks To search the chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the search appropriately: Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/create-an-index#integrated-embedding). ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "What is a vector database?"}, "top_k": 3, "filter": {"document_id": "document1"} }, fields=["chunk_text"] ) print(filtered_results) ``` ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, filter={ "document_id": {"$eq": "document1"} }, include_metadata=True, include_values=False ) print(filtered_results) ``` ### Fetch chunks To retrieve all chunks for a specific document, first [list the record IDs](/guides/manage-data/list-record-ids) using the document prefix, and then [fetch](/guides/manage-data/fetch-data) the complete records: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List all chunks for document1 using ID prefix chunk_ids = [] for record_id in index.list(prefix='document1#', namespace='example-namespace'): chunk_ids.append(record_id) print(f"Found {len(chunk_ids)} chunks for document1") # Fetch the complete records by ID if chunk_ids: records = index.fetch(ids=chunk_ids, namespace='example-namespace') for record_id, record_data in records['vectors'].items(): print(f"Chunk ID: {record_id}") print(f"Chunk text: {record_data['metadata']['chunk_text']}") # Process the vector values and metadata as needed ``` Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes. ### Update chunks To [update](/guides/manage-data/update-data) specific chunks within a document, first list the chunk IDs, and then update individual records: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List all chunks for document1 chunk_ids = [] for record_id in index.list(prefix='document1#', namespace='example-namespace'): chunk_ids.append(record_id) # Update specific chunks (e.g., update chunk 2) if 'document1#chunk2' in chunk_ids: index.update( id='document1#chunk2', values=[], set_metadata={ "document_id": "document1", "document_title": "Introduction to Vector Databases - Revised", "chunk_number": 2, "chunk_text": "Updated second chunk content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-01-15", "updated_at": "2024-02-15", "document_type": "tutorial" }, namespace='example-namespace' ) print("Updated chunk 2 successfully") ``` ### Delete chunks To [delete](/guides/manage-data/delete-data#delete-records-by-metadata) chunks of a document, use a [metadata filter expression](/guides/search/filter-by-metadata#metadata-filter-expressions) that limits the deletion appropriately: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Delete chunks 1 and 3 index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"}, "chunk_number": {"$in": [1, 3]} } ) # Delete all chunks for a document index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) ``` ### Update an entire document When the amount of chunks or ordering of chunks for a document changes, the recommended approach is to first [delete all chunks using a metadata filter](/guides/manage-data/delete-data#delete-records-by-metadata), and then [upsert](/guides/index-data/upsert-data) the new chunks: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Step 1: Delete all existing chunks for the document index.delete( namespace="example-namespace", filter={ "document_id": {"$eq": "document1"} } ) print("Deleted existing chunks for document1") # Step 2: Upsert the updated document chunks index.upsert( namespace="example-namespace", vectors=[ { "id": "document1#chunk1", "values": [], "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": [], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases - Updated Edition", "chunk_number": 2, "chunk_text": "Updated second chunk with new content...", "document_url": "https://example.com/docs/document1", "created_at": "2024-02-15", "document_type": "tutorial", "version": "2.0" } } # Add more chunks as needed for the updated document ] ) print("Successfully updated document1 with new chunks") ``` ## Data freshness Pinecone is [eventually consistent](/guides/index-data/check-data-freshness), so it's possible that a write (upsert, update, or delete) followed immediately by a read (query, list, or fetch) may not return the latest version of the data. If your use case requires retrieving data immediately, consider implementing a small delay or [retry logic](/guides/production/error-handling#implement-retry-logic) after writes. # Dedicated Read Nodes Source: https://docs.pinecone.io/guides/index-data/dedicated-read-nodes Dedicated read nodes use provisioned hardware for read operations, providing predictable, low-latency performance at high query volumes. This feature is in [public preview](/release-notes/feature-availability). ## Overview Pinecone indexes built on dedicated read nodes use provisioned read hardware to provide predictable, consistent performance at sustained, high query volumes. They're designed for large-scale vector workloads such as semantic search, recommendation engines, and mission-critical services. Dedicated read nodes differ from on-demand indexes in how they handle read operations. While on-demand indexes use shared, multi-tenant capacity for reads, dedicated read nodes provision exclusive hardware for reads—memory, local SSDs, and compute. Both index types use Pinecone's serverless infrastructure for writes and storage. When you create a dedicated read nodes index, Pinecone provisions resources based on your choice of [node type](#node-types), number of [shards](#shards), and number of [replicas](#replicas). These resources include local SSDs and memory that cache all your index data, and provide dedicated query executors to handle read operations (query, fetch, list). This architecture eliminates cold starts and ensures consistent low-latency performance, even under heavy load. Dedicated read nodes support dense, sparse, or hybrid indexes, giving you flexibility in your search and retrieval strategy. Because storage (shards) and compute (replicas) scale independently, you can optimize for your specific workload characteristics. ## On-demand vs dedicated On-demand indexes and dedicated read nodes are both built on Pinecone's serverless infrastructure. They use the same write path, storage layer, and data operations API. However, every dedicated read nodes index has isolated hardware for read operations (query, fetch, list), allowing these operations to run on dedicated query executors. This affects performance, cost, and how you scale: | Feature | On-demand | Dedicated read nodes | | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Read infrastructure** | Multi-tenant compute resources shared across customers | Isolated, provisioned query executors dedicated to your index | | **Read costs** | Pay per [read unit](/guides/manage-cost/understanding-cost#serverless-indexes) (1 RU per 1 GB of namespace size per query, minimum 0.25 RU) | Fixed hourly rate for read capacity based on node type, shards, and replicas | | **Other costs** | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage | [Storage](/guides/manage-cost/understanding-cost#storage) and [write](/guides/manage-cost/understanding-cost#write-units) costs based on usage (same as on-demand) | | **Caching** | Best-effort; frequently accessed data is cached, but cold queries fetch from object storage | Guaranteed; all index data always warm in memory and on local SSDs | | **Read rate limits** | [2,000 RUs/second per index (adjustable)](/reference/api/database-limits#rate-limits) | No read rate limits (only bounded by CPU capacity) | | **Scaling** | Automatic; Pinecone handles capacity | Manual; add [shards](#shards) for storage, add [replicas](#replicas) for throughput | | **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 requirements | ## When to use dedicated read nodes Dedicated read nodes are ideal for workloads with millions to billions of records and predictable query rates. They provide performance and cost benefits compared to on-demand for high-throughput workloads, and may be required when your workload exceeds on-demand rate limits. There's no universal formula for choosing between on-demand and dedicated read nodes—performance and cost vary by workload (vector dimensionality, metadata filtering, and query patterns). Consider the following factors when making your decision: With dedicated read nodes, you allocate dedicated read hardware for your index, and your data is cached in memory and on local SSDs. This provides: * Consistent low latency under heavy load. * No cold starts (fetching data from object storage). * Performance isolation from other workloads. * Linear scaling by adding replicas. * Predictable costs based on fixed hourly rates for provisioned hardware. If predictable performance and cost are critical for your application, dedicated read nodes may be a better fit than on-demand. On-demand indexes are subject to [read unit rate limits](/reference/api/database-limits#rate-limits) (default: 2,000 RUs/second per index). A high query volume on a large index can exceed these limits. For example, a 15 GB namespace at 150 QPS requires approximately 2,250 RUs/second (`15 RUs per query × 150 QPS`), which exceeds the default rate limit. Dedicated read nodes have no read rate limits and provide dedicated capacity for predictable QPS without throttling (bounded only by CPU capacity), making them better suited for high-throughput workloads. Recommendation engines for use cases such as e-commerce and media require very high throughput and low latency to maintain positive user experiences. Dedicated read nodes are purpose-built for these use cases, providing: * Consistent performance for thousands of queries per second * Low latency for real-time recommendations * Scalability to billion-vector datasets * No performance degradation during traffic spikes Similar requirements apply to other real-time use cases like semantic search at scale, personalization engines, and mission-critical services with strict performance SLOs. Dedicated read nodes indexes support only a single namespace. If your application requires multiple namespaces, on-demand is a better fit. Multi-namespace support is coming soon. For early access, [contact us](https://www.pinecone.io/contact/). On-demand indexes are better suited for workloads with unpredictable or highly variable traffic patterns. For example: * RAG systems with variable query volumes * Agentic applications with sporadic usage * Prototypes and development environments with intermittent activity * Scheduled jobs with infrequent, batch-style queries Additionally, on-demand is better for indexes with many namespaces, even if you have high query volumes. Dedicated read nodes currently only support single-namespace indexes, so multi-tenant applications requiring namespace-based isolation should use on-demand until multi-namespace support is available. For these scenarios, on-demand's elasticity and usage-based pricing provide better cost efficiency than provisioning dedicated capacity. Dedicated read nodes **can** handle predictable traffic spikes efficiently if you scale replicas proactively via the API. For example, you can provision extra replicas before a scheduled email campaign and scale back down afterward. Auto-scaling will be available in a future release. On-demand and dedicated read nodes have different cost structures. The key difference is read costs: on-demand uses usage-based pricing, while dedicated read nodes use a fixed hourly rate based on provisioned hardware. Write and storage costs are usage-based for both modes. Dedicated read nodes become cost-effective when you have predictable, sustained query volumes that make full use of your provisioned capacity. With unpredictable or low query volumes, you pay hourly rates even when your machines sit idle, making on-demand's usage-based pricing more economical. For detailed cost information, comparison tables, and estimation tools, see the [Cost](#cost) section of this guide. Performance depends on your specific workload — index size, vector dimensionality, metadata filtering, query patterns, throughput requirements, and latency requirements. Testing is the only way to know for sure whether dedicated read nodes are right for your scenario. For a step-by-step guide to testing, see [Test your workload](#test-your-workload). If you need guidance choosing a capacity mode (on-demand or dedicated read nodes) or sizing your index configuration, [contact us](https://www.pinecone.io/contact/). ## Key concepts Before creating a dedicated read nodes index, understand the configuration options that determine capacity and performance. ### Node types A node is the basic unit of compute and cache storage capacity for a dedicated read nodes index. Each shard runs on one node, so the node type you choose determines the performance characteristics and cost of your index. The total number of nodes in your index is calculated as `shards × replicas`. For example, an index with two shards and two replicas uses four nodes. There are two node types: `b1` and `t1`. Both are suitable for large-scale and demanding workloads, but they differ in processing power and memory capacity, and they cache different data. | | **b1 (Balanced)** | **t1 (Performance)** | | -------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Memory caching** | Vector index stored in memory | Vector index + vector projections cached in memory | | **Use case** | Predictable performance for sustained query rates with balanced cost efficiency | Highest performance for the most demanding workloads with extreme query volumes and strict latency requirements | | **Storage** | 250 GB per shard | 250 GB per shard | | **Compute & memory** | Base-level compute and memory resources | \~4x more compute and memory than `b1` | | **Cost** | Lower-cost option | \~3x the cost of `b1` | Consider using `t1` nodes if your performance requirements are not met by `b1` nodes, or if `t1` nodes are more cost-effective than `b1` nodes for your workload. When choosing a node type, remember that: * Both types of nodes provide 250 GB of storage per shard. The difference is in compute and memory, which affects query performance. * Because `t1` nodes cache more data in memory than `b1` nodes, an index may require more shards on `t1` than on `b1` (for the same data). * You can [change node types](#change-node-types) after creating your index. ### Shards Shards determine the storage capacity of an index. Each shard provides 250 GB of storage, and data is split across all the shards in an index. To respond to a query, the index gathers data from all shards as needed. To determine how many shards you need, [calculate your index size](#calculate-the-size-of-your-index) and then [calculate the number of shards](#number-of-shards). It's your responsibility to allocate enough shards to accommodate the size of your index. If your index exceeds the capacity of its shards, write operations (upsert, update, delete) are blocked, but read operations continue to work normally. ### Replicas Replicas multiply the compute resources and data of an index, allowing for higher query throughput and availability. Each replica is a complete copy of your index data and has its own dedicated compute resources. * Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS. * You can scale replicas up or down with no downtime using the API. See [Add or remove replicas](#add-or-remove-replicas). * Minimum: 0 replicas ([pauses the index](#pause-an-index)). * For high availability, use at least two replicas. The recommended approach is to allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones (up to three per region), so if one zone fails, remaining replicas continue serving queries. To determine how many replicas you need, [test your workload](#test-your-workload) and then [calculate the number of replicas](#number-of-replicas). Actual performance varies based on workload characteristics (query complexity, vector dimensions, metadata characteristics), [metadata filter](/guides/search/filter-by-metadata) selectivity, and [node type](#node-types) (`b1` vs `t1`). Always test with your specific workload. ### Index fullness Index fullness measures how much of your index's allocated capacity is being used. To ensure predictable performance, dedicated read nodes cache your data in memory and on local SSD. * You can use Pinecone's API to [check index fullness](#monitor-index-fullness). There are three metrics to monitor: `memoryFullness`, `storageFullness`, and `indexFullness`. `indexFullness` is the maximum of `memoryFullness` and `storageFullness`. * Usually, storage fills up first. However, memory can be the limiting factor when you have `b1` nodes with many low-dimension vectors, or when you have `t1` nodes with high-dimension vectors and lots of metadata. * Monitor fullness regularly and [add shards](#add-or-remove-shards) before your index reaches capacity. When `indexFullness` reaches 1.0 (100%), write operations (upsert, update, delete) are blocked, but read operations continue to work normally. Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures. ## Test your workload To choose between on-demand and dedicated read nodes, or to optimize your dedicated read nodes configuration, test with your actual workload. Performance varies based on factors such as the size of your index,vector dimensionality, metadata characteristics, and query patterns. [Calculate the size of your index](#calculate-the-size-of-your-index) to determine how many shards it requires. [Create a dedicated read nodes index](#create-a-dedicated-read-nodes-index) with representative data for your workload. You'll use this index for testing. If you don't restore your test index from a backup, you can [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data. If your test index is on-demand, [migrate it to dedicated read nodes](#migrate-to-dedicated-read-nodes). To start, use a single `b1` replica. Don't migrate your production index yet. At this point, you're just testing your workload. Run realistic query patterns against your test index, gradually increasing QPS. For example, start at 10 QPS for about 30 minutes, then increase by 10 QPS increments while monitoring latency. Identify the QPS where latency exceeds your target threshold. Throughput scales approximately linearly with replicas. For example, if one replica handles 50 QPS at your target latency, two replicas should handle approximately 100 QPS. However, performance can vary based on metadata filter selectivity. To calculate the number of replicas required for your target QPS, use this formula, rounding up: ``` Minimum replicas = (Required QPS) / (QPS per replica) ``` For more information, see [Number of replicas](#number-of-replicas). To meet your performance and cost goals, adjust your configuration as needed and re-test: * [Add or remove shards](#add-or-remove-shards) for storage capacity * [Add or remove replicas](#add-or-remove-replicas) for throughput * [Change node types](#change-node-types) for different performance characteristics Continue iterating until you meet your requirements with room for growth. ## Calculate the size of your index To determine how many [shards](#shards) your index requires, calculate your index size and then use the formula in the [section](#number-of-shards) below. ### Index size A record can include a dense vector, a sparse vector, or both. Use the formula for your index type to calculate total size:
A [dense index](/guides/index-data/indexing-overview#dense-indexes) contains records with one dense vector each. Dense index records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-hybrid-index). To learn how to calculate the size of a hybrid index, see [Hybrid index](#hybrid-index). **Calculate dense index size (assuming no sparse vectors)** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. **Example dense index calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg metadata size | Index size | | :--------- | :---------------------- | :---------------- | :--------- | | 500,000 | 768 | 500 bytes | 1.79 GB | | 1,000,000 | 1536 | 1,000 bytes | 7.15 GB | | 5,000,000 | 1024 | 15,000 bytes | 95.5 GB | | 10,000,000 | 1536 | 1,000 bytes | 71.5 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB A [sparse index](/guides/index-data/indexing-overview#sparse-indexes) contains records with one sparse vector each. **Calculate sparse index size** ``` Index size = Number of records × ( ID size + Metadata size + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example sparse index calculations** These examples assume 8-byte IDs: | Records | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 10 | 500 bytes | 0.29 GB | | 1,000,000 | 50 | 1,000 bytes | 1.41 GB | | 5,000,000 | 100 | 15,000 bytes | 79.0 GB | | 10,000,000 | 50 | 1,000 bytes | 14.1 GB | Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB A [hybrid index](/guides/search/hybrid-search#use-a-single-hybrid-index) contains records that each have one dense vector and an optional sparse vector. **Calculate hybrid index size** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example hybrid index calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 768 | 10 | 500 bytes | 1.83 GB | | 1,000,000 | 1536 | 50 | 1,000 bytes | 7.54 GB | | 5,000,000 | 1024 | 100 | 15,000 bytes | 99.5 GB | | 10,000,000 | 1536 | 50 | 1,000 bytes | 75.4 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
### Number of shards To calculate the number of shards your index requires, divide the size of your index by 250 GB and round up: ``` Minimum shards = (Index size) / (250 GB per shard) ``` To maintain optimal performance, provision additional shards to keep your index at 70-80% capacity. For example, a 500 GB index should have three shards (750 GB capacity = 67% full), not two shards (500 GB capacity = 100% full). **Example shard calculations** | Index size | Minimum shards | Recommended shards | | :----------- | :------------------- | :------------------- | | **\~71 GB** | 1 (250 GB; 28% full) | 1 (250 GB; 28% full) | | **\~300 GB** | 2 (500 GB; 60% full) | 2 (500 GB; 60% full) | | **\~400 GB** | 2 (500 GB; 80% full) | 3 (750 GB; 53% full) | **Other considerations** * Every index must have at least one shard. However, you can [pause an index](#pause-an-index) by reducing its replicas to 0. * After you've created your index, [monitor its fullness](#monitor-index-fullness). When your index approaches capacity, you can [add shards](#add-or-remove-shards). Add shards when [index fullness](#index-fullness) reaches 70-80%, especially if you expect continued growth. Adding shards reduces storage fullness (index data is spread across shards, so each stores less) and memory fullness (with less data per shard, there's less to cache in memory), helping you avoid write failures. ### Number of replicas To calculate the number of replicas your index requires, first [test your workload](#test-your-workload) to find the QPS a single replica can handle at your target latency. Then, use this formula, and round up: ``` Minimum replicas = (Required QPS) / (QPS per replica) ``` For example, if one replica handles 50 QPS at your target latency and you need 150 QPS, you need three replicas. **Other considerations** * Throughput scales approximately linearly with replicas, but performance can vary based on metadata filter selectivity. * For high availability, allocate `n+1` replicas where `n` is your minimum for throughput. Pinecone distributes replicas across availability zones. ## Create a dedicated read nodes index You can create a dedicated read nodes index from scratch or from a backup of an existing index. ### From scratch To create a new dedicated read nodes index from scratch, call [Create an index](/reference/api/2025-10/control-plane/create_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields: | Field | Value | Notes | | :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- | | **`mode`** | `Dedicated` | | | **`dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | | **`dedicated.scaling`** | `Manual` | Currently the only option | | **`dedicated.manual.shards`** | Number of [shards](#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index) | To learn how to determine the number of shards and replicas your index requires, see [Calculate the size of your index](#calculate-the-size-of-your-index). **Example** ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X POST "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-dedicated-index", "dimension": 1024, "metric": "cosine", "deletion_protection": "enabled", "tags": { "environment": "production" }, "vector_type": "dense", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } } } } } }' ``` Example response: ```json curl highlight={21,27} expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": false, "state": "Initializing" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, // <---- desired state "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, // <---- current state "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "environment": "production" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | When creating a dedicated read nodes index, `status.state` transitions to `Ready` as soon as the index is ready for reads and writes. However, `spec.serverless.read_capacity.status.state` remains `Migrating` until the index scales to its full read capacity, at which point it transitions to `Ready`. After creating the index, [upsert](/guides/index-data/upsert-data) or [import](/guides/index-data/import-data) your data. To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). Call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and specify the `embed` object in the request body. ### From a backup To create a dedicated read nodes index from a backup: 1. [Restore the backup](/guides/manage-data/restore-an-index). This creates a new on-demand index with the same data as the original. 2. If the restored index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support [one namespace](#namespace-limits). 3. [Migrate the index to dedicated read nodes](#migrate-to-dedicated-read-nodes). ## Migrate to dedicated read nodes To migrate an existing on-demand index to dedicated read nodes, follow these steps: [Create a backup](/guides/manage-data/back-up-an-index) of your index. If you later find that on-demand is preferable, you can restore the backup to a new on-demand index or [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to migrate back. If your index has multiple namespaces, [delete](/reference/api/latest/data-plane/deletenamespace) all of them except the one you want to keep. Dedicated read nodes currently only support a [single namespace](#namespace-limits). If this is a production index, be sure to make a [backup](/guides/manage-data/back-up-an-index) before deleting namespaces. Or, if you need multiple namespaces, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket) to discuss early access to multi-namespace support for dedicated read nodes. [Calculate your index size](#index-size) to determine how many [shards](#number-of-shards) you need. To migrate the index, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, in the `spec.serverless.read_capacity` object, set the following fields: | Field | Value | Notes | | :------------------------------ | :----------------------------------------------- | :----------------------------------------------------- | | **`mode`** | `Dedicated` | | | **`dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | | **`dedicated.scaling`** | `Manual` | Currently the only option | | **`dedicated.manual.shards`** | Number of [shards](#number-of-shards) needed | Minimum 1 shard; each shard provides 250 GB of storage | | **`dedicated.manual.replicas`** | Number of [replicas](#number-of-replicas) needed | Minimum 0 (this [pauses](#pause-an-index) the index) | **Example** This example migrates an index to dedicated read nodes using `b1` nodes, one shard, and one replica: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } } } } } }' ``` Example response: ```json curl highlight={21,27} expandable theme={null} { "name": "example-index-to-migrate", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-index-to-migrate-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, // <---- desired state "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, //<---- current state "current_replicas": null } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | If `status.state` is set to `Error`, the allocated number of shards was insufficient for the size of the index. Try again, adding more shards as needed. [Monitor](#check-the-status-of-a-change) the status of the migration. When the migration is complete, `spec.serverless.read_capacity.status.state` is `Ready`. After migrating, monitor your index performance to verify that it meets expectations. ## Manage your index The following sections describe how to manage a dedicated read nodes index using version `2025-10` of the Pinecone API. To upsert and search with text instead of vectors, you can configure your index to use a [hosted embedding model](/guides/index-data/create-an-index#embedding-models). To do this, call [Configure an index](/reference/api/2025-10/control-plane/configure_index) and provide an `embed` object in the request body. In this object: * For the `text` field, specify the name of the field in your data that contains the text to be embedded. * Specify a model whose dimension requirements match the dimensions of your index. **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "embed": { "field_map": { "text": "chunk_text" }, "model": "llama-text-embed-v2", "read_parameters": { "input_type": "query", "truncate": "NONE" }, "write_parameters": { "input_type": "passage" } } }' ``` Example response: ```json curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } }, "status": { "state": "Ready", "current_shards": 2, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "environment": "testing" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "NONE" }, "vector_type": "dense" } } ``` You can also create a dedicated read nodes index when calling [Create an index with integrated embedding](/reference/api/2025-10/control-plane/create_for_model). In the request body, use the `read_capacity` object to configure node type, shards, and replicas for dedicated read nodes. To check [index fullness](#index-fullness), call [Get index stats](/reference/api/2025-10/data-plane/describeindexstats). **Example** Example request: ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" curl -X GET "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` Example response: ```json curl expandable theme={null} { "namespaces": { "__default__": { "vectorCount": 705000 } }, "indexFullness": 0.01, "totalVectorCount": 705000, "dimension": 1536, "metric": "cosine", "vectorType": "dense", "memoryFullness": 0.01, "storageFullness": 0.01 } ``` In the response, `indexFullness` describes how full the index is, on a scale of 0 to 1. It's set to the greater of `memoryFullness` and `storageFullness`. To add or remove [shards](#shards), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :---------------------------------------------------------- | :---------------------------------- | :------------------------------------ | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.scaling`** | `Manual` | | | **`spec.serverless.read_capacity.dedicated.manual.shards`** | Desired number of [shards](#shards) | Each shard provides 250 GB of storage | **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "shards": 3 } } } } } }' ``` Example response: ```json curl highlight={21,27} expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 3, // <---- desired state "replicas": 1 } }, "status": { "state": "Scaling", "current_shards": 2, // <---- current state "current_replicas": 1 } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. To add or remove [replicas](#replicas), call [Configure an index](/reference/api/2025-10/control-plane/configure_index). This operation does not require downtime, but can take up to 30 minutes to complete. In the request body, set the following fields: | Field | Value | Notes | | :------------------------------------------------------------ | :-------------------------------------- | :---------------------------------------- | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.scaling`** | `Manual` | | | **`spec.serverless.read_capacity.dedicated.manual.replicas`** | Desired number of [replicas](#replicas) | Add replicas to increase query throughput | **Example** Example request: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "scaling": "Manual", "manual": { "replicas": 2 } } } } } }' ``` Example response: ```json curl highlight={22,28} expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 // <---- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 // <---- current state } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. You can change node types in either direction (`b1` → `t1` or `t1` → `b1`). This operation does not require downtime, but can take up to 30 minutes to complete. The most predictable way to increase throughput is by increasing [replicas](#replicas). `t1` nodes [cache more data in memory](#node-types) than `b1` nodes. Because of this, switching from `b1` to `t1` may require more shards. If your new configuration doesn't have enough shards, the configuration change will fail with an error telling you how many shards are required. Update the request and retry. In the meantime, your index will continue to function normally in its original configuration. To change node types, call [Configure an index](/reference/api/2025-10/control-plane/configure_index). In the request body, set the following fields: | Field | Value | Notes | | :------------------------------------------------------ | :----------- | :---------------------------- | | **`spec.serverless.read_capacity.mode`** | `Dedicated` | | | **`spec.serverless.read_capacity.dedicated.node_type`** | `b1` or `t1` | See [node types](#node-types) | **Example** Example request to change from `b1` to `t1`: ```bash curl expandable theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1" } } } } }' ``` Example response: ```json curl expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "t1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 1 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } ``` Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. To pause an index, [set the number of replicas](#add-or-remove-replicas) to 0. This operation can take up to 30 minutes to complete. While an index is paused, you cannot write to it or read from it. For a paused index, you're billed for storage, but not for node costs, reads, or writes. After making a configuration change to a dedicated read nodes index (changing shards, replicas, or node type), check the status of the change by calling [Describe an index](/reference/api/2025-10/control-plane/describe_index). **Example** Example request: ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` Example response (index scaling from one to two replicas): ```json curl highlight={22,28} expandable theme={null} { "name": "example-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-dedicated-index-1c6ab6aa.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 // <---- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 // <---- current state } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } ``` The response includes two status fields: | Field | Description | | :----------------------------------------------- | :------------------------------------------------------------------------- | | **`status.state`** | Overall index status (for example, `Initializing`, `Ready`, `Terminating`) | | **`spec.serverless.read_capacity.status.state`** | Read capacity status (`Migrating`, `Scaling`, `Ready`, `Error`) | When changing node types, shards, or replicas, monitor the read capacity status (`spec.serverless.read_capacity.status.state`). Possible values: | State | Description | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`Ready`** | The change is complete and the index is ready to serve queries at full capacity. | | **`Scaling`** | A change to the number of shards or replicas is in progress. | | **`Migrating`** | A change to the node type or read capacity mode is in progress. | | **`Error`** | The operation failed. For migrations to dedicated, this typically means you didn't allocate enough shards for your index size. Check `error_message` for details, and retry with more shards. | During changes to shards, replicas, and node type, the index-level status (`status.state`) remains `Ready`. This is because the index can handle reads and writes while its dedicated read capacity scales. Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. To change a dedicated read nodes index to on-demand, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). This can't be done with the API. ## Limits The following limits apply to dedicated read nodes: Dedicated read nodes indexes are not subject to [read-operation rate limits](/reference/api/database-limits#rate-limits), like on-demand indexes are. However, if your query rate exceeds the compute capacity of your index, you may observe decreased query throughput. In such cases, consider [adding replicas](#add-or-remove-replicas) to increase the compute resources of the index. On dedicated read nodes indexes, write operations (upsert, update, delete) have the same [rate limits](/reference/api/database-limits#rate-limits) as on-demand indexes. Writes that would cause your index to exceed its storage capacity are blocked. In such cases, consider [adding shards](#add-or-remove-shards) to increase available storage. To determine how close to the write limit you are, [check index fullness](#monitor-index-fullness). Currently, dedicated read nodes indexes only support a single namespace. However, multi-namespace support is coming soon. For early access, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). **Shards** The minimum number of [shards](#shards) per index is 1. **Replicas** The minimum number of [replicas](#replicas) per index is 0, which [pauses the index](#pause-an-index). **Nodes** The maximum number of [nodes](#node-types) per project is 20. This is a **project** limit, not an index limit. To calculate your total node count, multiply `shards × replicas` for each of your project's indexes, and then sum the results. This total must not exceed 20. For example, if you have two indexes that each have two shards and three replicas, your total node count is `(2 × 3) + (2 × 3) = 12` nodes. To increase your project's node limit, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). Configuration change limits: * You can make one configuration change every ten minutes, but you can batch multiple changes (node type, shards, and replicas) in a single request. * A new configuration change can only be initiated after the previous configuration change has completed. * Each configuration change can take up to 30 minutes to complete. * Read and write operations continue normally during configuration changes. `memoryFullness` is an approximation and doesn't yet account for metadata. For more information, see [Index fullness](#index-fullness). To migrate an index from dedicated to on-demand, [contact support](https://app.pinecone.io/organizations/-/settings/support/ticket). This cannot be done with the API. ## Cost The cost of an index has three components: read costs, write costs, and storage costs. On-demand and dedicated read nodes share infrastructure for writes and storage, so these costs are the same. However, dedicated read nodes provision dedicated hardware for read operations (query, fetch, list), which changes how read costs are calculated. | Cost component | On-demand | Dedicated read nodes | | :---------------- | :------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | | **Read costs** | [Usage-based](/guides/manage-cost/understanding-cost#read-units): 1 RU per 1 GB namespace size per query | Fixed hourly rate: Based on [node type](#node-types), [shards](#shards), and [replicas](#replicas) | | **Write costs** | [Usage-based](/guides/manage-cost/understanding-cost#write-units) | [Usage-based](/guides/manage-cost/understanding-cost#write-units) (same as on-demand) | | **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage) | [Usage-based](/guides/manage-cost/understanding-cost#storage) (same as on-demand) | If you use a hosted model for search or reranking, there are additional [inference costs](/guides/manage-cost/understanding-cost#inference). To calculate the total cost of a dedicated read nodes index, use this formula: ``` (Node rate × shards × replicas) + storage costs + write costs ``` | Term | Description | | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Node rate** | Monthly rate for the [node type](#node-types) (`b1` or `t1`), which varies by cloud region. See [Pinecone pricing](https://www.pinecone.io/pricing/). | | **Shards** | Number of [shards](#shards) allocated | | **Replicas** | Number of [replicas](#replicas) allocated | | **Storage costs** | [Usage-based](/guides/manage-cost/understanding-cost#storage), same as on-demand | | **Write costs** | [Usage-based](/guides/manage-cost/understanding-cost#write-units), same as on-demand | For help estimating costs, use the [Pinecone pricing calculator](https://www.pinecone.io/pricing/estimate/) or [contact us](https://www.pinecone.io/contact/). **Example:** If the rate for `b1` nodes on `aws-us-east-1` is \$168.21/month (\$0.23/hour), an index with two shards and two replicas would cost: ``` 168.21 × 2 × 2 = $672.84/month, plus storage and write costs ``` # Implement multitenancy Source: https://docs.pinecone.io/guides/index-data/implement-multitenancy Use namespaces to isolate tenant data securely. [Multitenancy](https://en.wikipedia.org/wiki/Multitenancy) is a software architecture where a single instance of a system serves multiple customers, or tenants, while ensuring data isolation between them for privacy and security. This page shows you how to implement multitenancy in Pinecone using a **serverless index with one namespace per tenant**. While the Standard and Enterprise plans support up to [100,000 namespaces per index](/reference/api/database-limits#namespaces-per-serverless-index), Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## How it works In Pinecone, an [index](/guides/index-data/indexing-overview) is the highest-level organizational unit of data, where you define the dimension of vectors to be stored in the index and the measure of similarity to be used when querying the index. Within an index, records are stored in [namespaces](/guides/index-data/indexing-overview#namespaces), and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other [data plane operations](/reference/api/latest/data-plane) always target one namespace. This structure makes it easy to implement multitenancy. For example, for an AI-powered SaaS application where you need to isolate the data of each customer, you would assign each customer to a namespace and target their writes and queries to that namespace (diagram above). In cases where you have different workload patterns (e.g., RAG and semantic search), you would use a different index for each workload, with one namespace per customer in each index: * **Tenant isolation:** In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so using namespaces provides physical isolation of data between tenants/customers. * **No noisy neighbors:** Reads and writes always target a single namespace, so the behavior of one tenant/customer does not affect other tenants/customers. * **No maintenance effort:** Serverless indexes scale automatically based on usage; you don't configure or manage any compute or storage resources. * **Cost efficiency:** With serverless indexes, you pay only for the amount of data stored and operations performed. For queries in particular, the cost is partly based on the total number of records that must be scanned, so using namespaces can significantly reduce query costs. * **Simple tenant offboarding:** To offboard a tenant/customer, you just [delete the relevant namespace](/guides/manage-data/delete-data#delete-all-records-from-a-namespace). This is a lightweight and almost instant operation. ## 1. Create a serverless index Based on a [breakthrough architecture](/guides/get-started/database-architecture), serverless indexes scale automatically based on usage, and you pay only for the amount of data stored and operations performed. Combined with the isolation of tenant data using namespaces (next step), serverless indexes are ideal for multitenant use cases. To [create a serverless index](/guides/index-data/create-an-index#create-a-serverless-index), use the `spec` parameter to define the cloud and region where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="multitenant-app", dimension=8, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'multitenant-app', dimension: 8, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createServerlessIndex("multitenant-app", "cosine", 8, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Serverless index indexName := "multi-tenant-app" vectorType := "dense" dimension := int32(8) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "multitenant-app", Dimension = 8, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1", } }, DeletionProtection = DeletionProtection.Disabled }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "multitenant-app", "dimension": 8, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } } }' ``` ## 2. Isolate tenant data In a multitenant solution, you need to isolate data between tenants. To achieve this in Pinecone, use one namespace per tenant. In the [serverless architecture](/guides/get-started/database-architecture), each namespace is stored separately, so this approach ensures physical isolation of each tenant's data. To [create a namespace for a tenant](/guides/index-data/indexing-overview#namespaces#creating-a-namespace), specify the `namespace` parameter when first [upserting](/guides/index-data/upsert-data) the tenant's records. For example, the following code upserts records for `tenant1` and `tenant2` into the `multitenant-app` index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.upsert( vectors=[ {"id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]}, {"id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}, {"id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]}, {"id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]} ], namespace="tenant1" ) index.upsert( vectors=[ {"id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}, {"id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, {"id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, {"id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]} ], namespace="tenant2" ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace("tenant1").upsert([ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ]); await index.namespace("tenant2").upsert([ { "id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import java.util.Arrays; import java.util.List; public class UpsertExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "multitenant-app"; Index index = pc.getIndexConnection(indexName); List values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f); List values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f); List values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f); List values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f); List values5 = Arrays.asList(0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f); List values6 = Arrays.asList(0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f); List values7 = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f); List values8 = Arrays.asList(0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f); index.upsert("A", values1, "tenant1"); index.upsert("B", values2, "tenant1"); index.upsert("C", values3, "tenant1"); index.upsert("D", values4, "tenant1"); index.upsert("E", values5, "tenant2"); index.upsert("F", values6, "tenant2"); index.upsert("G", values7, "tenant2"); index.upsert("H", values8, "tenant2"); } } ``` ```go Go theme={null} // Add to the main function: idx, err := pc.DescribeIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } idxConnection1, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "tenant1"}) if err != nil { log.Fatalf("Failed to create IndexConnection1 for Host %v: %v", idx.Host, err) } // This reuses the gRPC connection of idxConnection1 while targeting a different namespace idxConnection2 := idxConnection1.WithNamespace("tenant2") vectors1 := []*pinecone.Vector{ { Id: "A", Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, }, { Id: "B", Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, }, { Id: "C", Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, }, { Id: "D", Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}, }, } vectors2 := []*pinecone.Vector{ { Id: "E", Values: []float32{0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5}, }, { Id: "F", Values: []float32{0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6}, }, { Id: "G", Values: []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7}, }, { Id: "H", Values: []float32{0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8}, }, } count1, err := idxConnection1.UpsertVectors(ctx, vectors1) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count1) } count2, err := idxConnection2.UpsertVectors(ctx, vectors2) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count2) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("multitenant-app"); var upsertResponse1 = await index.UpsertAsync(new UpsertRequest { Vectors = new[] { new Vector { Id = "A", Values = new[] { 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f }, }, new Vector { Id = "B", Values = new[] { 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f }, }, new Vector { Id = "C", Values = new[] { 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f }, }, new Vector { Id = "D", Values = new[] { 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f }, } }, Namespace = "tenant1", }); var upsertResponse2 = await index.UpsertAsync(new UpsertRequest { Vectors = new[] { new Vector { Id = "E", Values = new[] { 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f, 0.5f }, }, new Vector { Id = "F", Values = new[] { 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f, 0.6f }, }, new Vector { Id = "G", Values = new[] { 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f }, }, new Vector { Id = "H", Values = new[] { 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f, 0.8f }, } }, Namespace = "tenant2", }); ``` ```bash curl theme={null} # The `POST` requests below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ], "namespace": "tenant1" }' curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "F", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "G", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "H", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ], "namespace": "tenant2" }' ``` When upserting additional records for a tenant, or when [updating](/guides/manage-data/update-data) or [deleting](/guides/manage-data/delete-data) records for a tenant, specify the tenant's `namespace`. For example, the following code updates the dense vector value of record `A` in `tenant1`: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.update(id="A", values=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], namespace="tenant1") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace('tenant1').update({ id: 'A', values: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.UpdateResponse; import java.util.Arrays; import java.util.List; public class UpdateExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("multitenant-app"); List values = Arrays.asList(0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f); UpdateResponse updateResponse = index.update("A", values, null, "tenant1", null, null); System.out.println(updateResponse); } } ``` ```go Go theme={null} // Add to the main function: idxConn1.UpdateVector(ctx, &pinecone.UpdateVectorRequest{ Id: "A", Values: []float32{0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8}, }) if err != nil { log.Fatalf("Failed to update vector with ID %v: %v", id, err) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("multitenant-app"); var upsertResponse = await index.UpsertAsync(new UpsertRequest { Vectors = new[] { new Vector { Id = "A", Values = new[] { 0.1f, 0.2f, 0.3f, 0.4f, 0.5f, 0.6f, 0.7f, 0.8f }, } }, Namespace = "tenant1", }); ``` ```bash curl theme={null} # The `POST` request below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "A", "values": [01., 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], "namespace": "tenant1" }' ``` ## 3. Query tenant data In a multitenant solution, you need to ensure that the queries of one tenant do not affect the experience of other tenants/customers. To achieve this in Pinecone, target each tenant's [queries](/guides/search/search-overview) at the namespace for the tenant. For example, the following code queries only `tenant2` for the 3 vectors that are most similar to an example query vector: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") query_results = index.query( namespace="tenant2", vector=[0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], top_k=3, include_values=True ) print(query_results) # Returns: # {'matches': [{'id': 'F', # 'score': 1.00000012, # 'values': [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, # {'id': 'G', # 'score': 1.0, # 'values': [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, # {'id': 'E', # 'score': 1.0, # 'values': [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}], # 'namespace': 'tenant2', # 'usage': {'read_units': 6}} ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); const queryResponse = await index.namespace("tenant2").query({ topK: 3, vector: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], includeValues: true }); console.log(queryResponse); // Returns: { "matches": [ { "id": "F", "score": 1.00000012, "values": [ 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6 ] }, { "id": "E", "score": 1, "values": [ 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5 ] }, { "id": "G", "score": 1, "values": [ 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7 ] } ], "namespace": "tenant2", "usage": { "readUnits": 6 } } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "multitenant-app"; Index index = pc.getIndexConnection(indexName); List queryVector = Arrays.asList(0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, queryVector2, null, null, null, "tenant2", null, true, false); System.out.println(queryResponse); } } // Results: // class QueryResponseWithUnsignedIndices { // matches: [ScoredVectorWithUnsignedIndices { // score: 1.00000012 // id: F // values: [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }, ScoredVectorWithUnsignedIndices { // score: 1 // id: E // values: [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }, ScoredVectorWithUnsignedIndices { // score: 0.07999992 // id: G // values: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] // metadata: // sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { // indicesWithUnsigned32Int: [] // values: [] // } // }] // namespace: tenant2 // usage: read_units: 6 // } ``` ```go Go theme={null} // Add to the main function: queryVector := []float32{0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7} res, err := idxConnection2.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } // Returns: // { // "matches": [ // { // "vector": { // "id": "F", // "values": [ // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6, // 0.6 // ] // }, // "score": 1.0000001 // }, // { // "vector": { // "id": "G", // "values": [ // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7, // 0.7 // ] // }, // "score": 1 // }, // { // "vector": { // "id": "H", // "values": [ // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8, // 0.8 // ] // }, // "score": 1 // } // ], // "usage": { // "read_units": 6 // } // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("multitenant-app"); var queryResponse = await index.QueryAsync(new QueryRequest { Vector = new[] { 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f, 0.7f }, Namespace = "tenant2", TopK = 3, }); Console.WriteLine(queryRespnose); ``` ```shell curl theme={null} # The `POST` requests below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "tenant2", "vector": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7], "topK": 3, "includeValues": true }' # # Output: # { # "matches": [ # { # "id": "F", # "score": 1.00000012, # "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] # }, # { # "id": "E", # "score": 1, # "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] # }, # { # "id": "G", # "score": 1, # "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] # } # ], # "namespace": "tenant2", # "usage": {"read_units": 6} # } ``` ## 4. Offboard a tenant In a multitenant solution, you also need it to be quick and easy to offboard a tenant and delete all of its records. To achieve this in Pinecone, you just [delete the namespace](/guides/manage-data/delete-data#delete-an-entire-namespace) for the specific tenant. For example, the following code deletes the namespace and all records for `tenant1`: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("multitenant-app") index.delete(delete_all=True, namespace='tenant1') ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = pc.index("multitenant-app"); await index.namespace('tenant1').deleteAll(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class DeleteVectorsExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("multitenant-app"); index.deleteAll("tenant1"); } } ``` ```go Go theme={null} // Add to the main function: idxConnection1.DeleteAllVectorsInNamespace(ctx) if err != nil { log.Fatalf("Failed to delete vectors in namespace \"%v\": %v", idxConnection2.Namespace, err) } ``` ```csharp C# theme={null} var index = pinecone.Index("multitenant-app"); var deleteResponse = await index.DeleteAsync(new DeleteRequest { DeleteAll = true, Namespace = "tenant1", }); ``` ```bash curl theme={null} # The `POST` request below uses the unique endpoint for an index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deleteAll": true, "namespace": "tenant1" } ' ``` ## Alternative: Metadata filtering When tenant isolation is not a strict requirement, or when you need to query across multiple tenants simultaneously, you can store all records in a single namespace and use metadata fields to assign records to tenants/customers. At query time, you can then [filter by metadata](/guides/index-data/indexing-overview#metadata). For more guidance on this approach, see [Multitenancy in Vector Databases](https://www.pinecone.io/learn/series/vector-databases-in-production-for-busy-engineers/vector-database-multi-tenancy/). # Import records Source: https://docs.pinecone.io/guides/index-data/import-data Import large datasets efficiently from S3, GCS, or Azure into Pinecone indexes. Importing from object storage is the most efficient and cost-effective way to load large numbers of records into an index. To run through this guide in your browser, see the [Bulk import colab notebook](https://colab.research.google.com/github/pinecone-io/examples/blob/master/docs/pinecone-import.ipynb). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Before you import Before you can import records, ensure you have a serverless index, a storage integration, and data formatted in a Parquet file and uploaded to an Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container. ### Create an index [Create a serverless index](/guides/index-data/create-an-index) for your data. Be sure to create your index on a cloud that supports importing from the object storage you want to use: | | …to an **AWS** index | …to a **GCP** index | …to an **Azure** index | | ------------------------------------- | :------------------: | :-----------------: | :--------------------: | | Import from **AWS S3**… | ✅ | ❌ | ❌ | | Import from **Google Cloud Storage**… | ✅ | ✅ | ✅ | | Import from **Azure Blob Storage**… | ✅ | ✅ | ✅ | ### Add a storage integration To import records from a public data source, a storage integration is not required. However, to import records from a secure data source, you must create an integration to allow Pinecone access to data in your object storage. See the following guides: * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) ### Prepare your data 1. In your Amazon S3 bucket, Google Cloud Storage bucket, or Azure Blob Storage container, create an import directory containing a subdirectory for each namespace you want to import into. The namespaces must not yet exist in your index. For example, to import data into the namespaces `example_namespace1` and `example_namespace2`, your directory structure would look like this: ``` / --// ----/example_namespace1/ ----/example_namespace2/ ``` To import into the default namespace, use a subdirectory called `__default__`. The default namespace must be empty. 2. For each namespace, create one or more Parquet files defining the records to import. Parquet files must contain specific columns, depending on the index type: To import into a namespace in a [dense index](/guides/index-data/indexing-overview#dense-indexes), the Parquet file must contain the following columns: | Column name | Parquet type | Description | | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `id` | `STRING` | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id). | | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector). | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | The Parquet file cannot contain additional columns. For example: ```parquet theme={null} id | values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | [ 3.82 2.48 -4.15 ... ] | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | [ 1.82 3.48 -2.15 ... ] | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` To import into a namespace in a [sparse index](/guides/index-data/indexing-overview#sparse-indexes), the Parquet file must contain the following columns: | Column name | Parquet type | Description | | --------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `STRING` | Required. The unique [identifier for each record](/guides/get-started/concepts#record-id). | | `sparse_values` | `LIST` and `LIST` | Required. A list of floating-point values (sparse values) and a list of integer values (sparse indices) that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | The Parquet file cannot contain additional columns. For example: ```parquet theme={null} id | sparse_values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | {"indices": [ 822745112 1009084850 1221765879 ... ], "values": [1.7958984 0.41577148 2.828125 ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | {"indices": [ 504939989 1293001993 3201939490 ... ], "values": [1.4383747 0.72849722 1.384775 ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` To import into a namespace in a [hybrid index](/guides/search/hybrid-search#use-a-single-hybrid-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/concepts#record-id). | | `values` | `LIST` | Required. A list of floating-point values that make up the [dense vector embedding](/guides/get-started/concepts#dense-vector). | | `sparse_values` | `STRUCT, values: LIST>` | Optional. A list of floating-point values that make up the [sparse vector embedding](/guides/get-started/concepts#sparse-vector). To omit from specific rows, use `NULL`. | | `metadata` | `STRING` | Optional. Additional [metadata](/guides/get-started/concepts#metadata) for each record. To omit from specific rows, use `NULL`. | The Parquet file cannot contain additional columns. For example: ```parquet theme={null} id | values | sparse_values | metadata -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1 | [ 3.82 2.48 -4.15 ... ] | {"indices": [1082468256, 1009084850, 1221765879, ...], "values": [2.0, 3.0, 4.0, ...]} | {"year": 1984, "month": 6, "source": "source1", "title": "Example1", "text": "When ..."} 2 | [ 1.82 3.48 -2.15 ... ] | {"indices": [2225824123, 1293001993, 3201939490, ...], "values": [5.0, 2.0, 3.0, ...]} | {"year": 1990, "month": 4, "source": "source2", "title": "Example2", "text": "Who ..."} ``` 3. Upload the Parquet files into the relevant subdirectory. For example, if you have subdirectories for the namespaces `example_namespace1` and `example_namespace2` and upload 4 Parquet files into each, your directory structure would look as follows after the upload: ``` / --// ----/example_namespace1/ ------0.parquet ------1.parquet ------2.parquet ------3.parquet ----/example_namespace2/ ------4.parquet ------5.parquet ------6.parquet ------7.parquet ``` ## Import records into an index Review [import limits](#import-limits) before starting an import. Use the [`start_import`](/reference/api/latest/data-plane/start_import) operation to start an asynchronous import of vectors from object storage into an index. * For `uri`, specify the URI of the bucket and import directory containing the namespaces and Parquet files you want to import. For example: * Amazon S3: `s3://BUCKET_NAME/IMPORT_DIR` * Google Cloud Storage: `gs://BUCKET_NAME/IMPORT_DIR` * Azure Blob Storage: `https://STORAGE_ACCOUNT.blob.core.windows.net/CONTAINER_NAME/IMPORT_DIR` * For `integration_id`, specify the Integration ID of the Amazon S3, Google Cloud Storage, or Azure Blob Storage integration you created. The ID is found on the [Storage integrations](https://app.pinecone.io/organizations/-/projects/-/storage) page of the Pinecone console. An Integration ID is not needed to import from a public bucket. * For `error_mode`, use `CONTINUE` or `ABORT`. * With `ABORT`, the operation stops if any records fail to import. * With `CONTINUE`, the operation continues on error, but there is not any notification about which records, if any, failed to import. To see how many records were successfully imported, use the [describe an import](#describe-an-import) operation. ```python Python theme={null} from pinecone import Pinecone, ImportErrorMode pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") root = "s3://example_bucket/import" index.start_import( uri=root, integration_id="a12b3d4c-47d2-492c-a97a-dd98c8dbefde", # Optional for public buckets error_mode=ImportErrorMode.CONTINUE # or ImportErrorMode.ABORT ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const storageURI = 's3://example_bucket/import'; const errorMode = 'continue'; // or 'abort' const integrationID = 'a12b3d4c-47d2-492c-a97a-dd98c8dbefde'; // Optional for public buckets await index.startImport(storageURI, errorMode, integrationID); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ImportErrorMode; import org.openapitools.db_data.client.model.StartImportResponse; public class StartImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // s3 uri String uri = "s3://example_bucket/import"; // Integration ID (optional for public buckets) String integrationId = "a12b3d4c-47d2-492c-a97a-dd98c8dbefde"; // Start an import StartImportResponse response = asyncIndex.startImport(uri, integrationId, ImportErrorMode.OnErrorEnum.CONTINUE); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } uri := "s3://example_bucket/import" errorMode := "continue" // or "abort" importRes, err := idxConnection.StartImport(ctx, uri, nil, (*pinecone.ImportErrorMode)(&errorMode)) if err != nil { log.Fatalf("Failed to start import: %v", err) } fmt.Printf("Import started with ID: %s", importRes.Id) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var uri = "s3://example_bucket/import"; var response = await index.StartBulkImportAsync(new StartImportRequest { Uri = uri, IntegrationId = "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", ErrorMode = new ImportErrorMode { OnError = ImportErrorModeOnError.Continue } }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/bulk/imports" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -H 'X-Pinecone-Api-Version: 2025-10' \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "s3://example_bucket/import", "errorMode": { "onError": "continue" } }' ``` The response contains an `id` that you can use to [check the status of the import](#list-imports): ```json Response theme={null} { "id": "101" } ``` Once all the data is loaded, the [index builder](/guides/get-started/database-architecture#index-builder) indexes the records, which usually takes at least 10 minutes. During this indexing process, the expected job status is `InProgress`, but `100.0` percent complete. Once all the imported records are indexed and fully available for querying, the import operation is set to `Completed`. You can start a new import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index you want to import into, and click the **ellipsis (...) menu > Import data**. ## Track import progress The amount of time required for an import depends on various factors, including: * The number of records to import * The number of namespaces to import, and the the number of records in each * The total size (in bytes) of the import To track an import's progress, check its status bar in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or use the [`describe_import`](/reference/api/latest/data-plane/describe_import) operation with the import ID: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.describe_import(id="101") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const results = await index.describeImport(id='101'); console.log(results); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ImportModel; public class DescribeImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // Describe import ImportModel importDetails = asyncIndex.describeImport("101"); System.out.println(importDetails); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } importID := "101" importDesc, err := idxConnection.DescribeImport(ctx, importID) if err != nil { log.Fatalf("Failed to describe import: %s - %v", importID, err) } fmt.Printf("Import ID: %s, Status: %s", importDesc.Id, importDesc.Status) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var importDetails = await index.DescribeBulkImportAsync("101"); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://{INDEX_HOST}/bulk/imports/101" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` The response contains the import details, including the import `status`, `percent_complete`, and `records_imported`: ```json Response theme={null} { "id": "101", "uri": "s3://example_bucket/import", "status": "InProgress", "created_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ``` If the import fails, the response contains an `error` field with the reason for the failure. See the [Troubleshooting](#troubleshooting) section for more information. ```json Response theme={null} { "id": "102", "uri": "s3://example_bucket/import", "status": "Failed", "percent_complete": 0.0, "records_imported": 0, "created_at": "2025-08-21T11:29:47.886797+00:00", "error": "User error: The namespace \"namespace1\" already exists. Imports are only allowed into nonexistent namespaces.", "finished_at": "2025-08-21T11:30:05.506423+00:00" } ``` ## Manage imports ### List imports Use the [`list_imports`](/reference/api/latest/data-plane/list_imports) operation to list all of the recent and ongoing imports. By default, the operation returns up to 100 imports per page. If the `limit` parameter is passed, the operation returns up to that number of imports per page instead. For example, if `limit=3`, up to 3 imports are returned per page. Whenever there are additional imports to return, the response includes a `pagination_token` for fetching the next page of imports. When using the Python SDK, `list_import` paginates automatically. ```python Python theme={null} from pinecone import Pinecone, ImportErrorMode pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # List using a generator that handles pagination for i in index.list_imports(): print(f"id: {i.id} status: {i.status}") # List using a generator that fetches all results at once operations = list(index.list_imports()) print(operations) ``` ```json Response theme={null} { "data": [ { "id": "1", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "started_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` You can view the list of imports for an index in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/). Select the index and navigate to the **Imports** tab. When using the Node.js SDK, Java SDK, Go SDK, .NET SDK, or REST API to list recent and ongoing imports, you must manually fetch each page of results. To view the next page of results, include the `paginationToken` provided in the response. ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const results = await index.listImports({ limit: 10, paginationToken: 'Tm90aGluZyB0byBzZWUgaGVyZQo' }); console.log(results); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.ListImportsResponse; public class ListImports { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // List imports ListImportsResponse response = asyncIndex.listImports(10, "Tm90aGluZyB0byBzZWUgaGVyZQo"); System.out.println(response); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := int32(10) firstImportPage, err := idxConnection.ListImports(ctx, &limit, nil) if err != nil { log.Fatalf("Failed to list imports: %v", err) } fmt.Printf("First page of imports: %+v", firstImportPage.Imports) paginationToken := firstImportPage.NextPaginationToken nextImportPage, err := idxConnection.ListImports(ctx, &limit, paginationToken) if err != nil { log.Fatalf("Failed to list imports: %v", err) } fmt.Printf("Second page of imports: %+v", nextImportPage.Imports) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var imports = await index.ListBulkImportsAsync(new ListBulkImportsRequest { Limit = 10, PaginationToken = "Tm90aGluZyB0byBzZWUgaGVyZQo" }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \ -H 'Api-Key: $YOUR_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` ### Cancel an import The [`cancel_import`](/reference/api/latest/data-plane/cancel_import) operation cancels an import if it is not yet finished. It has no effect if the import is already complete. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.cancel_import(id="101") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.cancelImport(id='101'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.AsyncIndex; import org.openapitools.db_data.client.ApiException; public class CancelImport { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); // Get async imports connection object AsyncIndex asyncIndex = pinecone.getAsyncIndexConnection("docs-example"); // Cancel import asyncIndex.cancelImport("2"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } importID := "101" err = idxConnection.CancelImport(ctx, importID) if err != nil { log.Fatalf("Failed to cancel import: %s", importID) } importDesc, err := idxConnection.DescribeImport(ctx, importID) if err != nil { log.Fatalf("Failed to describe import: %s - %v", importID, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var cancelResponse = await index.CancelBulkImportAsync("101"); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://{INDEX_HOST}/bulk/imports/101" \ -H 'Api-Key: $YOUR_API_KEY' \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json Response theme={null} {} ``` You can cancel your import using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import). To cancel an ongoing import, select the index you are importing into and navigate to the **Imports** tab. Then, click the **ellipsis (...) menu > Cancel**. ## Import limits If your import exceeds these limits, you'll get an `Exceeds system limit` error. Pinecone can help unblock these imports quickly. [Contact Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance. | Metric | Limit | | :------------------------ | :------ | | Max namespaces per import | 10,000 | | Max size per namespace | 500 GB | | Max files per import | 100,000 | | Max size per file | 10 GB | Also: * You cannot import data from an AWS S3 bucket into a Pinecone index hosted on GCP or Azure. * You cannot import data from S3 Express One Zone storage. * You cannot import data into an existing namespace. * When importing data into the `__default__` namespace of an index, the default namespace must be empty. * Each import takes at least 10 minutes to complete. * When importing into an [index with integrated embedding](/guides/index-data/indexing-overview#vector-embedding), records must contain vectors, not text. To add records with text, you must use [upsert](/guides/index-data/upsert-data). ## Troubleshooting When an import fails, you'll see an error message with the reason for the failure in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/import) or in the response to the [describe an import](/reference/api/latest/data-plane/describe_import) operation. You cannot import data into an existing namespace. If your import directory structure contains a folder with the name of an existing namespace in your index, the import will fail with the following error: ``` User error: The namespace "example-namespace" already exists. Imports are only allowed into nonexistent namespaces. ``` To fix this, rename the folder to use a namespace name that does not yet exist. In object storage, your directory structure must be as follows: ``` example_bucket/ --/imports/ ----/example_namespace1/ ------0.parquet ------1.parquet ------2.parquet ------3.parquet ----/example_namespace2/ ------4.parquet ------5.parquet ------6.parquet ------7.parquet ``` If a Parquet file is not nested under a namespace subdirectory, the import will fail with the following error: ``` User error: \"test-import/0.parquet\": No namespace detected. Each file should be nested under a subdirectory of the URI prefix. This indicates which namespace it should be imported into. ``` To fix this, move the Parquet file to a namespace subdirectory. Each namespace subdirectory must contain Parquet files with data to import. If a namespace subdirectory does not include Parquet files, the import will fail with the following error: ``` User error: No Parquet files found under \"gs://example_bucket/imports\". Files must be stored with the specified bucket prefix. ``` To fix this, add Parquet files to the namespace subdirectory. In your [start import](/reference/api/latest/data-plane/start_import) request, the import `uri` must specify only the bucket and import directory containing the namespaces and Parquet files you want to import. If the `uri` also contains a namespaces directory or a Parquet filename, the import will fail with the following error: ``` User error: \"test-import/0.parquet\": It looks like you specified a complete path to a parquet file as the URI prefix to import from. Note that the URI prefix should give an ancestor directory with subdirectories to specify each namespace to import into. See https://docs.pinecone.io/guides/data/understanding-imports#directory-structure. ``` To fix this, remove the namespaces directory or Parquet filename from the `uri`. When a Parquet file is not formatted correctly, the import will fail with a message like one of the following: ```shell File schema errors theme={null} Missing required column \"{0}\" Unsupported column \"{0}\" ``` ```shell File corruption errors theme={null} Parquet footer could not be parsed. Are you sure this is valid parquet? ``` ```shell Type errors theme={null} The expected data type for column \"{column}\" is \"{expected}\", but got \"{given}\" The expected data type for metadata is a JSON encoded string in UTF-8 format, but got \"{given}\" ``` These errors are returned for both `CONTINUE` and `ABORT` error modes. To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section. When the `error_mode` is `ABORT` and a file contains invalid records, the import will stop processing on the first invalid record and return an error message identifying the file name and row: ``` User error: error reading record (file \"/0.parquet\", row 0): ``` This will be followed by an error message identifying the specific issue. For example: ```shell Missing values theme={null} missing required values in column \"{column}\" ``` ```shell Invalid metadata theme={null} Failed to parse metadata: {msg} ``` ```shell Invalid vectors theme={null} Upserting dense vectors is not supported for sparse indexes ``` When the `error_mode` is `CONTINUE`, the import will skip individual invalid records. However, if all records are invalid and skipped (for example, the vector type in the file does not match the vector type of the index), the import will fail with a general message: ``` User error: No vectors added, all rows were skipped for namespace: example-namespace ``` To fix these errors, check the specific error message and follow the instructions in the [Prepare your data](#prepare-your-data) section. When your import contains duplicate vectors (records with identical vector values), the duplicates are marked as skipped and not imported. Only one occurrence of each unique vector is added to the index. This applies to both `CONTINUE` and `ABORT` error modes: * With `ABORT`: The import fails when it encounters a duplicate vector within the import. * With `CONTINUE`: The import proceeds, skipping duplicate records silently. **Example scenario:** If your Parquet file contains: ```parquet theme={null} id | values ---|--------- 1 | [0.1, 0.2, 0.3] 2 | [0.1, 0.2, 0.3] ← Duplicate of record 1, will be skipped 3 | [0.4, 0.5, 0.6] ``` Only records 1 and 3 will be imported. To prevent this from happening, deduplicate your source data before creating Parquet files by removing records with identical vector values. ## See also * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) * [Pinecone's pricing](https://www.pinecone.io/pricing/) # Indexing overview Source: https://docs.pinecone.io/guides/index-data/indexing-overview Understand key concepts related to indexing data in Pinecone. export const word_0 = "records" ## Indexes In Pinecone, you store vector data in indexes. There are two types of indexes: dense and sparse. ### Dense indexes Dense indexes store dense vectors, which are a series of numbers that represent the meaning and relationships of text, images, or other types of data. 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. When you query a dense index, Pinecone retrieves the dense vectors that are the most semantically similar to the query. This is often called **semantic search**, nearest neighbor search, similarity search, or just vector search. Learn more: * [Create a dense index](/guides/index-data/create-an-index#create-a-dense-index) * [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors) * [Semantic search](/guides/search/semantic-search) ### Sparse indexes Sparse indexes store sparse vectors, which are a series of numbers that represent the words or phrases in a document. Sparse vectors 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. When you search a sparse index, Pinecone retrieves the sparse vectors that most exactly match the words or phrases in the query. Query terms are scored independently and then summed, with the most similar records scored highest. This is often called **lexical search** or **keyword search**. Learn more: * [Create a sparse index](/guides/index-data/create-an-index#create-a-sparse-index) * [Upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors) * [Lexical search](/guides/search/lexical-search) Semantic search can miss results based on exact keyword matches, while lexical search can miss results based on relationships. To lift these limitations, you can perform [hybrid search](/guides/search/hybrid-search). #### Limitations These limitations are subject to change during the public preview period. Sparse indexes have the following limitations: * Max non-zero values per sparse vector: 1000 * Max upserts per second per sparse index: 10 * Max queries per second per sparse index: 100 * Max `top_k` value per query: 1000 You may get fewer than `top_k` results if `top_k` is larger than the number of sparse vectors in your index that match your query. That is, any vectors where the dotproduct score is `0` will be discarded. * Max query results size: 4MB ## Namespaces Within an index, records are partitioned into namespaces, and all [upserts](/guides/index-data/upsert-data), [queries](/guides/search/search-overview), and other [data operations](/guides/index-data/upsert-data) always target one namespace. This has two main benefits: * **Multitenancy:** When you need to isolate data between customers, you can use one namespace per customer and target each customer's writes and queries to their dedicated namespace. See [Implement multitenancy](/guides/index-data/implement-multitenancy) for end-to-end guidance. * **Faster queries:** When you divide records into namespaces in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to fetching records, listing record IDs, and other data operations. Namespaces are created automatically during [upsert](/guides/index-data/upsert-data). If a namespace doesn't exist, it is created implicitly. While the Standard and Enterprise plans support up to [100,000 namespaces per index](/reference/api/database-limits#namespaces-per-serverless-index), Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Vector embedding [Dense vectors](/guides/get-started/concepts#dense-vector) and [sparse vectors](/guides/get-started/concepts#sparse-vector) are the basic units of data in Pinecone and what Pinecone was specially designed to store and work with. Dense vectors represents the semantics of data such as text, images, and audio recordings, while sparse vectors represent documents or queries in a way that captures keyword information. To transform data into vector format, you use an embedding model. You can either use Pinecone's integrated embedding models to convert your source data to vectors automatically, or you can use an external embedding model and bring your own vectors to Pinecone. ### Integrated embedding 1. [Create an index](/guides/index-data/create-an-index) that is integrated with one of Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models). 2. [Upsert](/guides/index-data/upsert-data) your source text. Pinecone uses the integrated model to convert the text to vectors automatically. 3. [Search](/guides/search/search-overview) with a query text. Again, Pinecone uses the integrated model to convert the text to a vector automatically. Indexes with integrated embedding do not support [updating](/guides/manage-data/update-data) or [importing](/guides/index-data/import-data) with text. ### Bring your own vectors 1. Use an embedding model to convert your text to vectors. The model can be [hosted by Pinecone](/reference/api/latest/inference/generate-embeddings) or an external provider. 2. [Create an index](/guides/index-data/create-an-index) that matches the characteristics of the model. 3. [Upsert](/guides/index-data/upsert-data) your vectors directly. 4. Use the same external embedding model to convert a query to a vector. 5. [Search](/guides/search/search-overview) with your query vector directly. ## Data ingestion To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. There are two ways to ingest data into an index: * [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective way to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. * [Upserting](/guides/index-data/upsert-data) is intended for ongoing writes to an index. [Batch upserting](/guides/index-data/upsert-data#upsert-in-batches) can improve throughput performance and is a good option for larger numbers of records (up to 1000 per batch) if you cannot work around import's current limitations. ## Metadata Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a vector. In addition, you can include metadata key-value pairs to store additional information or context. When you query the index, you can then include a [metadata filter](/guides/search/filter-by-metadata) to limit the search to records matching a filter expression. Searches without metadata filters do not consider metadata and search the entire namespace. ### Metadata format * Metadata fields must be key-value pairs in a flat JSON object. Nested JSON objects are not supported. * Keys must be strings and must not start with a `$`. * Values must be one of the following data types: * String * Integer (converted to a 64-bit floating point by Pinecone) * Floating point * Boolean (`true`, `false`) * List of strings * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. **Examples** ```json Valid metadata theme={null} { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "is_public": true, "tags": ["beginner", "database", "vector-db"], "scores": ["85", "92"] } ``` ```json Invalid metadata theme={null} { "document": { // Nested JSON objects are not supported "document_id": "document1", "document_title": "Introduction to Vector Databases", }, "$chunk_number": 1, // Keys must not start with a `$` "chunk_text": null, // Null values are not supported "is_public": true, "tags": ["beginner", "database", "vector-db"], "scores": [85, 92] // Lists of non-strings are not supported } ``` ### Metadata size Pinecone supports 40KB of metadata per record. ### Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :-------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `$eq` | Matches {word_0} with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches {word_0} with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches {word_0} with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches {word_0} with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches {word_0} with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches {word_0} with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches {word_0} with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches {word_0} with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches {word_0} with the specified metadata field. Example: `{"genre": {"$exists": true}}` | Number, string, boolean | | `$and` | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | | `$or` | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | Only `$and` and `$or` are allowed at the top level of the query expression. For example, the following has a `"genre"` metadata field with a list of strings: ```JSON JSON theme={null} { "genre": ["comedy", "documentary"] } ``` This means `"genre"` takes on both values, and requests with the following filters will match: ```JSON JSON theme={null} {"genre":"comedy"} {"genre": {"$in":["documentary","action"]}} {"$and": [{"genre": "comedy"}, {"genre":"documentary"}]} ``` However, requests with the following filter will **not** match: ```JSON JSON theme={null} { "$and": [{ "genre": "comedy" }, { "genre": "drama" }] } ``` Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error: ```json JSON theme={null} # INVALID QUERY: {"genre": ["comedy", "documentary"]} ``` ```json JSON theme={null} # INVALID QUERY: {"genre": {"$eq": ["comedy", "documentary"]}} ``` # Upsert records Source: https://docs.pinecone.io/guides/index-data/upsert-data Add or update records in Pinecone indexes and manage data with namespaces. This page shows you how to upsert records into a namespace in an index. [Namespaces](/guides/index-data/indexing-overview#namespaces) let you partition records within an index and are essential for [implementing multitenancy](/guides/index-data/implement-multitenancy) when you need to isolate the data of each customer/user. If a record ID already exists, upserting overwrites the entire record. To change only part of a record, [update ](/guides/manage-data/update-data) the record. To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ## Upsert dense vectors Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To upsert source text into a [dense index with integrated embedding](/guides/index-data/create-an-index#create-a-dense-index), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to dense vectors automatically using the hosted dense embedding model associated with the index. * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`. * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index. * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata). For example, the following code converts the sentences in the `chunk_text` fields to dense vectors and then upserts them into `example-namespace` in an example index. The additional `category` field is stored as metadata. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` fields are stored as metadata index.upsert_records( "example-namespace", [ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", }, ] ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); // Upsert records into a namespace // `chunk_text` fields are converted to dense vectors // `category` is stored as metadata await namespace.upsertRecords([ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import java.util.*; public class UpsertText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); ArrayList> upsertRecords = new ArrayList<>(); HashMap record1 = new HashMap<>(); record1.put("_id", "rec1"); record1.put("category", "digestive system"); record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."); HashMap record2 = new HashMap<>(); record2.put("_id", "rec2"); record2.put("category", "cultivation"); record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today."); HashMap record3 = new HashMap<>(); record3.put("_id", "rec3"); record3.put("category", "immune system"); record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."); HashMap record4 = new HashMap<>(); record4.put("_id", "rec4"); record4.put("category", "endocrine system"); record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."); upsertRecords.add(record1); upsertRecords.add(record2); upsertRecords.add(record3); upsertRecords.add(record4); index.upsertRecords("example-namespace", upsertRecords); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into a namespace // `chunk_text` fields are converted to dense vectors // `category` is stored as metadata records := []*pinecone.IntegratedRecord{ { "_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system", }, { "_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation", }, { "_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system", }, { "_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system", }, } err = idxConnection.UpsertRecords(ctx, records) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index(host: "INDEX_HOST"); await index.UpsertRecordsAsync( "example-namespace", [ new UpsertRecord { Id = "rec1", AdditionalProperties = { ["chunk_text"] = "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", ["category"] = "technology", ["quarter"] = "Q3", }, }, new UpsertRecord { Id = "rec2", AdditionalProperties = { ["chunk_text"] = "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", ["category"] = "technology", ["quarter"] = "Q4", }, }, new UpsertRecord { Id = "rec3", AdditionalProperties = { ["chunk_text"] = "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", ["category"] = "technology", ["quarter"] = "Q4", }, }, new UpsertRecord { Id = "rec4", AdditionalProperties = { ["chunk_text"] = "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", ["category"] = "technology", ["quarter"] = "Q3", }, }, ] ); ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` is stored as metadata curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"} {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"} {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"} {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}' ``` To upsert dense vectors into a [dense index](/guides/index-data/create-an-index#create-a-dense-index), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows: * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `id` field with a unique record identifier for the index namespace. * A `values` field with the dense vector values. * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata). ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( vectors=[ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "metadata": {"genre": "comedy", "year": 2019} }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "metadata": {"genre": "drama"} } ], namespace="example-namespace" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const records = [ { id: 'A', values: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], metadata: { genre: "comedy", year: 2020 }, }, { id: 'B', values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], metadata: { genre: "documentary", year: 2019 }, }, { id: 'C', values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], metadata: { genre: "comedy", year: 2019 }, }, { id: 'D', values: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], metadata: { genre: "drama" }, } ] await index.('example-namespace').upsert(records); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class UpsertExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List values1 = Arrays.asList(0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f); List values2 = Arrays.asList(0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f); List values3 = Arrays.asList(0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f); List values4 = Arrays.asList(0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f); Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2020).build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metaData4 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); index.upsert("A", values1, null, null, metaData1, 'example-namespace'); index.upsert("B", values2, null, null, metaData2, 'example-namespace'); index.upsert("C", values3, null, null, metaData3, 'example-namespace'); index.upsert("D", values4, null, null, metaData4, 'example-namespace'); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } metadataMap1 := map[string]interface{}{ "genre": "comedy", "year": 2020, } metadata1, err := structpb.NewStruct(metadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap2 := map[string]interface{}{ "genre": "documentary", "year": 2019, } metadata2, err := structpb.NewStruct(metadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap3 := map[string]interface{}{ "genre": "comedy", "year": 2019, } metadata3, err := structpb.NewStruct(metadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } metadataMap4 := map[string]interface{}{ "genre": "drama", } metadata4, err := structpb.NewStruct(metadataMap4) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } vectors := []*pinecone.Vector{ { Id: "A", Values: []float32{0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1}, Metadata: metadata1, }, { Id: "B", Values: []float32{0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2}, Metadata: metadata2, }, { Id: "C", Values: []float32{0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3}, Metadata: metadata3, }, { Id: "D", Values: []float32{0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4}, Metadata: metadata4, }, } count, err := idxConnection.UpsertVectors(ctx, vectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var upsertResponse = await index.UpsertAsync(new UpsertRequest { Vectors = new[] { new Vector { Id = "A", Values = new[] { 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f, 0.1f }, Metadata = new Metadata { ["genre"] = new("comedy"), ["year"] = new(2020), }, }, new Vector { Id = "B", Values = new[] { 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f, 0.2f }, Metadata = new Metadata { ["genre"] = new("documentary"), ["year"] = new(2019), }, }, new Vector { Id = "C", Values = new[] { 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f, 0.3f }, Metadata = new Metadata { ["genre"] = new("comedy"), ["year"] = new(2019), }, }, new Vector { Id = "D", Values = new[] { 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f, 0.4f }, Metadata = new Metadata { ["genre"] = new("drama"), }, } }, Namespace = "example-namespace", }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} }, { "id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "metadata": {"genre": "comedy", "year": 2019} }, { "id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4], "metadata": {"genre": "drama"} } ], "namespace": "example-namespace" }' ``` ## Upsert sparse vectors Upserting text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To upsert source text into a [sparse index with integrated embedding](/guides/index-data/create-an-index#create-a-sparse-index), use the [`upsert_records`](/reference/api/latest/data-plane/upsert_records) operation. Pinecone converts the text to sparse vectors automatically using the hosted sparse embedding model associated with the index. * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `_id` field with a unique record identifier for the index namespace. `id` can be used as an alias for `_id`. * A field with the source text to convert to a vector. This field must match the `field_map` specified in the index. * Additional fields are stored as record [metadata](/guides/index-data/indexing-overview#metadata) and can be returned in search results or used to [filter search results](/guides/search/filter-by-metadata). For example, the following code converts the sentences in the `chunk_text` fields to sparse vectors and then upserts them into `example-namespace` in an example index. The additional `category` and `quarter` fields are stored as metadata. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Upsert records into a namespace # `chunk_text` fields are converted to sparse vectors # `category` and `quarter` fields are stored as metadata index.upsert_records( "example-namespace", [ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" }, { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } ] ) time.sleep(10) # Wait for the upserted vectors to be indexed ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); // Upsert records into a namespace // `chunk_text` fields are converted to sparse vectors // `category` and `quarter` fields are stored as metadata await namespace.upsertRecords([ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" }, { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } ]); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import java.util.*; public class UpsertText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-sparse-java"); ArrayList> upsertRecords = new ArrayList<>(); HashMap record1 = new HashMap<>(); record1.put("_id", "rec1"); record1.put("category", "digestive system"); record1.put("chunk_text", "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."); HashMap record2 = new HashMap<>(); record2.put("_id", "rec2"); record2.put("category", "cultivation"); record2.put("chunk_text", "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today."); HashMap record3 = new HashMap<>(); record3.put("_id", "rec3"); record3.put("category", "immune system"); record3.put("chunk_text", "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."); HashMap record4 = new HashMap<>(); record4.put("_id", "rec4"); record4.put("category", "endocrine system"); record4.put("chunk_text", "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes."); upsertRecords.add(record1); upsertRecords.add(record2); upsertRecords.add(record3); upsertRecords.add(record4); index.upsertRecords("example-namespace", upsertRecords); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into a namespace // `chunk_text` fields are converted to sparse vectors // `category` and `quarter` fields are stored as metadata records := []*pinecone.IntegratedRecord{ { "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3", }, { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", }, { "_id": "vec3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3", }, { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4", }, } err = idxConnection.UpsertRecords(ctx, records) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index(host: "INDEX_HOST"); await index.UpsertRecordsAsync( "example-namespace", [ new UpsertRecord { Id = "rec1", AdditionalProperties = { ["chunk_text"] = "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", ["category"] = "technology", ["quarter"] = "Q3", }, }, new UpsertRecord { Id = "rec2", AdditionalProperties = { ["chunk_text"] = "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", ["category"] = "technology", ["quarter"] = "Q4", }, }, new UpsertRecord { Id = "rec3", AdditionalProperties = { ["chunk_text"] = "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", ["category"] = "technology", ["quarter"] = "Q4", }, }, new UpsertRecord { Id = "rec4", AdditionalProperties = { ["chunk_text"] = "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", ["category"] = "technology", ["quarter"] = "Q3", }, }, ] ); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "_id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } { "_id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } { "_id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" } { "_id": "vec4", "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" }' ``` To upsert sparse vectors into a [sparse index](/guides/index-data/create-an-index#create-a-sparse-index), use the [`upsert`](/reference/api/latest/data-plane/upsert) operation as follows: * Specify the [`namespace`](/guides/index-data/indexing-overview#namespaces) to upsert into. If the namespace doesn't exist, it is created. To use the default namespace, set the namespace to `"__default__"`. * Format your input data as records, each with the following: * An `id` field with a unique record identifier for the index namespace. * A `sparse_values` field with the sparse vector values and indices. * Optionally, a `metadata` field with [key-value pairs](/guides/index-data/indexing-overview#metadata) to store additional information or context. When you query the index, you can use metadata to [filter search results](/guides/search/filter-by-metadata). For example, the following code upserts sparse vector representations of sentences related to the term "apple", with the source text and additional fields stored as metadata: ```python Python theme={null} from pinecone import Pinecone, SparseValues, Vector pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } }, { "id": "vec4", "sparse_values": { "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375], "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673] }, "metadata": { "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } } ] ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').upsert([ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } }, { id: 'vec4', sparseValues: { indices: [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673], values: [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375] }, metadata: { chunk_text: 'AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.', category: 'technology', quarter: 'Q4' } } ]); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.clients.Index; import com.google.protobuf.Struct; import com.google.protobuf.Value; import java.util.*; public class UpsertSparseVectors { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API)KEY").build(); Index index = pinecone.getIndexConnection("docs-example"); // Record 1 ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct metaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); // Record 2 ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct metaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); // Record 3 ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct metaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); // Record 4 ArrayList indices4 = new ArrayList<>(Arrays.asList( 131900689L, 152217691L, 441495248L, 1640781426L, 1851149807L, 2263326288L, 2502307765L, 2641553256L, 2684780967L, 2966813704L, 3162218338L, 3283104238L, 3488055477L, 3530642888L, 3888762515L, 4152503047L, 4177290673L )); ArrayList values4 = new ArrayList<>(Arrays.asList( 0.73046875f, 0.46972656f, 2.84375f, 5.2265625f, 3.3242188f, 1.9863281f, 0.9511719f, 0.5019531f, 4.4257812f, 3.4277344f, 0.41308594f, 4.3242188f, 2.4179688f, 3.1757812f, 1.0224609f, 2.0585938f, 2.5859375f )); Struct metaData4 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); index.upsert("vec1", Collections.emptyList(), indices1, values1, metaData1, "example-namespace"); index.upsert("vec2", Collections.emptyList(), indices2, values2, metaData2, "example-namespace"); index.upsert("vec3", Collections.emptyList(), indices3, values3, metaData3, "example-namespace"); index.upsert("vec4", Collections.emptyList(), indices4, values4, metaData4, "example-namespace"); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } metadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } metadata1, err := structpb.NewStruct(metadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } metadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } metadata2, err := structpb.NewStruct(metadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } metadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } metadata3, err := structpb.NewStruct(metadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues4 := pinecone.SparseValues{ Indices: []uint32{131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673}, Values: []float32{0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375}, } metadataMap4 := map[string]interface{}{ "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4", } metadata4, err := structpb.NewStruct(metadataMap4) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } vectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: metadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: metadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: metadata3, }, { Id: "vec4", SparseValues: &sparseValues4, Metadata: metadata4, }, } count, err := idxConnection.UpsertVectors(ctx, vectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("Successfully upserted %d vector(s)!\n", count) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("docs-example"); var vector1 = new Vector { Id = "vec1", SparseValues = new SparseValues { Indices = new uint[] { 822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var vector2 = new Vector { Id = "vec2", SparseValues = new SparseValues { Indices = new uint[] { 131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."), ["category"] = new("technology"), ["quarter"] = new("Q4"), }, }; var vector3 = new Vector { Id = "vec3", SparseValues = new SparseValues { Indices = new uint[] { 8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var vector4 = new Vector { Id = "vec4", SparseValues = new SparseValues { Indices = new uint[] { 131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space."), ["category"] = new("technology"), ["quarter"] = new("Q4"), }, }; // Upsert vector Console.WriteLine("Upserting vector..."); var upsertResponse = await index.UpsertAsync(new UpsertRequest { Vectors = new List { vector1, vector2, vector3, vector4 }, Namespace = "example-namespace" }); Console.WriteLine($"Upserted {upsertResponse.UpsertedCount} vector"); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" PINECONE_API_KEY="YOUR_API_KEY" curl "http://$INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } }, { "id": "vec4", "sparseValues": { "values": [0.73046875, 0.46972656, 2.84375, 5.2265625, 3.3242188, 1.9863281, 0.9511719, 0.5019531, 4.4257812, 3.4277344, 0.41308594, 4.3242188, 2.4179688, 3.1757812, 1.0224609, 2.0585938, 2.5859375], "indices": [131900689, 152217691, 441495248, 1640781426, 1851149807, 2263326288, 2502307765, 2641553256, 2684780967, 2966813704, 3162218338, 3283104238, 3488055477, 3530642888, 3888762515, 4152503047, 4177290673] }, "metadata": { "chunk_text": "AAPL may consider healthcare integrations in Q4 to compete with tech rivals entering the consumer wellness space.", "category": "technology", "quarter": "Q4" } }, ] }' ``` ## Upsert in batches To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. Send upserts in batches to help increase throughput. * When upserting records with vectors, a batch should be as large as possible (up to 1000 records) without exceeding the [max request size of 2 MB](#upsert-limits). To understand the number of records you can fit into one batch based on the vector dimensions and metadata size, see the following table: | Dimension | Metadata (bytes) | Max batch size | | :-------- | :--------------- | :------------- | | 386 | 0 | 1000 | | 768 | 500 | 559 | | 1536 | 2000 | 245 | * When upserting records with text, a batch can contain up to 96 records. This limit comes from the [hosted embedding models](/guides/index-data/create-an-index#embedding-models) used during integrated embedding rather than the batch size limit for upserting raw vectors. ```Python Python theme={null} import random import itertools from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") def chunks(iterable, batch_size=200): """A helper function to break an iterable into chunks of size batch_size.""" it = iter(iterable) chunk = tuple(itertools.islice(it, batch_size)) while chunk: yield chunk chunk = tuple(itertools.islice(it, batch_size)) vector_dim = 128 vector_count = 10000 # Example generator that generates many (id, vector) pairs example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count)) # Upsert data with 200 vectors per upsert request for ids_vectors_chunk in chunks(example_data_generator, batch_size=200): index.upsert(vectors=ids_vectors_chunk) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from "@pinecone-database/pinecone"; const RECORD_COUNT = 10000; const RECORD_DIMENSION = 128; const client = new Pinecone({ apiKey: "YOUR_API_KEY" }); const index = client.index("docs-example"); // A helper function that breaks an array into chunks of size batchSize const chunks = (array, batchSize = 200) => { const chunks = []; for (let i = 0; i < array.length; i += batchSize) { chunks.push(array.slice(i, i + batchSize)); } return chunks; }; // Example data generation function, creates many (id, vector) pairs const generateExampleData = () => Array.from({ length: RECORD_COUNT }, (_, i) => { return { id: `id-${i}`, values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()), }; }); const exampleRecordData = generateExampleData(); const recordChunks = chunks(exampleRecordData); // Upsert data with 200 records per upsert request for (const chunk of recordChunks) { await index.upsert(chunk) } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class UpsertBatchExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); ArrayList vectors = generateVectors(); ArrayList> chunks = chunks(vectors, BATCH_SIZE); for (ArrayList chunk : chunks) { index.upsert(chunk, "example-namespace"); } } // A helper function that breaks an ArrayList into chunks of batchSize private static ArrayList> chunks(ArrayList vectors, int batchSize) { ArrayList> chunks = new ArrayList<>(); ArrayList chunk = new ArrayList<>(); for (int i = 0; i < vectors.size(); i++) { if (i % BATCH_SIZE == 0 && i != 0) { chunks.add(chunk); chunk = new ArrayList<>(); } chunk.add(vectors.get(i)); } return chunks; } // Example data generation function, creates many (id, vector) pairs private static ArrayList generateVectors() { Random random = new Random(); ArrayList vectors = new ArrayList<>(); for (int i = 0; i <= RECORD_COUNT; i++) { String id = "id-" + i; ArrayList values = new ArrayList<>(); for (int j = 0; j < RECORD_DIMENSION; j++) { values.add(random.nextFloat()); } VectorWithUnsignedIndices vector = new VectorWithUnsignedIndices(); vector.setId(id); vector.setValues(values); vectors.add(vector); } return vectors; } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Generate a large number of vectors to upsert vectorCount := 10000 vectorDim := idx.Dimension vectors := make([]*pinecone.Vector, vectorCount) for i := 0; i < int(vectorCount); i++ { randomFloats := make([]float32, vectorDim) for i := int32(0); i < vectorDim; i++ { randomFloats[i] = rand.Float32() } vectors[i] = &pinecone.Vector{ Id: fmt.Sprintf("doc1#-vector%d", i), Values: randomFloats, } } // Break the vectors into batches of 200 var batches [][]*pinecone.Vector batchSize := 200 for len(vectors) > 0 { batchEnd := batchSize if len(vectors) < batchSize { batchEnd = len(vectors) } batches = append(batches, vectors[:batchEnd]) vectors = vectors[batchEnd:] } // Upsert batches for i, batch := range batches { upsertResp, err := idxConn.UpsertVectors(context.Background(), batch) if err != nil { panic(err) } fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches)) } } ``` ## Upsert in parallel Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic. For more details, see [Asyncio support](/reference/python-sdk#asyncio-support). Send multiple upserts in parallel to help increase throughput. Vector operations block until the response has been received. However, they can be made asynchronously as follows: ```Python Python theme={null} # This example uses `async_req=True` and multiple threads. # For a single-threaded approach compatible with modern async web frameworks, # see https://docs.pinecone.io/reference/python-sdk#asyncio-support import random import itertools from pinecone import Pinecone # Initialize the client with pool_threads=30. This limits simultaneous requests to 30. pc = Pinecone(api_key="YOUR_API_KEY", pool_threads=30) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") def chunks(iterable, batch_size=200): """A helper function to break an iterable into chunks of size batch_size.""" it = iter(iterable) chunk = tuple(itertools.islice(it, batch_size)) while chunk: yield chunk chunk = tuple(itertools.islice(it, batch_size)) vector_dim = 128 vector_count = 10000 example_data_generator = map(lambda i: (f'id-{i}', [random.random() for _ in range(vector_dim)]), range(vector_count)) # Upsert data with 200 vectors per upsert request asynchronously # - Pass async_req=True to index.upsert() with pc.Index(host="INDEX_HOST", pool_threads=30) as index: # Send requests in parallel async_results = [ index.upsert(vectors=ids_vectors_chunk, async_req=True) for ids_vectors_chunk in chunks(example_data_generator, batch_size=200) ] # Wait for and retrieve responses (this raises in case of error) [async_result.get() for async_result in async_results] ``` ```JavaScript JavaScript theme={null} import { Pinecone } from "@pinecone-database/pinecone"; const RECORD_COUNT = 10000; const RECORD_DIMENSION = 128; const client = new Pinecone({ apiKey: "YOUR_API_KEY" }); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") // A helper function that breaks an array into chunks of size batchSize const chunks = (array, batchSize = 200) => { const chunks = []; for (let i = 0; i < array.length; i += batchSize) { chunks.push(array.slice(i, i + batchSize)); } return chunks; }; // Example data generation function, creates many (id, vector) pairs const generateExampleData = () => Array.from({ length: RECORD_COUNT }, (_, i) => { return { id: `id-${i}`, values: Array.from({ length: RECORD_DIMENSION }, (_, i) => Math.random()), }; }); const exampleRecordData = generateExampleData(); const recordChunks = chunks(exampleRecordData); // Upsert data with 200 records per request asynchronously using Promise.all() await Promise.all(recordChunks.map((chunk) => index.upsert(chunk))); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.UpsertResponse; import io.pinecone.unsigned_indices_model.VectorWithUnsignedIndices; import java.util.ArrayList; import java.util.Arrays; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; import java.util.List; public class UpsertExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); // Run 5 threads concurrently and upsert data into pinecone int numberOfThreads = 5; // Create a fixed thread pool ExecutorService executor = Executors.newFixedThreadPool(numberOfThreads); // Submit tasks to the executor for (int i = 0; i < numberOfThreads; i++) { // upsertData int batchNumber = i+1; executor.submit(() -> upsertData(index, batchNumber)); } // Shutdown the executor executor.shutdown(); } private static void upsertData(Index index, int batchNumber) { // Vector ids to be upserted String prefix = "v" + batchNumber; List upsertIds = Arrays.asList(prefix + "_1", prefix + "_2", prefix + "_3"); // List of values to be upserted List> values = new ArrayList<>(); values.add(Arrays.asList(1.0f, 2.0f, 3.0f)); values.add(Arrays.asList(4.0f, 5.0f, 6.0f)); values.add(Arrays.asList(7.0f, 8.0f, 9.0f)); // List of sparse indices to be upserted List> sparseIndices = new ArrayList<>(); sparseIndices.add(Arrays.asList(1L, 2L, 3L)); sparseIndices.add(Arrays.asList(4L, 5L, 6L)); sparseIndices.add(Arrays.asList(7L, 8L, 9L)); // List of sparse values to be upserted List> sparseValues = new ArrayList<>(); sparseValues.add(Arrays.asList(1000f, 2000f, 3000f)); sparseValues.add(Arrays.asList(4000f, 5000f, 6000f)); sparseValues.add(Arrays.asList(7000f, 8000f, 9000f)); List vectors = new ArrayList<>(3); // Metadata to be upserted Struct metadataStruct1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("action").build()) .putFields("year", Value.newBuilder().setNumberValue(2019).build()) .build(); Struct metadataStruct2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("thriller").build()) .putFields("year", Value.newBuilder().setNumberValue(2020).build()) .build(); Struct metadataStruct3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .putFields("year", Value.newBuilder().setNumberValue(2021).build()) .build(); List metadataStructList = Arrays.asList(metadataStruct1, metadataStruct2, metadataStruct3); // Upsert data for (int i = 0; i < metadataStructList.size(); i++) { vectors.add(buildUpsertVectorWithUnsignedIndices(upsertIds.get(i), values.get(i), sparseIndices.get(i), sparseValues.get(i), metadataStructList.get(i))); } UpsertResponse upsertResponse = index.upsert(vectors, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "math/rand" "sync" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConn, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Generate a large number of vectors to upsert vectorCount := 10000 vectorDim := idx.Dimension vectors := make([]*pinecone.Vector, vectorCount) for i := 0; i < int(vectorCount); i++ { randomFloats := make([]float32, vectorDim) for i := int32(0); i < vectorDim; i++ { randomFloats[i] = rand.Float32() } vectors[i] = &pinecone.Vector{ Id: fmt.Sprintf("doc1#-vector%d", i), Values: randomFloats, } } // Break the vectors into batches of 200 var batches [][]*pinecone.Vector batchSize := 200 for len(vectors) > 0 { batchEnd := batchSize if len(vectors) < batchSize { batchEnd = len(vectors) } batches = append(batches, vectors[:batchEnd]) vectors = vectors[batchEnd:] } // Use channels to manage concurrency and possible errors maxConcurrency := 10 errChan := make(chan error, len(batches)) semaphore := make(chan struct{}, maxConcurrency) var wg sync.WaitGroup for i, batch := range batches { wg.Add(1) semaphore <- struct{}{} go func(batch []*pinecone.Vector, i int) { defer wg.Done() defer func() { <-semaphore }() upsertResp, err := idxConn.UpsertVectors(context.Background(), batch) if err != nil { errChan <- fmt.Errorf("batch %d failed: %v", i, err) return } fmt.Printf("upserted %d vectors (%v of %v batches)\n", upsertResp, i+1, len(batches)) }(batch, i) } wg.Wait() close(errChan) for err := range errChan { if err != nil { fmt.Printf("Error while upserting batch: %v\n", err) } } } ``` ### Python SDK with gRPC Using the Python SDK with gRPC extras can provide higher upsert speeds. Through multiplexing, gRPC is able to handle large amounts of requests in parallel without slowing down the rest of the system (HoL blocking), unlike REST. Moreover, you can pass various retry strategies to the gRPC SDK, including [exponential backoff](/guides/production/error-handling#implement-retry-logic). To install the gRPC version of the SDK: ```Shell Shell theme={null} pip install "pinecone[grpc]" ``` To use the gRPC SDK, import the `pinecone.grpc` subpackage and target an index as usual: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone # This is gRPC client aliased as "Pinecone" pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") ``` To launch multiple read and write requests in parallel, pass `async_req` to the `upsert` operation: ```Python Python theme={null} def chunker(seq, batch_size): return (seq[pos:pos + batch_size] for pos in range(0, len(seq), batch_size)) async_results = [ index.upsert(vectors=chunk, async_req=True) for chunk in chunker(data, batch_size=200) ] # Wait for and retrieve responses (in case of error) [async_result.result() for async_result in async_results] ``` It is possible to get write-throttled faster when upserting using the gRPC SDK. If you see this often, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) while upserting. The syntax for upsert, query, fetch, and delete with the gRPC SDK remain the same as the standard SDK. ## Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max metadata size per record | 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 | # Back up a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/back-up-a-pod-based-index Backup pod-based indexes using Pinecone collections Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page describes how to create a static copy of a pod-based index, also known as a [collection](/guides/indexes/pods/understanding-collections). ## Create a collection To create a backup of your pod-based index, use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation. The following example creates a [collection](/guides/indexes/pods/understanding-collections) named `example-collection` from an index named `docs-example`: ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="API_KEY") pc.create_collection("example-collection", "docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createCollection({ name: "example-collection", source: "docs-example", }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class CreateCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createCollection("example-collection", "docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{ Name: "example-collection", Source: "docs-example", }) if err != nil { log.Fatalf("Failed to create collection: %v", err) } else { fmt.Printf("Successfully created collection: %v", collection.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var collectionModel = await pinecone.CreateCollectionAsync(new CreateCollectionRequest { Name = "example-collection", Source = "docs-example", }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s POST "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-collection", "source": "docs-example" }' ``` You can create a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Check the status of a collection To retrieve the status of the process creating a collection and the size of the collection, use the [`describe_collection`](/reference/api/latest/control-plane/describe_collection) operation. Specify the name of the collection to check. You can only call `describe_collection` on a collection in the current project. The `describe_collection` operation returns an object containing key-value pairs representing the name of the collection, the size in bytes, and the creation status of the collection. The following example gets the creation status and size of a collection named `example-collection`. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.describe_collection(name="example-collection") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeCollection('example-collection'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.client.model.CollectionModel; public class DescribeCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); CollectionModel collectionModel = pc.describeCollection("example-collection"); System.out.println(collectionModel); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collectionName := "example-collection" collection, err := pc.DescribeCollection(ctx, collectionName) if err != nil { log.Fatalf("Error describing collection %v: %v", collectionName, err) } else { fmt.Printf("Collection: %+v", collection) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var collectionModel = await pinecone.DescribeCollectionAsync("example-collection"); Console.WriteLine(collectionModel); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can check the status of a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## List your collections To get a list of the collections in the current project, use the [`list_collections`](/reference/api/latest/control-plane/list_collections) operation. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.list_collections() ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.listCollections(); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.client.model.CollectionModel; public class ListCollectionsExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); List collectionList = pc.listCollections().getCollections(); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collections, err := pc.ListCollections(ctx) if err != nil { log.Fatalf("Failed to list collections: %v", err) } else { if len(collections) == 0 { fmt.Printf("No collections found in project") } else { for _, collection := range collections { fmt.Printf("collection: %v\n", prettifyStruct(collection)) } } } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var collectionList = await pinecone.ListCollectionsAsync(); Console.WriteLine(collectionList); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). You can view a list of your collections using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Delete a collection To delete a collection, use the [`delete_collection`](/reference/api/latest/control-plane/delete_collection) operation. Specify the name of the collection to delete. Deleting the collection takes several minutes. During this time, the [`describe_collection`](#check-the-status-of-a-collection) operation returns the status "deleting". ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='API_KEY') pc.delete_collection("example-collection") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.deleteCollection("example-collection"); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteCollection("example-collection"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collectionName := "example-collection" err = pc.DeleteCollection(ctx, collectionName) if err != nil { log.Fatalf("Failed to delete collection: %v\n", err) } else { if len(collections) == 0 { fmt.Printf("No collections found in project") } else { fmt.Printf("Successfully deleted collection \"%v\"\n", collectionName) } } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); await pinecone.DeleteCollectionAsync("example-collection"); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can delete a collection using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). # Choose a pod type and size Source: https://docs.pinecone.io/guides/indexes/pods/choose-a-pod-type-and-size Select the right pod configuration for your workload Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). When planning your Pinecone deployment, it is important to understand the approximate storage requirements of your vectors to choose the appropriate pod type and number. This page will give guidance on sizing to help you plan accordingly. As with all guidelines, these considerations are general and may not apply to your specific use case. We caution you to always test your deployment and ensure that the index configuration you are using is appropriate to your requirements. [Collections](/guides/indexes/pods/understanding-collections) allow you to create new versions of your index with different pod types and sizes. This also allows you to test different configurations. This guide is merely an overview of sizing considerations; test your index configuration before moving to production. Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for further help with sizing and testing. ## Overview There are five main considerations when deciding how to configure your Pinecone index: * Number of vectors * Dimensionality of your vectors * Size of metadata on each vector * Queries per second (QPS) throughput * Cardinality of indexed metadata Each of these considerations comes with requirements for index size, pod type, and replication strategy. ### Number of vectors The most important consideration in sizing is the [number of vectors](/guides/index-data/upsert-data) you plan on working with. As a rule of thumb, a single p1 pod can store approximately 1M vectors, while a s1 pod can store 5M vectors. However, this can be affected by other factors, such as dimensionality and metadata, which are explained below. ### Dimensionality of vectors The rules of thumb above for how many vectors can be stored in a given pod assumes a typical configuration of 768 [dimensions per vector](/guides/index-data/create-an-index). As your individual use case will dictate the dimensionality of your vectors, the amount of space required to store them may necessarily be larger or smaller. Each dimension on a single vector consumes 4 bytes of memory and storage per dimension, so if you expect to have 1M vectors with 768 dimensions each, that’s about 3GB of storage without factoring in metadata or other overhead. Using that reference, we can estimate the typical pod size and number needed for a given index. Table 1 below gives some examples of this. **Table 1: Estimated number of pods per 1M vectors by dimensionality** | Pod type | Dimensions | Estimated max vectors per pod | | -------- | ---------: | ----------------------------: | | **p1** | 512 | 1,250,000 | | | 768 | 1,000,000 | | | 1024 | 675,000 | | | 1536 | 500,000 | | **p2** | 512 | 1,250,000 | | | 768 | 1,100,000 | | | 1024 | 1,000,000 | | | 1536 | 550,000 | | **s1** | 512 | 8,000,000 | | | 768 | 5,000,000 | | | 1024 | 4,000,000 | | | 1536 | 2,500,000 | Pinecone does not support fractional pod deployments, so always round up to the next nearest whole number when choosing your pods. ## Queries per second (QPS) QPS speeds are governed by a combination of the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) of the index, the number of [replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas), and the `top_k` value of queries. The pod type is the primary factor driving QPS, as the different pod types are optimized for different approaches. The [p1 pods](/guides/index-data/indexing-overview/#p1-pods) are performance-optimized pods which provide very low query latencies, but hold fewer vectors per pod than [s1 pods](/guides/index-data/indexing-overview/#s1-pods). They are ideal for applications with low latency requirements (\<100ms). The s1 pods are optimized for storage and provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements. The [p2 pod type](/guides/index-data/indexing-overview/#p2-pods) provides greater query throughput with lower latency. They support 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1, especially for low dimension vectors (\<512D). As a rule, a single p1 pod with 1M vectors of 768 dimensions each and no replicas can handle about 20 QPS. It’s possible to get greater or lesser speeds, depending on the size of your metadata, number of vectors, the dimensionality of your vectors, and the `top_K` value for your search. See Table 2 below for more examples. **Table 2: QPS by pod type and `top_k` value**\* | Pod type | top\_k 10 | top\_k 250 | top\_k 1000 | | -------- | --------- | ---------- | ----------- | | p1 | 30 | 25 | 20 | | p2 | 150 | 50 | 20 | | s1 | 10 | 10 | 10 | \*The QPS values in Table 2 represent baseline QPS with 1M vectors and 768 dimensions. [Adding replicas](/guides/indexes/pods/scale-pod-based-indexes#add-replicas) is the simplest way to increase your QPS. Each replica increases the throughput potential by roughly the same QPS, so aiming for 150 QPS using p1 pods means using the primary pod and 5 replicas. Using threading or multiprocessing in your application is also important, as issuing single queries sequentially still subjects you to delays from any underlying latency. The [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk) can also be used to increase throughput of upserts. ### Metadata cardinality and size The last consideration when planning your indexes is the cardinality and size of your [metadata](/guides/index-data/upsert-data#inserting-vectors-with-metadata). While the increases are small when talking about a few million vectors, they can have a real impact as you grow to hundreds of millions or billions of vectors. Indexes with very high cardinality, like those storing a unique user ID on each vector, can have significant memory requirements, resulting in fewer vectors fitting per pod. Also, if the size of the metadata per vector is larger, the index requires more storage. Limiting which metadata fields are indexed using [selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) can help lower memory usage. ### Pod sizes You can also start with one of the larger [pod sizes](/guides/index-data/indexing-overview/#pod-size-and-performance), like p1.x2. Each step up in pod size doubles the space available for your vectors. We recommend starting with x1 pods and scaling as you grow. This way, you don’t start with too large a pod size and have nowhere else to go up, meaning you have to migrate to a new index before you’re ready. ### Example applications The following examples will showcase how to use the sizing guidelines above to choose the appropriate type, size, and number of pods for your index. #### Example 1: Semantic search of news articles In our first example, we’ll use the demo app for semantic search from our documentation. In this case, we’re only working with 204,135 vectors. The vectors use 300 dimensions each, well under the general measure of 768 dimensions. Using the rule of thumb above of up to 1M vectors per p1 pod, we can run this app comfortably with a single p1.x1 pod. #### Example 2: Facial recognition For this example, suppose you’re building an application to identify customers using facial recognition for a secure banking app. Facial recognition can work with as few as 128 dimensions, but in this case, because the app will be used for access to finances, we want to make sure we’re certain that the person using it is the right one. We plan for 100M customers and use 2048 dimensions per vector. We know from our rules of thumb above that 1M vectors with 768 dimensions fit nicely in a p1.x1 pod. We can just divide those numbers into the new targets to get the ratios we’ll need for our pod estimate: ``` 100M / 1M = 100 base p1 pods 2048 / 768 = 2.667 vector ratio 2.667 * 100 = 267 rounding up ``` So we need 267 p1.x1 pods. We can reduce that by switching to s1 pods instead, sacrificing latency by increasing storage availability. They hold five times the storage of p1.x1, so the math is simple: ``` 267 / 5 = 54 rounding up ``` So we estimate that we need 54 s1.x1 pods to store very high dimensional data for the face of each of the bank’s customers. # Create a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/create-a-pod-based-index Create and configure a pod-based Pinecone index Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page shows you how to create a pod-based index. For guidance on serverless indexes, see [Create a serverless index](/guides/index-data/create-an-index). ## Create a pod index To create a pod index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation as follows: * Provide a `name` for the index. * Specify the `dimension` and `metric` of the vectors you'll store in the index. This should match the dimension and metric supported by your embedding model. * Set `spec.environment` to the [environment](/guides/index-data/create-an-index#cloud-regions) where the index should be deployed. For Python, you also need to import the `ServerlessSpec` class. * Set `spec.pod_type` to the [pod type](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) and [size](/guides/index-data/indexing-overview#pod-size-and-performance) that you want. Other parameters are optional. See the [API reference](/reference/api/latest/control-plane/create_index) for details. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1 ), deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1 } }, deletionProtection: 'disabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1536, Metric = MetricType.Cosine, Spec = new PodIndexSpec { Pod = new PodSpec { Environment = "us-east1-gcp", PodType = "p1.x1", Pods = 1, } }, DeletionProtection = DeletionProtection.Disabled }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1 } }, "deletion_protection": "disabled" }' ``` ## Create a pod index from a collection You can create a pod-based index from a collection. For more details, see [Restore an index](/guides/indexes/pods/restore-a-pod-based-index). # Manage pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/manage-pod-based-indexes List, describe, and configure pod-based indexes Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). This page shows you how to manage pod-based indexes. For guidance on serverless indexes, see [Manage serverless indexes](/guides/manage-data/manage-indexes). ## Describe a pod-based index Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") # Response: # {'dimension': 1536, # 'host': 'docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io', # 'metric': 'cosine', # 'name': 'docs-example', # 'spec': {'pod': {'environment': 'us-east-1-aws', # 'pod_type': 's1.x1', # 'pods': 1, # 'replicas': 1, # 'shards': 1}}, # 'status': {'ready': True, 'state': 'Ready'}} ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", // "deletionProtection": "disabled", // "spec": { // "pod": { // "environment": "us-east-1-aws", // "pod_type": "s1.x1", // "pods": 1, // "replicas": 1, // "shards": 1 // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } // Response: // class IndexModel { // name: docs-example // dimension: 1536 // metric: cosine // host: docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io // deletionProtection: disabled // spec: class IndexModelSpec { // serverless: null // pod: class PodSpec { // cloud: aws // region: us-east-1 // environment: us-east-1-aws, // podType: s1.x1, // pods: 1, // replicas: 1, // shards: 1 // } // } // status: class IndexModelStatus { // ready: true // state: Ready // } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } // Response: // index: { // "name": "docs-example", // "dimension": 1536, // "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", // "metric": "cosine", // "deletion_protection": "disabled", // "spec": { // "pod": { // "environment": "us-east-1-aws", // "pod_type": "s1.x1", // "pods": 1, // "replicas": 1, // "shards": 1 // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexModel = await pinecone.DescribeIndexAsync("docs-example"); Console.WriteLine(indexModel); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", // "deletion_protection": "disabled", // "spec": { // "serverless": null, // "pod": { // "environment": "us-east-1-aws", // "pod_type": "s1.x1", // "pods": 1, // "replicas": 1, // "shards": 1 // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "name": "docs-example", # "metric": "cosine", # "dimension": 1536, # "status": { # "ready": true, # "state": "Ready" # }, # "host": "docs-example-4mkljsz.svc.aped-4627-b74a.pinecone.io", # "spec": { # "pod": { # "environment": "us-east-1-aws", # "pod_type": "s1.x1", # "pods": 1, # "replicas": 1, # "shards": 1 # } # } # } ``` **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Delete a pod-based index Use the [`delete_index`](/reference/api/latest/control-plane/delete_index) operation to delete a pod-based index and all of its associated resources. You are billed for a pod-based index even when it is not in use. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_index(name="docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.deleteIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Println("Index \"%v\" deleted successfully", indexName) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); await pinecone.DeleteIndexAsync("docs-example"); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**. ## Selective metadata indexing For pod-based indexes, Pinecone indexes all metadata fields by default. When metadata fields contains many unique values, pod-based indexes will consume significantly more memory, which can lead to performance issues, pod fullness, and a reduction in the number of possible vectors that fit per pod. To avoid indexing high-cardinality metadata that is not needed for [filtering your queries](/guides/index-data/indexing-overview#metadata) and keep memory utilization low, specify which metadata fields to index using the `metadata_config` parameter. Since high-cardinality metadata does not cause high memory utilization in serverless indexes, selective metadata indexing is not supported. The value for the `metadata_config` parameter is a JSON object containing the names of the metadata fields to index. ```JSON JSON theme={null} { "indexed": [ "metadata-field-1", "metadata-field-2", "metadata-field-n" ] } ``` **Example** The following example creates a pod-based index that only indexes the `genre` metadata field. Queries against this index that filter for the `genre` metadata field may return results; queries that filter for other metadata fields behave as though those fields do not exist. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1, metadata_config = { "indexed": ["genre"] } ), deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1, metadata_config: { indexed: ["genre"] } } }, deletionProtection: 'disabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); CreateIndexRequestSpecPodMetadataConfig podSpecMetadataConfig = new CreateIndexRequestSpecPodMetadataConfig(); List indexedItems = Arrays.asList("genre", "year"); podSpecMetadataConfig.setIndexed(indexedItems); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", podSpecMetadataConfig, DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } podIndexMetadata := &pinecone.PodSpecMetadataConfig{ Indexed: &[]string{"genre"}, } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1536, Metric = MetricType.Cosine, Spec = new PodIndexSpec { Pod = new PodSpec { Environment = "us-east1-gcp", PodType = "p1.x1", Pods = 1, MetadataConfig = new PodSpecMetadataConfig { Indexed = new List { "genre" }, }, } }, DeletionProtection = DeletionProtection.Disabled }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s https://api.pinecone.io/indexes \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1, "metadata_config": { "indexed": ["genre"] } } }, "deletion_protection": "disabled" }' ``` ## Prevent index deletion This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/python-sdk) v5.0.0, [Node.js SDK](/reference/node-sdk) v3.0.0, [Java SDK](/reference/java-sdk) v2.0.0, or [Go SDK](/reference/go-sdk) v1.0.0 or later. You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or when [configuring an existing index](/guides/indexes/pods/manage-pod-based-indexes). In both cases, you set the `deletion_protection` parameter to `enabled`. To enable deletion protection when creating a new index: ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west1-gcp", pod_type="p1.x1", pods=1 ), deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { pod: { environment: 'us-west1-gcp', podType: 'p1.x1', pods: 1 } }, deletionProtection: 'enabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1536, Metric = MetricType.Cosine, Spec = new PodIndexSpec { Pod = new PodSpec { Environment = "us-east1-gcp", PodType = "p1.x1", Pods = 1, } }, DeletionProtection = DeletionProtection.Enabled }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "pod": { "environment": "us-west1-gcp", "pod_type": "p1.x1", "pods": 1 } }, "deletion_protection": "enabled" }' ``` To enable deletion protection when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'enabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexMetadata = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { DeletionProtection = DeletionProtection.Enabled, }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "enabled" }' ``` When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` ## Disable deletion protection Before you can [delete an index](#delete-a-pod-based-index) with deletion protection enabled, you must first disable deletion protection as follows: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'disabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configurePodsIndex("docs-example", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var configureIndexRequest = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { DeletionProtection = DeletionProtection.Disabled, }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "disabled" }' ``` ## Delete an entire namespace In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace with many records can increase the latency of read operations. In such cases, consider [deleting records in batches](#delete-records-in-batches). ## Delete records in batches In pod-based indexes, reads and writes share compute resources, so deleting an entire namespace or a large number of records can increase the latency of read operations. To avoid this, delete records in batches of up to 1000, with a brief sleep between requests. Consider using smaller batches if the index has active read traffic. ```python Batch delete a namespace theme={null} from pinecone import Pinecone import numpy as np import time pc = Pinecone(api_key='API_KEY') INDEX_NAME = 'INDEX_NAME' NAMESPACE = 'NAMESPACE_NAME' # Consider using smaller batches if you have a high RPS for read operations BATCH = 1000 index = pc.Index(name=INDEX_NAME) dimensions = index.describe_index_stats()['dimension'] # Create the query vector query_vector = np.random.uniform(-1, 1, size=dimensions).tolist() results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH) # Delete in batches until the query returns no results while len(results['matches']) > 0: ids = [i['id'] for i in results['matches']] index.delete(ids=ids, namespace=NAMESPACE) time.sleep(0.01) results = index.query(vector=query_vector, namespace=NAMESPACE, top_k=BATCH) ``` ```python Batch delete by metadata theme={null} from pinecone import Pinecone import numpy as np import time pc = Pinecone(api_key='API_KEY') INDEX_NAME = 'INDEX_NAME' NAMESPACE = 'NAMESPACE_NAME' # Consider using smaller batches if you have a high RPS for read operations BATCH = 1000 index = pc.Index(name=INDEX_NAME) dimensions = index.describe_index_stats()['dimension'] METADATA_FILTER = {} # Create the query vector with a filter query_vector = np.random.uniform(-1, 1, size=dimensions).tolist() results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH) # Delete in batches until the query returns no results while len(results['matches']) > 0: ids = [i['id'] for i in results['matches']] index.delete(ids=ids, namespace=NAMESPACE) time.sleep(0.01) results = index.query(vector=query_vector, namespace=NAMESPACE, filter=METADATA_FILTER, top_k=BATCH) ``` ## Delete records by metadata In pod-based indexes, if you are targeting a large number of records for deletion and the index has active read traffic, consider [deleting records in batches](#delete-records-in-batches). To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression. For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`: ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete( filter={ "genre": {"$eq": "documentary"} }, namespace="example-namespace" ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') await ns.deleteMany({ genre: { $eq: "documentary" }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("genre", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("documentary") .build())) .build()) .build(); index.deleteByFilter(filter, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } metadataFilter := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } filter, err := structpb.NewStruct(metadataFilter) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } err = idxConnection.DeleteVectorsByFilter(ctx, filter) if err != nil { log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var deleteResponse = await index.DeleteAsync(new DeleteRequest { Namespace = "example-namespace", Filter = new Metadata { ["genre"] = new Metadata { ["$eq"] = "documentary" } } }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/delete" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "filter": {"genre": {"$eq": "documentary"}}, "namespace": "example-namespace" }' ``` ## Tag an index When configuring an index, you can tag the index to help with index organization and management. For more details, see [Tag an index](/guides/manage-data/manage-indexes#configure-index-tags). ## Manage costs ### Set a project pod limit To control costs, [project owners](/guides/projects/understanding-projects#project-roles) can [set the maximum total number of pods](/reference/api/database-limits#pods-per-project) allowed across all pod-based indexes in a project. The default pod limit is 5. 1. Go to [Settings > Projects](https://app.pinecone.io/organizations/-/settings/projects). 2. For the project you want to update, click the **ellipsis (...) menu > Configure**. 3. In the **Pod Limit** section, update the number of pods. 4. Click **Save Changes**. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "max_pods": 5 }' ``` The example returns a response like the following: ```json theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:42:31.912Z" } ``` ### Back up inactive pod-based indexes For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. When a pod-based index is not in use, [back it up using collections](/guides/indexes/pods/back-up-a-pod-based-index) and delete the inactive index. When you're ready to use the vectors again, you can [create a new index from the collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection). This new index can also use a different index type or size. Because it's relatively cheap to store collections, you can reduce costs by only running an index when it's in use. ### Choose the right index type and size Pod sizes are designed for different applications, and some are more expensive than others. [Choose the appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size), so you pay for the resources you need. For example, the `s1` pod type provides large storage capacity and lower overall costs with slightly higher query latencies than `p1` pods. By switching to a different pod type, you may be able to reduce costs while still getting the performance your application needs. For pod-based indexes, project owners can [set limits for the total number of pods](/reference/api/database-limits#pods-per-project) across all indexes in the project. The default pod limit is 5. ## Monitor performance Pinecone generates time-series performance metrics for each Pinecone index. You can monitor these metrics directly in the Pinecone console or with tools like Prometheus or Datadog. ### Use the Pinecone Console To view performance metrics in the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index you want to monitor. 3. Go to **Database > Indexes**. 4. Select the index. 5. Go to the **Metrics** tab. ### Use Datadog To monitor Pinecone with Datadog, use Datadog's [Pinecone integration](/integrations/datadog). This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ### Use Prometheus This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). When using [Bring Your Own Cloud](/guides/production/bring-your-own-cloud), you must configure Prometheus monitoring within your VPC. To monitor all pod-based indexes in a specific region of a project, insert the following snippet into the [`scrape_configs`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) section of your `prometheus.yml` file and update it with values for your Prometheus integration: ```YAML theme={null} scrape_configs: - job_name: "pinecone-pod-metrics" scheme: https metrics_path: '/metrics' authorization: credentials: API_KEY static_configs: - targets: ["metrics.ENVIRONMENT.pinecone.io" ] ``` * Replace `API_KEY` with an API key for the project you want to monitor. If necessary, you can [create an new API key](/reference/api/authentication) in the Pinecone console. * Replace `ENVIRONMENT` with the [environment](/guides/indexes/pods/understanding-pod-based-indexes#pod-environments) of the pod-based indexes you want to monitor. For more configuration details, see the [Prometheus docs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/). #### Available metrics The following metrics are available when you integrate Pinecone with Prometheus: | Name | Type | Description | | :----------------------------------- | :-------- | :-------------------------------------------------------------------------------- | | `pinecone_vector_count` | gauge | The number of records per pod in the index. | | `pinecone_request_count_total` | counter | The number of data plane calls made by clients. | | `pinecone_request_error_count_total` | counter | The number of data plane calls made by clients that resulted in errors. | | `pinecone_request_latency_seconds` | histogram | The distribution of server-side processing latency for pinecone data plane calls. | | `pinecone_index_fullness` | gauge | The fullness of the index on a scale of 0 to 1. | #### Metric labels Each metric contains the following labels: | Label | Description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | `pid` | Process identifier. | | `index_name` | Name of the index to which the metric applies. | | `project_name` | Name of the project containing the index. | | `request_type` | Type of request: `upsert`, `delete`, `fetch`, `query`, or `describe_index_stats`. This label is included only in `pinecone_request_*` metrics. | #### Example queries Return the average latency in seconds for all requests against the Pinecone index `docs-example`: ```shell theme={null} avg by (request_type) (pinecone_request_latency_seconds{index_name="docs-example"}) ``` Return the vector count for the Pinecone index `docs-example`: ```shell theme={null} sum ((avg by (app) (pinecone_vector_count{index_name="docs-example"}))) ``` Return the total number of requests against the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example"}[60s])) ``` Return the total number of upsert requests against the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type)(increase(pinecone_request_count_total{index_name="docs-example", request_type="upsert"}[60s])) ``` Return the total errors returned by the Pinecone index `docs-example` over one minute: ```shell theme={null} sum by (request_type) (increase(pinecone_request_error_count{ index_name="docs-example"}[60s])) ``` Return the index fullness metric for the Pinecone index `docs-example`: ``` round(max (pinecone_index_fullness{index_name="docs-example"} * 100)) ``` ## Troubleshooting ### Index fullness errors Serverless indexes automatically scale as needed. However, pod-based indexes can run out of capacity. When that happens, upserting new records will fail with the following error: ```console console theme={null} Index is full, cannot accept data. ``` ### High-cardinality metadata and over-provisioning This [Loom video walkthrough](https://www.loom.com/share/ce6f5dd0c3e14ba0b988fe32d96b703a?sid=48646dfe-c10c-4143-82c6-031fefe05a68) shows you how to manage two scenarios: * The first scenario involves customers loading an index replete with high cardinality metadata. This can trigger a series of unforeseen challenges, and hence, it's vital to comprehend how to manage this situation effectively. This methodology can be applied whenever you need to change your metadata configuration. * The second scenario that we will address involves customers who have over-provisioned the number of pods they need. More specifically, we will discuss the process of re-scaling an index in instances where the customer has previously scaled vertically and now desires to scale the index back down. # Migrate a pod-based index to serverless Source: https://docs.pinecone.io/guides/indexes/pods/migrate-a-pod-based-index-to-serverless Migrate existing pod indexes to cost-effective serverless This page shows you how to migrate a pod-based index to [serverless](/guides/get-started/database-architecture). The migration process is free; the standard costs of upserting records to a new serverless index are not applied. In most cases, migrating to serverless reduces costs significantly. However, costs can increase for read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace. Before migrating, consider [contacting Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications. ## Limitations Migration is supported for pod-based indexes with less than 25 million records and 20,000 namespaces across all supported clouds (AWS, GCP, and Azure). Also, serverless indexes do not support the following features. If you were using these features for your pod-based index, you will need to adapt your code. If you are blocked by these limitations, [contact Pinecone Support](/troubleshooting/contact-support). * [Selective metadata indexing](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) * Because high-cardinality metadata in serverless indexes does not cause high memory utilization, this operation is not relevant. * [Filtering index statistics by metadata](/reference/api/latest/data-plane/describeindexstats) ## How it works Migrating a pod-based index to serverless is a 2-step process: After migration, you will have both a new serverless index and the original pod-based index. Once you've switched your workload to the serverless index, you can delete the pod-based index to avoid paying for unused resources. ## 1. Understand cost implications In most cases, migrating to serverless reduces costs significantly. However, costs can increase for read-heavy workloads with more than 1 query per second and for indexes with many records in a single namespace. Before migrating, consider [contacting Pinecone Support](/troubleshooting/contact-support) for help estimating and managing cost implications. ## 2. Prepare for migration Migrating a pod-based index to serverless can take anywhere from a few minutes to several hours, depending on the size of the index. During that time, you can continue reading from the pod-based index. However, all [upserts](/guides/index-data/upsert-data), [updates](/guides/manage-data/update-data), and [deletes](/guides/manage-data/delete-data) to the pod-based index will not automatically be reflected in the new serverless index, so be sure to prepare in one of the following ways: * **Pause write traffic:** If downtime is acceptable, pause traffic to the pod-based index before starting migration. After migration, you will start sending traffic to the serverless index. * **Log your writes:** If you need to continue reading from the pod-based index during migration, send read traffic to the pod-based index, but log your writes to a temporary location outside of Pinecone (e.g., S3). After migration, you will replay the logged writes to the new serverless index and start sending all traffic to the serverless index. ## 3. Start migration 1. In the [Pinecone console](https://app.pinecone.io/), go to your pod-based index and click the **ellipsis (...) menu > Migrate to serverless**. The dropdown will not display **Migrate to serverless** if the index has any of the listed [limitations](#limitations). 2. To save the legacy index and create a new serverless index now, follow the prompts. Depending on the size of the index, migration can take anywhere from a few minutes to several hours. While migration is in progress, you'll see the yellow **Initializing** status: create index from collection - initializing status When the new serverless index is ready, the status will change to green: create index from collection - ready status 1. Use the [`create_collection`](/reference/api/latest/control-plane/create_collection) operation to create a backup of your pod-based index: ```javascript JavaScript theme={null} // Requires Node.js SDK v6.1.2 or later import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createCollection({ name: "pod-collection", source: "pod-index" }); ``` ```go Go theme={null} // Requires Go SDK v4.1.2 or later package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } collection, err := pc.CreateCollection(ctx, &pinecone.CreateCollectionRequest{ Name: "pod-collection", Source: "pod-index", }) if err != nil { log.Fatalf("Failed to create collection: %v", err) } else { fmt.Printf("Successfully created collection: %v", collection.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s POST "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "pod-collection", "source": "pod-index" }' ``` 2. Use the [`create_index`](/reference/api/latest/control-plane/create_index) operation to create a new serverless index from the collection: * Use API verison `2025-04` or later. Creating a serverless index from a collection is not supported in earlier versions. * Set `dimension` to the same dimension as the pod-based index. Changing the dimension is not supported. * Set `cloud` to the cloud where the pod-based index is hosted. Migrating to a different cloud is not supported. * Set `source_collection` to the name of the collection you created in step 1. ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'serverless-index', vectorType: 'dense', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1', sourceCollection: 'pod-collection' } } }); ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: "serverless-index", VectorType: "dense", Dimension: 1536, Metric: pinecone.Cosine, Cloud: pinecone.Aws, Region: "us-east-1", SourceCollection: "pod-collection", }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "serverless-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "source_collection": "pod-collection" } } }' ``` ## 4. Update SDKs If you are using an older version of the Python, Node.js, Java, or Go SDK, you must update the SDK to work with serverless indexes. 1. Check your SDK version: ```shell Python theme={null} pip show pinecone ``` ```shell JavaScript theme={null} npm list | grep @pinecone-database/pinecone ``` ```shell Java theme={null} # Check your dependency file or classpath ``` ```shell Go theme={null} go list -u -m all | grep go-pinecone ``` 2. If your SDK version is less than 3.0.0 for [Python](https://github.com/pinecone-io/pinecone-python-client/blob/main/README.md), 2.0.0 for [Node.js](https://sdk.pinecone.io/typescript/), 1.0.0 for [Java](https://github.com/pinecone-io/pinecone-java-client), or 1.0.0 for [Go](https://github.com/pinecone-io/go-pinecone), upgrade the SDK as follows: ```Python Python theme={null} pip install "pinecone[grpc]" --upgrade ``` ```JavaScript JavaScript theme={null} npm install @pinecone-database/pinecone@latest ``` ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ```go Go theme={null} go get -u github.com/pinecone-io/go-pinecone/v4/pinecone@latest ``` If you are using the [.NET SDK](/reference/dotnet-sdk), add a package reference to your project file: ```shell C# theme={null} dotnet add package Pinecone.Client ``` ## 5. Adapt existing code You must make some minor code changes to work with serverless indexes. Serverless indexes do not support some features, as outlined in [Limitations](#limitations). If you were relying on these features for your pod-based index, you’ll need to adapt your code. 1. Change how you import the Pinecone library and authenticate and initialize the client: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec, PodSpec # ServerlessSpec and PodSpec are required only when # creating serverless and pod-based indexes. pc = Pinecone(api_key="YOUR_API_KEY") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); ``` 2. [Listing indexes](/guides/manage-data/manage-indexes) now fetches a complete description of each index. If you were relying on the output of this operation, you'll need to adapt your code. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_list = pc.list_indexes() print(index_list) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexList = await pc.listIndexes(); console.log(indexList); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ListIndexesExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexList indexList = pc.listIndexes(); System.out.println(indexList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idxs, err := pc.ListIndexes(ctx) if err != nil { log.Fatalf("Failed to list indexes: %v", err) } else { for _, index := range idxs { fmt.Printf("index: %v\n", prettifyStruct(index)) } } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexList = await pinecone.ListIndexesAsync(); Console.WriteLine(indexList); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The `list_indexes` operation now returns a response like the following: ```python Python theme={null} [{ "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse", "dimension": null, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense", "dimension": 1536, "deletion_protection": "disabled", "tags": { "environment": "development" } }] ``` ```javascript JavaScript theme={null} { indexes: [ { name: 'docs-example-sparse', dimension: undefined, metric: 'dotproduct', host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'sparse' }, { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ] } ``` ```java Java theme={null} class IndexList { indexes: [class IndexModel { name: docs-example-sparse dimension: null metric: dotproduct host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: sparse additionalProperties: null }, class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null }] additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-sparse", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "dotproduct", "vector_type": "sparse", "deletion_protection": "disabled", "dimension": null, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```csharp C# theme={null} { "indexes": [ { "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "deletion_protection": "disabled", "tags": { "environment": "development" }, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse" }, { "name": "docs-example-dense", "dimension": 1536, "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "deletion_protection": "disabled", "tags": { "environment": "development" }, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense" } ] } ``` ```json curl theme={null} { "indexes": [ { "name": "docs-example-sparse", "vector_type": "sparse", "metric": "dotproduct", "dimension": null, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ] } ``` 3. [Describing an index](/guides/manage-data/manage-indexes) now returns a description of an index in a different format. It also returns the index host needed to run data plane operations against the index. If you were relying on the output of this operation, you'll need to adapt your code. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexModel = await pinecone.DescribeIndexAsync("docs-example"); Console.WriteLine(indexModel); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 6. Use your new index When you're ready to cutover to your new serverless index: 1. Your new serverless index has a different name and unique endpoint than your pod-based index. Update your code to target the new serverless index: ```Python Python theme={null} index = pc.Index("YOUR_SERVERLESS_INDEX_NAME") ``` ```JavaScript JavaScript theme={null} const index = pc.index("YOUR_SERVERLESS_INDEX_NAME"); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class TargetIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("YOUR_SERVERLESS_INDEX_NAME"); ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "YOUR_SERVERLESS_INDEX_NAME") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: idx.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("YOUR_SERVERLESS_INDEX_NAME"); ``` ```bash curl theme={null} # When using the API directly, you need the unique endpoint for your new serverless index. # See https://docs.pinecone.io/guides/manage-data/target-an-index for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` 2. Reinitialize your clients. 3. If you logged writes to the pod-based index during migration, replay the logged writes to your serverless index. 4. [Delete the pod-based index](/guides/manage-data/manage-indexes#delete-an-index) to avoid paying for unused resources. It is not possible to save a serverless index as a collection, so if you want to retain the option to recreate your pod-based index, be sure to keep the collection you created earlier. ## See also * [Limits](/reference/api/database-limits) * [Serverless architecture](/guides/get-started/database-architecture) * [Understanding serverless cost](/guides/manage-cost/understanding-cost) # Restore a pod-based index Source: https://docs.pinecone.io/guides/indexes/pods/restore-a-pod-based-index Restore pod-based indexes from collections Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). You can restore a pod-based index by creating a new index from a [collection](/guides/indexes/pods/understanding-collections). ## Create a pod-based index from a collection To create a pod-based index from a [collection](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections), use the [`create_index`](/reference/api/latest/control-plane/create_index) endpoint and provide a [`source_collection`](/reference/api/latest/control-plane/create_index#!path=source%5Fcollection\&t=request) parameter containing the name of the collection from which you wish to create an index. The new index can differ from the original source index: the new index can have a different name, number of pods, or pod type. The new index is queryable and writable. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone, PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=128, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1, source_collection="example-collection" ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 128, metric: 'cosine', spec: { pod: { environment: 'us-west-1-gcp', podType: 'p1.x1', pods: 1, sourceCollection: 'example-collection' } } }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateIndexFromCollectionExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createPodsIndex("docs-example", 1536, "us-west1-gcp", "p1.x1", "cosine", "example-collection", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" metric := pinecone.Dotproduct deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreatePodIndex(ctx, &pinecone.CreatePodIndexRequest{ Name: indexName, Metric: &metric, Dimension: 1536, Environment: "us-east1-gcp", PodType: "p1.x1", SourceCollection: "example-collection", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create pod-based index: %v", idx.Name) } else { fmt.Printf("Successfully created pod-based index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1538, Metric = MetricType.Cosine, Spec = new PodIndexSpec { Pod = new PodSpec { Environment = "us-east1-gcp", PodType = "p1.x1", Pods = 1, Replicas = 1, Shards = 1, SourceCollection = "example-collection", } }, DeletionProtection = DeletionProtection.Enabled, }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 128, "metric": "cosine", "spec": { "pod": { "environment": "us-west-1-gcp", "pod_type": "p1.x1", "pods": 1, "source_collection": "example-collection" } } }' ``` # Scale pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/scale-pod-based-indexes Scale indexes vertically or horizontally as needed Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). While your index can still serve queries, new upserts may fail as the capacity becomes exhausted. If you need to scale your environment to accommodate more vectors, you can modify your existing index and scale it vertically or create a new index and scale horizontally. This page explains how you can scale your [pod-based indexes](/guides/index-data/indexing-overview#pod-based-indexes) horizontally and vertically. ## Vertical vs. horizontal scaling If you need to scale your environment to accommodate more vectors, you can modify your existing index to scale it vertically or create a new index and scale horizontally. This article will describe both methods and how to scale your index effectively. ## Vertical scaling [Vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1) is fast and involves no downtime. This is a good choice when you can't pause upserts and must continue serving traffic. It also allows you to double your capacity instantly. However, there are some factors to consider. ### Increase pod size The default [pod size](/guides/index-data/indexing-overview#pod-size-and-performance) is `x1`. You can increase the size to `x2`, `x4`, or `x8`. Moving up to the next size effectively doubles the capacity of the index. If you need to scale by smaller increments, then consider horizontal scaling. Increasing the pod size of your index does not result in downtime. Reads and writes continue uninterrupted during the scaling process, which completes in about 10 minutes. You cannot reduce the pod size of your indexes. The number of base pods you specify when you initially create the index is static and cannot be changed. For example, if you start with 10 pods of `p1.x1` and vertically scale to `p1.x2`, this equates to 20 pods worth of usage. Pod types (performance versus storage pods) also cannot be changed with vertical scaling. If you want to change your pod type while scaling, then horizontal scaling is the better option. #### When to increase pod size If your index is at around 90% fullness, we recommend increasing its size. This helps ensure optimal performance and prevents upserts from failing due to capacity constraints. #### How to increase pod size You can increase the pod size in the Pinecone console or using the API. 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index you want to configure. 3. Go to **Database > Indexes**. 4. Select the index. 5. Click the **...** button. 6. Select **Configure**. 7. In the dropdown, choose the pod size to use. 8. Click **Confirm**. Use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation and append the new size to the `pod_type` parameter, separated by a period (.). **Example** The following example assumes that `docs-example` has size `x1` and increases the size to `x2`. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index("docs-example", pod_type="s1.x2") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pinecone = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { spec: { pod: { podType: 's1.x2', }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build(); pc.configurePodsIndex("docs-example", "s1.x2"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{PodType: "s1.x2"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexMetadata = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { Spec = new ConfigureIndexRequestSpec { Pod = new ConfigureIndexRequestSpecPod { PodType = "s1.x2", } } }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "pod_type": "s1.x2" }' ``` The size change can take up to 15 minutes to complete. ### Decrease pod size After creating an index, you cannot vertically downscale the index/pod size. Instead, you must [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) and then [create a new index from your collection](/guides/indexes/pods/restore-a-pod-based-index) and specify your desired pod size. ### Check the status of a pod size change To check the status of a pod size change, use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint. The `status` field in the results contains the key-value pair `"state":"ScalingUp"` or `"state":"ScalingDown"` during the resizing process and the key-value pair `"state":"Ready"` after the process is complete. The index fullness metric provided by [`describe_index_stats`](/reference/api/latest/data-plane/describeindexstats) may be inaccurate until the resizing process is complete. **Example** The following example uses `describe_index` to get the index status of the index `docs-example`. The `status` field contains the key-value pair `"state":"ScalingUp"`, indicating that the resizing process is still ongoing. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex({ name: "docs-example", }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index %v: %v", idx.Name, err) } else { fmt.Printf("Successfully found index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexModel = await pinecone.DescribeIndexAsync("docs-example"); Console.WriteLine(indexModel); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X GET "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## Horizontal scaling There are two approaches to horizontal scaling in Pinecone: adding pods and adding replicas. Adding pods increases all resources but requires a pause in upserts; adding replicas only increases throughput and requires no pause in upserts. ### Add pods Adding additional pods to a running index is not supported directly. However, you can increase the number of pods by using our [collections](/guides/indexes/pods/understanding-collections) feature to create a new index with more pods. A collection is an immutable snapshot of your index in time: a collection stores the data but not the original index configuration. When you [create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection), you define the new index configuration. This allows you to scale the base pod count horizontally without scaling vertically. The main advantage of this approach is that you can scale incrementally instead of doubling capacity as with vertical scaling. Also, you can redefine pod types if you are experimenting or if you need to use a different pod type, such as performance-optimized pods or storage-optimized pods. Another advantage of this method is that you can change your [metadata configuration](/guides/indexes/pods/manage-pod-based-indexes#selective-metadata-indexing) to redefine metadata fields as indexed or stored-only. This is important when tuning your index for the best throughput. Here are the general steps to make a copy of your index and create a new index while changing the pod type, pod count, metadata configuration, replicas, and all typical parameters when creating a new collection: 1. Pause upserts. 2. Create a collection from the current index. 3. Create an index from the collection with new parameters. 4. Continue upserts to the newly created index. Note: the URL has likely changed. 5. Delete the old index if desired. For detailed steps on creating the collection, see [backup indexes](/guides/manage-data/back-up-an-index#create-a-backup-using-a-collection). For steps on creating an index from a collection, see [Create an index from a collection](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection). ### Add replicas Each replica duplicates the resources and data in an index. This means that adding additional replicas increases the throughput of the index but not its capacity. However, adding replicas does not require downtime. Throughput in terms of queries per second (QPS) scales linearly with the number of replicas per index. #### When to add replicas There are two primary scenarios where adding replicas is beneficial: **Increase QPS**: The primary reason to add replicas is to increase your index's queries per second (QPS). Each new replica adds another pod for reading from your index and, generally speaking, will increase your QPS by an equal amount as a single pod. For example, if you consistently get 25 QPS for a single pod, each replica will result in 25 more QPS. If you don't see an increase in QPS after adding replicas, add multiprocessing to your application to ensure you are running parallel operations. You can use the [Pinecone gRPC SDK](/guides/index-data/upsert-data#grpc-python-sdk), or your multiprocessing library of choice. **Provide data redundancy**: When you add a replica to your index, the Pinecone controller will choose a zone in the same region that does not currently have a replica, up to a maximum of three zones (your fourth and subsequent replicas will be hosted in zones with existing replicas). If your application requires multizone redundancy, this is our recommended approach to achieve that. #### How to add replicas To add replicas, use the `configure_index` endpoint to increase the number of replicas for your index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index("docs-example", replicas=4) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { spec: { pod: { replicas: 4, }, }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("PINECONE_API_KEY").build(); pc.configurePodsIndex("docs-example", 4, DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{Replicas: 4}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var configureIndexRequest = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { Spec = new ConfigureIndexRequestSpec { Pod = new ConfigureIndexRequestSpecPod { Replicas = 4, } } }); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "replicas": 4 }' ``` ## Next steps * See our learning center for more information on [vertical scaling](https://www.pinecone.io/learn/testing-p2-collections-scaling/#vertical-scaling-on-p1-and-s1). * Learn more about [collections](/guides/indexes/pods/understanding-collections). # Understanding collections Source: https://docs.pinecone.io/guides/indexes/pods/understanding-collections Create static backups of pod-based indexes with collections Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). A collection is a static copy of a pod-based index that only consumes storage. It is a non-queryable representation of a set of records. You can [create a collection](/guides/indexes/pods/back-up-a-pod-based-index) of a pod-based index, and you can [create a new pod-based index from a collection](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations. Once a collection is created, it cannot be moved to a different project. ## Use cases Creating a collection is useful when performing tasks like the following: * Protecting an index from manual or system failures. * Temporarily shutting down an index. * Copying the data from one index into a different index. * Making a backup of your index. * Experimenting with different index configurations. ## Performance Collections operations perform differently, depending on the pod type of the index: * Creating a `p1` or `s1` index from a collection takes approximately 10 minutes. * Creating a `p2` index from a collection can take several hours when the number of vectors is on the order of 1,000,000. ## Limitations Collection limitations are as follows: * You can only perform operations on collections in the current Pinecone project. ## Pricing See [Pricing](https://www.pinecone.io/pricing/) for up-to-date pricing information. # Understanding pod-based indexes Source: https://docs.pinecone.io/guides/indexes/pods/understanding-pod-based-indexes Learn about pod-based index architecture and types Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). With pod-based indexes, you choose one or more pre-configured units of hardware (pods). Depending on the pod type, pod size, and number of pods used, you get different amounts of storage and higher or lower latency and throughput. Be sure to [choose an appropriate pod type and size](/guides/indexes/pods/choose-a-pod-type-and-size) for your dataset and workload. ## Pod types Different pod types are priced differently. See [Understanding cost](/guides/manage-cost/understanding-cost) for more details. Once a pod-based index is created, you cannot change its pod type. However, you can create a collection from an index and then [create a new index with a different pod type](/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection) from the collection. ### s1 pods These storage-optimized pods provide large storage capacity and lower overall costs with slightly higher query latencies than p1 pods. They are ideal for very large indexes with moderate or relaxed latency requirements. Each s1 pod has enough capacity for around 5M vectors of 768 dimensions. ### p1 pods These performance-optimized pods provide very low query latencies, but hold fewer vectors per pod than s1 pods. They are ideal for applications with low latency requirements (\<100ms). Each p1 pod has enough capacity for around 1M vectors of 768 dimensions. ### p2 pods The p2 pod type provides greater query throughput with lower latency. For vectors with fewer than 128 dimension and queries where `topK` is less than 50, p2 pods support up to 200 QPS per replica and return queries in less than 10ms. This means that query throughput and latency are better than s1 and p1. Each p2 pod has enough capacity for around 1M vectors of 768 dimensions. However, capacity may vary with dimensionality. The data ingestion rate for p2 pods is significantly slower than for p1 pods; this rate decreases as the number of dimensions increases. For example, a p2 pod containing vectors with 128 dimensions can upsert up to 300 updates per second; a p2 pod containing vectors with 768 dimensions or more supports upsert of 50 updates per second. Because query latency and throughput for p2 pods vary from p1 pods, test p2 pod performance with your dataset. The p2 pod type does not support sparse vector values. ## Pod size and performance Each pod type supports four pod sizes: `x1`, `x2`, `x4`, and `x8`. Your index storage and compute capacity doubles for each size step. The default pod size is `x1`. You can increase the size of a pod after index creation. To learn about changing the pod size of an index, see [Configure an index](/guides/indexes/pods/scale-pod-based-indexes#increase-pod-size). ## Pod environments When creating a pod-based index, you must choose the cloud environment where you want the index to be hosted. The project environment can affect your [pricing](https://pinecone.io/pricing). The following table lists the available cloud regions and the corresponding values of the `environment` parameter for the [`create_index`](/guides/index-data/create-an-index#create-a-pod-based-index) endpoint: | Cloud | Region | Environment | | ----- | ---------------------------- | ----------------------------- | | GCP | us-west-1 (N. California) | `us-west1-gcp` | | GCP | us-central-1 (Iowa) | `us-central1-gcp` | | GCP | us-west-4 (Las Vegas) | `us-west4-gcp` | | GCP | us-east-4 (Virginia) | `us-east4-gcp` | | GCP | northamerica-northeast-1 | `northamerica-northeast1-gcp` | | GCP | asia-northeast-1 (Japan) | `asia-northeast1-gcp` | | GCP | asia-southeast-1 (Singapore) | `asia-southeast1-gcp` | | GCP | us-east-1 (South Carolina) | `us-east1-gcp` | | GCP | eu-west-1 (Belgium) | `eu-west1-gcp` | | GCP | eu-west-4 (Netherlands) | `eu-west4-gcp` | | AWS | us-east-1 (Virginia) | `us-east-1-aws` | | Azure | eastus (Virginia) | `eastus-azure` | [Contact us](http://www.pinecone.io/contact/) if you need a dedicated deployment in other regions. The environment cannot be changed after the index is created. ## Pod costs For each pod-based index, billing is determined by the per-minute price per pod and the number of pods the index uses, regardless of index activity. The per-minute price varies by pod type, pod size, account plan, and cloud region. For the latest pod-based index pricing rates, see [Pricing](https://www.pinecone.io/pricing/pods). Total cost depends on a combination of factors: * **Pod type.** Each pod type has different per-minute pricing. * **Number of pods.** This includes replicas, which duplicate pods. * **Pod size.** Larger pod sizes have proportionally higher costs per minute. * **Total pod-minutes.** This includes the total time each pod is running, starting at pod creation and rounded up to 15-minute increments. * **Cloud provider.** The cost per pod-type and pod-minute varies depending on the cloud provider you choose for your project. * **Collection storage.** Collections incur costs per GB of data per minute in storage, rounded up to 15-minute increments. * **Plan.** The free plan incurs no costs; the Standard or Enterprise plans incur different costs per pod-type, pod-minute, cloud provider, and collection storage. The following equation calculates the total costs accrued over time: ``` (Number of pods) * (pod size) * (number of replicas) * (minutes pod exists) * (pod price per minute) + (collection storage in GB) * (collection storage time in minutes) * (collection storage price per GB per minute) ``` To see a calculation of your current usage and costs, go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. While our pricing page lists rates on an hourly basis for ease of comparison, this example lists prices per minute, as this is how Pinecone calculates billing. An example application has the following requirements: * 1,000,000 vectors with 1536 dimensions * 150 queries per second with `top_k` = 10 * Deployment in an EU region * Ability to store 1GB of inactive vectors [Based on these requirements](/guides/indexes/pods/choose-a-pod-type-and-size), the organization chooses to configure the project to use the Standard billing plan to host one `p1.x2` pod with three replicas and a collection containing 1 GB of data. This project runs continuously for the month of January on the Standard plan. The components of the total cost for this example are given in Table 1 below: **Table 1: Example billing components** | Billing component | Value | | ----------------------------- | ------------ | | Number of pods | 1 | | Number of replicas | 3 | | Pod size | x2 | | Total pod count | 6 | | Minutes in January | 44,640 | | Pod-minutes (pods \* minutes) | 267,840 | | Pod price per minute | \$0.0012 | | Collection storage | 1 GB | | Collection storage minutes | 44,640 | | Price per storage minute | \$0.00000056 | The invoice for this example is given in Table 2 below: **Table 2: Example invoice** | Product | Quantity | Price per unit | Charge | | ------------- | -------- | -------------- | -------- | | Collections | 44,640 | \$0.00000056 | \$0.025 | | P2 Pods (AWS) | 0 | | \$0.00 | | P2 Pods (GCP) | 0 | | \$0.00 | | S1 Pods | 0 | | \$0.00 | | P1 Pods | 267,840 | \$0.0012 | \$514.29 | Amount due \$514.54 ## Known limitations * [Pod storage capacity](#pod-types) * Each **p1** pod has enough capacity for 1M vectors with 768 dimensions. * Each **s1** pod has enough capacity for 5M vectors with 768 dimensions. * [Metadata](/guides/index-data/indexing-overview#metadata) * Metadata with high cardinality, such as a unique value for every vector in a large index, uses more memory than expected and can cause the pods to become full. * [Collections](/guides/manage-data/back-up-an-index#pod-based-index-backups-using-collections) * You cannot query or write to a collection after its creation. For this reason, a collection only incurs storage costs. * You can only perform operations on collections in the current Pinecone project. * [Sparse-dense vectors](/guides/search/hybrid-search#use-a-single-hybrid-index) * Only `s1` and `p1` [pod-based indexes](/guides/indexes/pods/understanding-pod-based-indexes#pod-types) using the dotproduct distance metric support sparse-dense vectors. # Manage cost Source: https://docs.pinecone.io/guides/manage-cost/manage-cost Learn strategies for managing cost in Pinecone. For the latest pricing details, see our [pricing page](https://www.pinecone.io/pricing/). For help estimating total cost, see [Understanding cost](/guides/manage-cost/understanding-cost). To view or download a detailed report of your current usage and costs, see [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage). ## Set monthly spend alerts You can set up email alerts to monitor your organization's monthly spending. These alerts notify designated recipients when spending reaches specified thresholds. The alerts automatically reset at the start of each monthly billing cycle. To set a spend alert: 1. Go to [Settings > Spend alerts](https://app.pinecone.io/organizations/-/settings/spend-alerts) in the Pinecone console 2. Click **+ Add Alert**. 3. Enter the dollar amount for the spend alert. 4. Enter the email addresses to send the alert to. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) are listed by default. 5. Click **Create**. To edit a spend alert: 1. In the row of the spend alert you want to edit, click **ellipsis (...) menu > Edit**. 2. Change the dollar amount and/or email addresses for the spend alert. 3. Click **Update**. **Auto-spend spike alert**: To protect from unexpected cost increases, Pinecone sends an alert when spending exceeds double your previous month's invoice amount. While the alert threshold is fixed and the alert cannot be deleted, you can modify which email addresses receive the alert and enable or disable the alert notifications. ## List by ID prefix By using a [hierarchical ID schema](/guides/index-data/data-modeling#use-structured-ids), you can retrieve records without performing a query. To do so, you can use [`list`](/reference/api/latest/data-plane/list) to retrieve records by ID prefix, then use `fetch` to retrieve the records you need. This can reduce costs, because [`query` consumes more RUs when scanning a larger namespace](/guides/manage-cost/understanding-cost#query), while [`fetch` consumes a fixed ratio of RUs to records retrieved](/guides/manage-cost/understanding-cost#fetch). ## Use namespaces for multitenancy If your application requires you to isolate the data of each customer/user, consider [implementing multitenancy with serverless indexes and namespaces](/guides/index-data/implement-multitenancy). With serverless indexes, you pay only for the amount of data stored and operations performed. For queries in particular, the cost is partly based on the total number of records that must be scanned, so using namespaces can significantly reduce query costs. ## Commit to annual spend Pinecone offers up to an 18% discount for customers who enroll in an annual plan with an upfront payment. Eligibility requires a minimum annual commitment of \$8,000. Throughout the contract term, the discount applies to List Price for all Pinecone services, excluding Storage and Support. Any usage that exceeds the prepaid credits will be billed at full List Price and will not qualify for the contractual discount. Customers on the Standard and Enterprise pay-as-you-go plans may upgrade directly by naviating in the Pinecone console to **[Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans)**. The self-serve annual plan is not available through cloud marketplace billing. To purchase an annual plan through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io). ## Talk to support Users on Standard and Enterprise plans can [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help in optimizing costs. ## See also * [Understanding cost](/guides/manage-cost/understanding-cost) * [Monitor usage and costs](/guides/manage-cost/monitor-usage-and-costs) # Monitor usage and costs Source: https://docs.pinecone.io/guides/manage-cost/monitor-usage-and-costs Monitor usage and costs for your Pinecone organization and indexes. ## Monitor organization-level usage and costs To view usage and costs across your Pinecone organization, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-owners). Also, this feature is available only to organizations on the Standard or Enterprise plans. The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis. 1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. 2. Select the time range to report on. This defaults to the last 30 days. 3. Select the scope for your report: * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model. * **Project:** The aggregated cost for each project in your organization. * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections. 4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all. 5. To download the report as a CSV file, click **Download**. The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags. Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date. ## Monitor index-level usage You can monitor index-level usage directly in the Pinecone console, or you can pull them into [Prometheus](https://prometheus.io/). For more details, see [Monitoring](/guides/production/monitoring). ## Monitor operation-level usage ### Read units [Query](/guides/search/search-overview), [fetch](/guides/manage-data/fetch-data), and [list by ID](/guides/manage-data/list-record-ids) requests return a `usage` parameter with the [read unit](/guides/manage-cost/understanding-cost#read-units) consumption of each request that is made. While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. Example query request: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("example-index") response = index.query( vector=[0.22,0.43,0.16,1,...], namespace='example-namespace', top_k=3, include_values=False, include_metadata=False ) print(response) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) const index = pc.index("example-index") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.22,0.43,0.16,1,...], topK: 3, includeValues: false, includeMetadata: false, }); console.log(queryResponse); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryByVector { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "example-index"); List query = Arrays.asList(0.22f,0.43f,0.16f,1f,...); QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, false); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } queryVector := []float32{0.22, 0.43, 0.16, 1, ...} res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: false, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var queryResponse = await index.QueryAsync(new QueryRequest { Vector = new[] { 0.22f,0.43f,0.16f,1f,... }, Namespace = "example-namespace", TopK = 3, IncludeMetadata = false, }); ``` The response looks like this: ```python Python theme={null} {'matches': [{'id': 'record_193027', 'score': 0.00405937387, 'values': []}, {'id': 'record_137452', 'score': 0.00405937387, 'values': []}, {'id': 'record_132264', 'score': 0.00405937387, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 1}} ``` ```javascript JavaScript theme={null} { matches: [ { id: 'record_186225', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined }, { id: 'record_164994', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined }, { id: 'record_186333', score: 0.00405937387, values: [], sparseValues: undefined, metadata: undefined } ], namespace: 'example-namespace', usage: { readUnits: 1 } } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_170370 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_107423 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.004059374 id: record_171426 values: [] metadata: sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-index usage: read_units: 1 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "record_193027" }, "score": 0.004059374 }, { "vector": { "id": "record_137452" }, "score": 0.004059374 }, { "vector": { "id": "record_132264" }, "score": 0.004059374 } ], "usage": { "read_units": 1 }, "namespace": "example-index" } ``` ```csharp C# theme={null} { "results": [], "matches": [ { "id": "record_193027", "score": 0.004059374, "values": [] }, { "id": "record_137452", "score": 0.004059374, "values": [] }, { "id": "record_132264", "score": 0.004059374, "values": [] } ], "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` For a more in-depth demonstration of how to use read units to inspect read costs, see [this notebook](https://github.com/pinecone-io/examples/blob/master/docs/read-units-demonstrated.ipynb). ### Embedding tokens Requests to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models), either directly via the [`embed` operation](/reference/api/latest/inference/generate-embeddings) or automatically when upserting or querying an [index with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding), return a `usage` parameter with the total tokens generated. For example, the following request to use the `multilingual-e5-large` model to generate embeddings for sentences related to the word “apple” might return this request and summary of embedding tokens generated: ```python Python theme={null} # Import the Pinecone library from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec import time # Initialize a Pinecone client with your API key pc = Pinecone(api_key="YOUR_API_KEY") # Define a sample dataset where each item has a unique ID and piece of text data = [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "The tech company Apple is known for its innovative products like the iPhone."}, {"id": "vec3", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec4", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec5", "text": "An apple a day keeps the doctor away, as the saying goes."}, {"id": "vec6", "text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] # Convert the text into numerical vectors that Pinecone can index embeddings = pc.inference.embed( model="llama-text-embed-v2", inputs=[d['text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) print(embeddings) ``` ```javascript JavaScript theme={null} // Import the Pinecone library import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a Pinecone client with your API key const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Define a sample dataset where each item has a unique ID and piece of text const data = [ { id: 'vec1', text: 'Apple is a popular fruit known for its sweetness and crisp texture.' }, { id: 'vec2', text: 'The tech company Apple is known for its innovative products like the iPhone.' }, { id: 'vec3', text: 'Many people enjoy eating apples as a healthy snack.' }, { id: 'vec4', text: 'Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.' }, { id: 'vec5', text: 'An apple a day keeps the doctor away, as the saying goes.' }, { id: 'vec6', text: 'Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.' } ]; // Convert the text into numerical vectors that Pinecone can index const model = 'llama-text-embed-v2'; const embeddings = await pc.inference.embed( model, data.map(d => d.text), { inputType: 'passage', truncate: 'END' } ); console.log(embeddings); ``` ```java Java theme={null} // Import the required classes import io.pinecone.clients.Index; import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.ApiException; import org.openapitools.inference.client.model.Embedding; import org.openapitools.inference.client.model.EmbeddingsList; import java.math.BigDecimal; import java.util.*; import java.util.stream.Collectors; public class GenerateEmbeddings { public static void main(String[] args) throws ApiException { // Initialize a Pinecone client with your API key Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // Prepare input sentences to be embedded List data = Arrays.asList( new DataObject("vec1", "Apple is a popular fruit known for its sweetness and crisp texture."), new DataObject("vec2", "The tech company Apple is known for its innovative products like the iPhone."), new DataObject("vec3", "Many people enjoy eating apples as a healthy snack."), new DataObject("vec4", "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."), new DataObject("vec5", "An apple a day keeps the doctor away, as the saying goes."), new DataObject("vec6", "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.") ); List inputs = data.stream() .map(DataObject::getText) .collect(Collectors.toList()); // Specify the embedding model and parameters String embeddingModel = "llama-text-embed-v2"; Map parameters = new HashMap<>(); parameters.put("input_type", "passage"); parameters.put("truncate", "END"); // Generate embeddings for the input data EmbeddingsList embeddings = inference.embed(embeddingModel, parameters, inputs); // Get embedded data List embeddedData = embeddings.getData(); } private static List convertBigDecimalToFloat(List bigDecimalValues) { return bigDecimalValues.stream() .map(BigDecimal::floatValue) .collect(Collectors.toList()); } } class DataObject { private String id; private String text; public DataObject(String id, String text) { this.id = id; this.text = text; } public String getId() { return id; } public String getText() { return text; } } ``` ```go Go theme={null} package main // Import the required packages import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) type Data struct { ID string Text string } type Query struct { Text string } func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a Pinecone client with your API key pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Define a sample dataset where each item has a unique ID and piece of text data := []Data{ {ID: "vec1", Text: "Apple is a popular fruit known for its sweetness and crisp texture."}, {ID: "vec2", Text: "The tech company Apple is known for its innovative products like the iPhone."}, {ID: "vec3", Text: "Many people enjoy eating apples as a healthy snack."}, {ID: "vec4", Text: "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {ID: "vec5", Text: "An apple a day keeps the doctor away, as the saying goes."}, {ID: "vec6", Text: "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."}, } // Specify the embedding model and parameters embeddingModel := "llama-text-embed-v2" docParameters := pinecone.EmbedParameters{ InputType: "passage", Truncate: "END", } // Convert the text into numerical vectors that Pinecone can index var documents []string for _, d := range data { documents = append(documents, d.Text) } docEmbeddingsResponse, err := pc.Inference.Embed(ctx, &pinecone.EmbedRequest{ Model: embeddingModel, TextInputs: documents, Parameters: docParameters, }) if err != nil { log.Fatalf("Failed to embed documents: %v", err) } else { fmt.Printf(prettifyStruct(docEmbeddingsResponse)) } } ``` ```csharp C# theme={null} using Pinecone; using System; using System.Collections.Generic; // Initialize a Pinecone client with your API key var pinecone = new PineconeClient("YOUR_API_KEY"); // Prepare input sentences to be embedded var data = new[] { new { Id = "vec1", Text = "Apple is a popular fruit known for its sweetness and crisp texture." }, new { Id = "vec2", Text = "The tech company Apple is known for its innovative products like the iPhone." }, new { Id = "vec3", Text = "Many people enjoy eating apples as a healthy snack." }, new { Id = "vec4", Text = "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, new { Id = "vec5", Text = "An apple a day keeps the doctor away, as the saying goes." }, new { 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 var embeddingModel = "llama-text-embed-v2"; // Generate embeddings for the input data var embeddings = await pinecone.Inference.EmbedAsync(new EmbedRequest { Model = embeddingModel, Inputs = data.Select(item => new EmbedRequestInputsItem { Text = item.Text }), Parameters = new Dictionary { ["input_type"] = "passage", ["truncate"] = "END" } }); Console.WriteLine(embeddings); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/embed \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "passage", "truncate": "END" }, "inputs": [ {"text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"text": "The tech company Apple is known for its innovative products like the iPhone."}, {"text": "Many people enjoy eating apples as a healthy snack."}, {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"text": "An apple a day keeps the doctor away, as the saying goes."}, {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] }' ``` The returned object looks like this: ```python Python theme={null} EmbeddingsList( model='llama-text-embed-v2', data=[ {'values': [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...]}, ... ], usage={'total_tokens': 130} ) ``` ```javascript JavaScript theme={null} EmbeddingsList(1) [ { values: [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... model: 'llama-text-embed-v2', data: [ { values: [Array] } ], usage: { totalTokens: 130 } ] ``` ```java Java theme={null} class EmbeddingsList { model: llama-text-embed-v2 data: [class Embedding { values: [0.04925537109375, -0.01313018798828125, -0.0112762451171875, ...] additionalProperties: null }, ...] usage: class EmbeddingsListUsage { totalTokens: 130 additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "values": [ 0.03942871, -0.010177612, -0.046051025, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` ```csharp C# theme={null} { "model": "llama-text-embed-v2", "data": [ { "values": [ 0.04913330078125, -0.01306915283203125, -0.01116180419921875, ... ] }, ... ], "usage": { "total_tokens": 130 } } ``` ```json curl theme={null} { "data": [ { "values": [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` ## See also * [Understanding cost](/guides/manage-cost/understanding-cost) * [Manage cost](/guides/manage-cost/manage-cost) # Understanding cost Source: https://docs.pinecone.io/guides/manage-cost/understanding-cost Understand how costs are incurred in Pinecone. For the latest pricing details, see [Pricing](https://www.pinecone.io/pricing/). ## Minimum usage The Standard and Enterprise [pricing plans](https://www.pinecone.io/pricing/) include a monthly minimum usage committment: | Plan | Minimum usage | | ---------- | ------------- | | Starter | \$0/month | | Standard | \$50/month | | Enterprise | \$500/month | Beyond the monthly minimum, customers are charged for what they use each month. **Examples** * You are on the Standard plan. * Your usage for the month of August amounts to \$20. * Your usage is below the \$50 monthly minimum, so your total for the month is \$50. In this case, the August invoice would include line items for each service you used (totaling \$20), plus a single line item covering the rest of the minimum usage commitment (\$30). * You are on the Standard plan. * Your usage for the month of August amounts to \$100. * Your usage exceeds the \$50 monthly minimum, so your total for the month is \$100. In this case, the August invoice would only show line items for each service you used (totaling \$100). Since your usage exceeds the minimum usage commitment, you are only charged for your actual usage and no additional minimum usage line item appears on your invoice. ## Discounts Pinecone offers up to an 18% discount for customers who enroll in an annual plan with an upfront payment. Eligibility requires a minimum annual commitment of \$8,000. Throughout the contract term, the discount applies to List Price for all Pinecone services, excluding Storage and Support. Any usage that exceeds the prepaid credits will be billed at full List Price and will not qualify for the contractual discount. Customers on the Standard and Enterprise pay-as-you-go plans may upgrade directly by naviating in the Pinecone console to **[Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans)**. The self-serve annual plan is not available through cloud marketplace billing. To purchase an annual plan through a cloud marketplace, contact [ar@pinecone.io](mailto:ar@pinecone.io). ## Serverless indexes With serverless indexes, you pay for the amount of data stored and operations performed, based on three usage metrics: [read units](#read-units), [write units](#write-units), and [storage](#storage). For the latest serverless pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ### Read units Read units (RUs) measure the compute, I/O, and network resources consumed by the following read requests: * [Query](#query) * [Fetch](#fetch) * [List](#list) Read requests return the number of RUs used. You can use this information to [monitor read costs](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. #### Query The cost of a query scales linearly with the size of the targeted namespace. Specifically, a query uses 1 RU for every 1 GB of namespace size, with a minimum of 0.25 RUs per query. | Namespace size | Read units per query | | :------------- | :------------------- | | \< 0.25 GB | 0.25 RUs (minimum) | | 1 GB | 1 RU | | 10 GB | 10 RUs | | 50 GB | 50 RUs | | 100 GB | 100 RUs | To learn how to calculate your namespace size, see [Storage](#storage). Parameters that affect the size of the query response, such as `top_k`, `include_metadata`, and `include_values`, are not relevant for query cost; only the size of the namespace determines the number of RUs used. #### Fetch A fetch request uses 1 RU for every 10 records fetched, for example: | Fetched records | RUs | | --------------- | --- | | 10 | 1 | | 50 | 5 | | 107 | 11 | Specifying a non-existent ID or adding the same ID more than once does not increase the number of RUs used. However, a fetch request will always use at least 1 RU. [Fetching records by metadata](/guides/manage-data/fetch-data#fetch-records-by-metadata) uses the same cost model as fetching by ID: 1 RU for every 10 records fetched. #### List List has a fixed cost of 1 RU per call, with up to 100 records per call. ### Write units Write units (WUs) measure the storage and compute resources used by the following write requests: * [Upsert](#upsert) * [Update](#update) * [Delete](#delete) #### Upsert An upsert request uses 1 WU for each 1 KB of the request, with a minimum of 5 WUs per request. When an upsert modifies an existing record, the request uses 1 WU for each 1 KB of the existing record as well. For example, the following table shows the WUs used by upsert requests at different batch sizes and record sizes, assuming all records are new: | Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs | | :---------------- | :-------- | :----------------- | :--------------- | :--- | | 1 | 768 | 100 bytes | 3.2 KB | 5 | | 2 | 768 | 100 bytes | 3.2 KB | 7 | | 10 | 1024 | 15,000 bytes | 19.10 KB | 191 | | 100 | 768 | 500 bytes | 3.57 KB | 357 | | 1000 | 1536 | 1000 bytes | 7.14 KB | 7140 | #### Update An update request uses 1 WU for each 1 KB of the new and existing record, with a minimum of 5 WUs per request. For example, the following table shows the WUs used by an update at different record sizes: | New record size | Previous record size | WUs | | :-------------- | :------------------- | :-- | | 6.24 KB | 6.50 KB | 13 | | 19.10 KB | 15 KB | 25 | | 3.57 KB | 5 KB | 9 | | 7.14 KB | 10 KB | 18 | | 3.17 KB | 3.17 KB | 7 | [Updating records by metadata](/guides/manage-data/update-data#update-by-metadata) uses the same cost model as updating by ID: 1 WU for each 1 KB of the new and existing record. #### Delete A delete request uses 1 WU for each 1 KB of records deleted, with a minimum of 5 WUs per request. For example, the following table shows the WUs used by delete requests at different batch sizes and record sizes: | Records per batch | Dimension | Avg. metadata size | Avg. record size | WUs | | :---------------- | :-------- | :----------------- | :--------------- | :--- | | 1 | 768 | 100 bytes | 3.2 KB | 5 | | 2 | 768 | 100 bytes | 3.2 KB | 7 | | 10 | 1024 | 15,000 bytes | 19.10 KB | 191 | | 100 | 768 | 500 bytes | 3.57 KB | 357 | | 1000 | 1536 | 1000 bytes | 7.14 KB | 7140 | Specifying a non-existent ID or adding the same ID more than once does not increase WU use. [Deleting a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace) or [deleting all records in a namespace using `deleteAll`](/guides/manage-data/delete-data#delete-all-records-in-a-namespace) uses 5 WUs. [Deleting records by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) uses the same cost model as deleting by ID: 1 WU for each 1 KB of records deleted. ### Storage Storage costs are based on the size of an index on a per-gigabyte (GB) monthly rate. The size of an index is defined as the total size of its records across all namespaces. For the latest storage pricing rates, see [Pricing](https://www.pinecone.io/pricing/?plan=standard\&provider=aws\&plans=database\&scrollTo=product-pricing-modal-section). A record can include a dense vector, a sparse vector, or both. Use the formula for your index type to calculate total size:
A [dense index](/guides/index-data/indexing-overview#dense-indexes) contains records with one dense vector each. Dense index records can also contain sparse vectors (when the index metric is set to `dotproduct`), which can be useful for [hybrid search](/guides/search/hybrid-search#use-a-single-hybrid-index). To learn how to calculate the size of a hybrid index, see [Hybrid index](#hybrid-index). **Calculate dense index size (assuming no sparse vectors)** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. **Example dense index calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg metadata size | Index size | | :--------- | :---------------------- | :---------------- | :--------- | | 500,000 | 768 | 500 bytes | 1.79 GB | | 1,000,000 | 1536 | 1,000 bytes | 7.15 GB | | 5,000,000 | 1024 | 15,000 bytes | 95.5 GB | | 10,000,000 | 1536 | 1,000 bytes | 71.5 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + 500 bytes of metadata) = 1.79 GB A [sparse index](/guides/index-data/indexing-overview#sparse-indexes) contains records with one sparse vector each. **Calculate sparse index size** ``` Index size = Number of records × ( ID size + Metadata size + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * `Number of non-zero sparse values`: Average number across all records. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example sparse index calculations** These examples assume 8-byte IDs: | Records | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 10 | 500 bytes | 0.29 GB | | 1,000,000 | 50 | 1,000 bytes | 1.41 GB | | 5,000,000 | 100 | 15,000 bytes | 79.0 GB | | 10,000,000 | 50 | 1,000 bytes | 14.1 GB | Example: 500,000 records × (8-byte ID + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 0.29 GB A [hybrid index](/guides/search/hybrid-search#use-a-single-hybrid-index) contains records that each have one dense vector and an optional sparse vector. **Calculate hybrid index size** ``` Index size = Number of records × ( ID size + Metadata size + Dense vector dimensions × 4 bytes + Number of non-zero sparse values × 8 bytes ) ``` Where: * `ID size` and `Metadata size` are measured in bytes, averaged across all records. * Each `Dense vector dimension` uses 4 bytes. * `Number of non-zero sparse values`: Average number across all records, including those without sparse vectors. To find the count for a single record, check the length of the sparse vector's `indices` or `values` array. Each non-zero value uses 8 bytes. **Example hybrid index calculations** These examples assume 8-byte IDs: | Records | Dense vector dimensions | Avg number of non-zero sparse values | Avg metadata size | Index size | | :--------- | :---------------------- | :----------------------------------- | :---------------- | :--------- | | 500,000 | 768 | 10 | 500 bytes | 1.83 GB | | 1,000,000 | 1536 | 50 | 1,000 bytes | 7.54 GB | | 5,000,000 | 1024 | 100 | 15,000 bytes | 99.5 GB | | 10,000,000 | 1536 | 50 | 1,000 bytes | 75.4 GB | Example: 500,000 records × (8-byte ID + (768 dense vector dimensions × 4 bytes) + (10 non-zero sparse values × 8 bytes) + 500 bytes of metadata) = 1.83 GB
## Imports [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. The cost of an import is based on the size of the records read, whether the records were imported successfully or not. If the import operation fails (e.g., after encountering a vector of the wrong dimension in an import with `on_error="abort"`), you will still be charged for the records read. However, if the import fails because of an internal system error, you will not incur charges. In this case, the import will return the error message `"We were unable to process your request. If the problem persists, please contact us at https://support.pinecone.io"`. For the latest import pricing rates, see [Pricing](https://www.pinecone.io/pricing/). ## Backups and restores A [backup](/guides/manage-data/backups-overview) is a static copy of a serverless index. Both the cost of storing a backup and [restoring an index](/guides/manage-data/restore-an-index) from a backup is based on the size of the index. For the latest backup and restore pricing rates, see [Pricing](https://www.pinecone.io/pricing/?plan=standard\&provider=aws\&plans=database\&scrollTo=product-pricing-modal-section). ## Embedding Pinecone hosts several [embedding models](/guides/index-data/create-an-index#embedding-models) so it's easy to manage your vector storage and search process on a single platform. You can use a hosted model to embed your data as an integrated part of upserting and querying, or you can use a hosted model to embed your data as a standalone operation. Embedding costs are determined by how many [tokens](https://www.pinecone.io/learn/tokenization/) are in a request. In general, the more words contained in your passage or query, the more tokens you generate. For example, if you generate embeddings for the query, "What is the maximum diameter of a red pine?", Pinecone Inference generates 10 tokens, then converts them into an embedding. If the price per token for your billing plan is \$.08 per million tokens, then this API call costs \$.00001. To learn more about tokenization, see [Choosing an embedding model](https://www.pinecone.io/learn/series/rag/embedding-models-rundown/). For the latest embed pricing rates, see [Pricing](https://www.pinecone.io/pricing/?plan=standard\&provider=aws\&plans=inference\&scrollTo=product-pricing-modal-section). Embedding requests returns the total tokens generated. You can use this information to [monitor and manage embedding costs](/guides/manage-cost/monitor-usage-and-costs#embedding-tokens). ## Reranking Pinecone hosts several [reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. Reranking costs are determined by the number of requests to the reranking model. For the latest rerank pricing rates, see [Pricing](https://www.pinecone.io/pricing/?plan=standard\&provider=aws\&plans=inference\&scrollTo=product-pricing-modal-section). ## Assistant For details on how costs are incurred in Pinecone Assistant, see [Assistant pricing](/guides/assistant/pricing-and-limits). ## See also * [Manage cost](/guides/manage-cost/manage-cost) * [Monitor usage](/guides/manage-cost/monitor-usage-and-costs) * [Pricing](https://www.pinecone.io/pricing/) # Back up an index Source: https://docs.pinecone.io/guides/manage-data/back-up-an-index Create backups of serverless indexes for protection ## 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/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" backupName := "example-backup" backupDesc := "Monthly backup of production index" backup, err := pc.CreateBackup(ctx, &pinecone.CreateBackupParams{ IndexName: indexName, Name: &backupName, Description: &backupDesc, }) if err != nil { log.Fatalf("Failed to create backup: %v", err) } fmt.Printf(prettifyStruct(backup)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); var backup = await pinecone.Backups.BackupIndexAsync( "docs-example", new BackupIndexRequest { Name = "example-backup", Description = "Monthly backup of production index" } ); Console.WriteLine(backup); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-backup", "description": "Monthly backup of production index" }' ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', 'cloud': 'aws', 'created_at': '2025-05-15T00:52:10.809305882Z', 'description': 'Monthly backup of production index', 'dimension': 1024, 'name': 'example-backup', 'namespace_count': 3, 'record_count': 98, 'region': 'us-east-1', 'size_bytes': 1069169, 'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', 'source_index_name': 'docs-example', 'status': 'Ready', 'tags': {}} ``` ```javascript JavaScript theme={null} { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ``` ```java Java theme={null} class BackupModel { backupId: 0d75b99f-be61-4a93-905e-77201286c02e sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:42:23.804787550Z additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "region": "us-east-1", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Initializing", "tags": {} } ``` ```csharp C# theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "name": "example-backup", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "created_at": "2025-05-15T00:52:10.809305882Z" } ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":96, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-05-14T16:37:25.625540Z" } ``` You can create a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/backups). ## Describe a backup You can [view the details of a backup](/reference/api/latest/control-plane/describe_backup) as follows. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") backup = pc.describe_backup(backup_id="8c85e612-ed1c-4f97-9f8c-8194e07bcf71") print(backup) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const backupDesc = await pc.describeBackup('8c85e612-ed1c-4f97-9f8c-8194e07bcf71'); console.log(backupDesc); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); BackupModel backupModel = pc.describeBackup("8c85e612-ed1c-4f97-9f8c-8194e07bcf71"); System.out.println(backupModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } backup, err := pc.DescribeBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71") if err != nil { log.Fatalf("Failed to describe backup: %v", err) } fmt.Printf(prettifyStruct(backup)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); var backup = await pinecone.Backups.GetAsync("8c85e612-ed1c-4f97-9f8c-8194e07bcf71"); Console.WriteLine(backup); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71" curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', 'cloud': 'aws', 'created_at': '2025-05-15T00:52:10.809354Z', 'description': 'Monthly backup of production index', 'dimension': 1024, 'name': 'example-backup', 'namespace_count': 3, 'record_count': 98, 'region': 'us-east-1', 'size_bytes': 1069169, 'source_index_id': 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', 'source_index_name': 'docs-example', 'status': 'Ready', 'tags': {}} ``` ```javascript JavaScript theme={null} { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 95707edb-e482-49cf-b5a5-312219a51a97 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809354Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "namespace_count": 3, "record_count": 98, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Ready", "tags": {} } ``` ```csharp C# theme={null} { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "name": "example-backup", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 97, "namespace_count": 2, "size_bytes": 1069169, "tags": {}, "created_at": "2025-05-15T00:52:10.809354Z" } ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ``` You can view backup details using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). ## List backups for an index You can [list backups for a specific index](/reference/api/latest/control-plane/list_index_backups) as follows. Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_backups = pc.list_backups(index_name="docs-example") print(index_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexBackups = await pc.listBackups({ indexName: 'docs-example' }); console.log(indexBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList indexBackupList = pc.listIndexBackups(indexName); System.out.println(indexBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" limit := 2 indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, IndexName: &indexName, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(indexBackups)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexBackups = await pinecone.Backups.ListByIndexAsync( "docs-example", new ListBackupsByIndexRequest()); Console.WriteLine(indexBackups); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809305882Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-16T18:01:51.531129Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "cloud": "aws", "created_at": "2025-05-14T17:00:45.803146Z", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready" } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```csharp C# theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ] } ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console. ## List backups in a project You can [list backups for all indexes in a project](/reference/api/latest/control-plane/list_project_backups) as follows. Up to 100 backups are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of backups are returned instead. Whenever there are additional backups to return, the response also includes a `pagination_token` that you can use to get the next batch of backups. When the response does not include a `pagination_token`, there are no more backups to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") project_backups = pc.list_backups() print(project_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const projectBackups = await pc.listBackups(); console.log(projectBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList projectBackupList = pc.listProjectBackups(); System.out.println(projectBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } limit := 3 backups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(backups)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); var backups = await pinecone.Backups.ListAsync(); Console.WriteLine(backups); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T20:26:21.248515Z" }, { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "source_index_name": "docs-example2", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup2", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 97, "namespace_count": 2, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809354Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example3", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: 'e12269b0-a29b-4af0-9729-c7771dec03e3', sourceIndexName: 'docs-example', sourceIndexId: 'bcb5b3c9-903e-4cb6-8b37-a6072aeb874f', name: 'example-backup', description: undefined, status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 0, metric: undefined, recordCount: 96, namespaceCount: 1, sizeBytes: 86393, tags: undefined, createdAt: '2025-05-14T17:00:45.803146Z' }, { backupId: 'd686451d-1ede-4004-9f72-7d22cc799b6e', sourceIndexName: 'docs-example2', sourceIndexId: 'b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6', name: 'example-backup2', description: undefined, status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 50, namespaceCount: 1, sizeBytes: 545171, tags: undefined, createdAt: '2025-05-14T17:00:34.814371Z' }, { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example3', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup3', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 13761d20-7a0b-4778-ac27-36dd91c4be43 sourceIndexName: example-dense-index sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }, class BackupModel { backupId: 0d75b99f-be61-4a93-905e-77201286c02e sourceIndexName: example-dense-index sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup2 description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:42:23.804820Z additionalProperties: null }, class BackupModel { backupId: bf2cda5d-b233-4a0a-aae9-b592780ad3ff sourceIndexName: example-sparse-index sourceIndexId: bcb5b3c9-903e-4cb6-8b37-a6072aeb874f name: example-backup3 description: Monthly backup of production index status: Ready cloud: aws region: us-east-1 dimension: 0 metric: null recordCount: 96 namespaceCount: 1 sizeBytes: 86393 tags: {} createdAt: 2025-05-16T18:01:51.531129Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup", "namespace_count": 3, "record_count": 98, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-15T00:52:10.809305882Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "example-sparse-index", "status": "Ready", "tags": {} }, { "backup_id": "f73028f6-1746-410e-ab6d-9dd2519df4de", "cloud": "aws", "created_at": "2025-05-15T20:26:21.248515Z", "description": "Monthly backup of production index", "dimension": 1024, "name": "example-backup3", "namespace_count": 2, "record_count": 97, "region": "us-east-1", "size_bytes": 1069169, "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "example-dense-index", "status": "Ready", "tags": {} } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```csharp C# theme={null} { "data": [ { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "name": "example-backup", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 97, "namespace_count": 2, "size_bytes": 1069169, "tags": {}, "created_at": "2025-05-15T00:52:10.809354Z" }, { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "source_index_name": "docs-example2", "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "name": "example-backup2", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 0, "record_count": 96, "namespace_count": 1, "size_bytes": 86393, "created_at": "2025-05-14T17:00:45.803146Z" }, { "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e", "source_index_name": "docs-example3", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "name": "example-backup3", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 50, "namespace_count": 1, "size_bytes": 545171, "created_at": "2025-05-14T17:00:34.814371Z" } ] } ``` ```json curl theme={null} { "data": [ { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "tags": null, "name": "example-backup", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 0, "record_count": 96, "namespace_count": 1, "size_bytes": 86393, "created_at": "2025-05-14T17:00:45.803146Z" }, { "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "source_index_name": "docs-example2", "tags": null, "name": "example-backup2", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 50, "namespace_count": 1, "size_bytes": 545171, "created_at": "2025-05-14T17:00:34.814371Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example3", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" } ], "pagination": null } ``` You can view all backups in a project using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). ## Delete a backup You can [delete a backup](/reference/api/latest/control-plane/delete_backup) as follows. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_backup(backup_id="9947520e-d5a1-4418-a78d-9f464c9969da") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) await pc.deleteBackup('9947520e-d5a1-4418-a78d-9f464c9969da'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteBackup("9947520e-d5a1-4418-a78d-9f464c9969da"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } err = pc.DeleteBackup(ctx, "8c85e612-ed1c-4f97-9f8c-8194e07bcf71") if err != nil { log.Fatalf("Failed to delete backup: %v", err) } else { fmt.Println("Backup deleted successfully") } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); await pinecone.Backups.DeleteAsync("9947520e-d5a1-4418-a78d-9f464c9969da"); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da" curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` You can delete a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects-/backups). # Backups overview Source: https://docs.pinecone.io/guides/manage-data/backups-overview Learn about backups of serverless indexes in Pinecone. A backup is a static copy of a serverless [index](/guides/index-data/indexing-overview) that only consumes storage. It is a non-queryable representation of a set of records. You can [create a backup](/guides/manage-data/back-up-an-index) of a serverless index, and you can [create a new serverless index from a backup](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations. ## Use cases Creating a backup is useful when performing tasks like the following: * Protecting an index from manual or system failures. * Temporarily shutting down an index. * Copying the data from one index into a different index. * Making a backup of your index. * Experimenting with different index configurations. ## 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 | Standard plan | Enterprise plan | | :------------------ | :----------- | :------------ | :-------------- | | Backups per project | N/A | 500 | 1000 | ## 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, cloud provider, and region as the source index. * 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. ## Backup and restore cost * To understand how cost is calculated for backups and restores, see [Understanding cost](/guides/manage-cost/understanding-cost#backups-and-restores). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). # Delete records Source: https://docs.pinecone.io/guides/manage-data/delete-data Delete records by ID or metadata filter from indexes This page shows you how to [delete](/reference/api/latest/data-plane/delete) records from an index [namespace](/guides/index-data/indexing-overview#namespaces). ## Delete records by ID Since Pinecone records can always be efficiently accessed using their ID, deleting by ID is the most efficient way to remove specific records from a namespace. To remove records from the default namespace, specify `"__default__"` as the namespace in your request. ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete(ids=["id-1", "id-2"], namespace='example-namespace') ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') // Delete one record by ID. await ns.deleteOne('id-1'); // Delete more than one record by ID. await ns.deleteMany(['id-2', 'id-3']); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List ids = Arrays.asList("id-1", "id-2"); index.deleteByIds(ids, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } id1 := "id-1" id2 := "id-2" err = idxConnection.DeleteVectorsById(ctx, []string{id1, id2}) if err != nil { log.Fatalf("Failed to delete vector with ID %v: %v", id, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var deleteResponse = await index.DeleteAsync(new DeleteRequest { Ids = new List { "id-1", "id-2" }, Namespace = "example-namespace", }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "ids": [ "id-1", "id-2" ], "namespace": "example-namespace" } ' ``` ## Delete records by metadata To delete records from a namespace based on their metadata values, pass a [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to the `delete` operation. This deletes all records in the namespace that match the filter expression. For example, the following code deletes all records with a `genre` field set to `documentary` from namespace `example-namespace`: ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete( filter={ "genre": {"$eq": "documentary"} }, namespace="example-namespace" ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const ns = index.namespace('example-namespace') await ns.deleteMany({ genre: { $eq: "documentary" }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); Struct filter = Struct.newBuilder() .putFields("genre", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("documentary") .build())) .build()) .build(); index.deleteByFilter(filter, "example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } metadataFilter := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } filter, err := structpb.NewStruct(metadataFilter) if err != nil { log.Fatalf("Failed to create metadata filter: %v", err) } err = idxConnection.DeleteVectorsByFilter(ctx, filter) if err != nil { log.Fatalf("Failed to delete vector(s) with filter %+v: %v", filter, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var deleteResponse = await index.DeleteAsync(new DeleteRequest { Namespace = "example-namespace", Filter = new Metadata { ["genre"] = new Metadata { ["$eq"] = "documentary" } } }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -i "https://$INDEX_HOST/vectors/delete" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "filter": {"genre": {"$eq": "documentary"}}, "namespace": "example-namespace" }' ``` ## Delete all records in a namespace To delete all of the records in a namespace but not the namespace itself, provide a `namespace` parameter and specify the appropriate `deleteAll` parameter for your SDK. To target the default namespace, set `namespace` to `"__default__"`. ```Python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.delete(delete_all=True, namespace='example-namespace') ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').deleteAll(); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.Arrays; import java.util.List; public class DeleteExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); index.deleteAll("example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } err = idxConnection.DeleteAllVectorsInNamespace(ctx) if err != nil { log.Fatalf("Failed to delete all vectors in namespace %v: %v", namespace, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var deleteResponse = await index.DeleteAsync(new DeleteRequest { DeleteAll = true, Namespace = "example-namespace", }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deleteAll": true, "namespace": "example-namespace" } ' ``` ## Delete an entire namespace To delete an entire namespace and all of its records, see [Delete a namespace](/guides/manage-data/manage-namespaces#delete-a-namespace). ## Delete an entire index To remove all records from an index, [delete the index](/guides/manage-data/manage-indexes#delete-an-index) and [recreate it](/guides/index-data/create-an-index). ## Delete limits **Delete by ID limits:** | Metric | Limit | | :------------------ | :--------------------------------------------- | | Max IDs per request | 1000 IDs | | Max request rate | 5000 records per second per index or namespace | **Delete by metadata limits:** | Metric | Limit | | :--------------- | :------------------------------------------------------------------------- | | Max request rate | 5 requests per second per namespace
500 requests per second per index | ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Fetch records Source: https://docs.pinecone.io/guides/manage-data/fetch-data Retrieve complete records by ID or metadata filter. You can fetch data using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser). ## Fetch records by ID To fetch records from a namespace based on their IDs, use the `fetch` operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. To use the default namespace, set this to `"__default__"`. * `ids`: The IDs of the records to fetch. Maximum of 1000. ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.fetch(ids=["id-1", "id-2"], namespace="example-namespace") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const fetchResult = await index.namespace('example-namespace').fetch(['id-1', 'id-2']); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.FetchResponse; import java.util.Arrays; import java.util.List; public class FetchExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List ids = Arrays.asList("id-1", "id-2"); FetchResponse fetchResponse = index.fetch(ids, "example-namespace"); System.out.println(fetchResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } res, err := idxConnection.FetchVectors(ctx, []string{"id-1", "id-2"}) if err != nil { log.Fatalf("Failed to fetch vectors: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var fetchResponse = await index.FetchAsync(new FetchRequest { Ids = new List { "id-1", "id-2" }, Namespace = "example-namespace" }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response looks like this: ```Python Python theme={null} {'namespace': 'example-namespace', 'usage': {'readUnits': 1}, 'vectors': {'id-1': {'id': 'id-1', 'values': [0.568879, 0.632687092, 0.856837332, ...]}, 'id-2': {'id': 'id-2', 'values': [0.00891787093, 0.581895, 0.315718859, ...]}}} ``` ```JavaScript JavaScript theme={null} {'namespace': 'example-namespace', 'usage': {'readUnits': 1}, 'records': {'id-1': {'id': 'id-1', 'values': [0.568879, 0.632687092, 0.856837332, ...]}, 'id-2': {'id': 'id-2', 'values': [0.00891787093, 0.581895, 0.315718859, ...]}}} ``` ```java Java theme={null} namespace: "example-namespace" vectors { key: "id-1" value { id: "id-1" values: 0.568879 values: 0.632687092 values: 0.856837332 ... } } vectors { key: "id-2" value { id: "id-2" values: 0.00891787093 values: 0.581895 values: 0.315718859 ... } } usage { read_units: 1 } ``` ```go Go theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [ -0.0089730695, -0.020010853, -0.0042787646, ... ] }, "id-2": { "id": "id-2", "values": [ -0.005380766, 0.00215196, -0.014833462, ... ] } }, "usage": { "read_units": 1 } } ``` ```csharp C# theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [ -0.0089730695, -0.020010853, -0.0042787646, ... ], "sparseValues": null, "metadata": null }, "vec1": { "id": "id-2", "values": [ -0.005380766, 0.00215196, -0.014833462, ... ], "sparseValues": null, "metadata": null } }, "namespace": "example-namespace", "usage": { "readUnits": 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 This feature is in [early access](/release-notes/feature-availability) and is available only on the `2025-10` version of the API. To fetch records from a namespace based on their metadata values, use the `fetch_by_metadata` operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to fetch. To use the default namespace, set this to `"__default__"`. * `filter`: A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to match the records to fetch. * `limit`: The number of matching records to return. Defaults to 100. Maximum of 10,000. For example, the following code fetches 200 records with a `genre` field set to `documentary` from namespace `example-namespace`: ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": {"rating": {"$lt": 5}}, "limit": 2 }' ``` The response looks like this: ```json curl theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [ -0.0273742676, -0.000517368317, ... ], "metadata": { "main_category": "Books", "rating": 4, "review": "Identical twins have only one purpose in movies and plays: to cause mass confusion...", "title": "A comedy of twin-switching" } }, "id-2": { "id": "id-2", "values": [ -0.00305938721, 0.0234375, ... ], "metadata": { "main_category": "Automotive", "rating": 1, "review": "If I could rate this 1/2 a star I would! These both broke within 10 minutes of using it. The only upside is the cloth is removable so it can be used with good old fashioned elbow grease. Epic waste!", "title": "Dont waste your money!" } } }, "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` ## 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 | 4MB | | Max response rate | 10 requests per second per namespace | ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # List record IDs Source: https://docs.pinecone.io/guides/manage-data/list-record-ids List the IDS of records in an index namespace. You can list the IDs of all records in a [namespace](/guides/index-data/indexing-overview#namespaces) or just the records with a common ID prefix. Using `list` to get record IDs and not the associated data is a cheap and fast way to check [upserts](/guides/index-data/upsert-data). The `list` endpoint is supported only for serverless indexes. ## List the IDs of all records in a namespace To list the IDs of all records in the namespace of a serverless index, pass only the `namespace` parameter: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") for ids in index.list(namespace='example-namespace'): print(ids) # Response: # ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3'] ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated(); console.log(results); // { // vectors: [ // { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' }, // { id: 'doc1#04' }, { id: 'doc1#05' }, { id: 'doc1#06' }, // { id: 'doc1#07' }, { id: 'doc1#08' }, { id: 'doc1#09' }, // ... // ], // pagination: { // next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LS04MCIsInByZWZpeCI6InByZVRlc3QifQ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } // Fetch the next page of results await index.listPaginated({ prefix: 'doc1#', paginationToken: results.pagination.next}); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListResponse; public class ListExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); // get the pagination token String paginationToken = index.list("example-namespace", 3).getPagination().getNext(); // get vectors with limit 3 with the paginationToken obtained from the previous step ListResponse listResponse = index.list("example-namespace", 3, paginationToken); } } // Response: // vectors { // id: "doc1#chunk1" // } // vectors { // id: "doc1#chunk2" // } // vectors { // id: "doc2#chunk1" // } // vectors { // id: "doc3#chunk1" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(3) res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk1", // "doc1#chunk2", // "doc1#chunk3" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var listResponse = await index.ListAsync(new ListRequest { Namespace = "example-namespace", }); Console.WriteLine(listResponse); // Response: // { // "vectors": [ // { // "id": "doc1#chunk1" // }, // { // "id": "doc1#chunk2" // }, // { // "id": "doc1#chunk3" // } // ], // "pagination": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9", // "namespace": "example-namespace", // "usage": { // "readUnits": 1 // } // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc1#chunk1" }, # { "id": "doc1#chunk2" }, # { "id": "doc1#chunk3" }, # { "id": "doc1#chunk4" }, # ... # ], # "pagination": { # "next": "c2Vjb25kY2FsbA==" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` ## List the IDs of records with a common prefix ID prefixes enable you to query segments of content. Use the `list` endpoint to list all of the records with the common prefix. For more details, see [Use structured IDs](/guides/index-data/data-modeling#use-structured-ids). ## Paginate through results The `list` endpoint returns up to 100 IDs per page at a time by default. If the `limit` parameter is passed, `list` returns up to that number of IDs per page instead. For example, if `limit=3`, up to 3 IDs be returned per page. Whenever there are additional IDs to return, the response also includes a `pagination_token` for fetching the next page of IDs. ### Implicit pagination When using the Python SDK, `list` paginates automatically. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") for ids in index.list(namespace='example-namespace'): print(ids) # Response: # ['doc1#chunk1', 'doc1#chunk2', 'doc1#chunk3'] # ['doc1#chunk4', 'doc1#chunk5', 'doc1#chunk6'] # ... ``` ### Manual pagination When using the Node.js SDK, Java SDK, Go SDK, .NET SDK, or REST API, you must manually fetch each page of results. You can also manually paginate with the Python SDK using `list_paginated()`. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' # For manual control over pagination results = index.list_paginated( prefix='pref', limit=3, namespace='example-namespace' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Results: # ['10103-0', '10103-1', '10103-10'] # eyJza2lwX3Bhc3QiOiIxMDEwMy0= # {'read_units': 1} ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated({ prefix: 'doc1#', limit: 3 }); console.log(results); // Response: // { // vectors: [ // { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' } // ], // pagination: { // next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LSCIsInByZWZpeCI6InByZVRlc3QifQ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListResponse; public class ListExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); ListResponse listResponse = index.list("example-namespace", "doc1#" 2); /* Note: You must include an ID prefix to list vector IDs. */ System.out.println(listResponse.getVectorsList()); System.out.println(listResponse.getPagination()); } } // Response: // vectors { // id: "doc1#chunk1" // } // vectors { // id: "doc1#chunk2" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(3) res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk1", // "doc1#chunk2", // "doc1#chunk3" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var listResponse = await index.ListAsync(new ListRequest { Namespace = "example-namespace", Prefix = "document1#", }); Console.WriteLine(listResponse); // Response: // { // "vectors": [ // { // "id": "doc1#chunk1" // }, // { // "id": "doc1#chunk2" // }, // { // "id": "doc1#chunk3" // } // ], // "pagination": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9", // "namespace": "example-namespace", // "usage": { // "readUnits": 1 // } // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc1#chunk1" }, # { "id": "doc1#chunk2" }, # { "id": "doc1#chunk3" }, # { "id": "doc1#chunk4" }, # ... # ], # "pagination": { # "next": "c2Vjb25kY2FsbA==" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` Then, to get the next batch of IDs, use the returned `pagination_token`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' results = index.list_paginated( prefix='pref', limit=3, namespace='example-namespace', pagination_token='eyJza2lwX3Bhc3QiOiIxMDEwMy0=' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Response: # ['10103-0', '10103-1', '10103-10'] # xndlsInByZWZpeCI6IjEwMTAzIn0== # {'read_units': 1} ``` ```js JavaScript theme={null} await index.listPaginated({ prefix: 'doc1#', limit: 3, paginationToken: results.pagination.next}); // Response: // { // vectors: [ // { id: 'doc1#10' }, { id: 'doc1#11' }, { id: 'doc1#12' } // ], // pagination: { // next: 'dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==' // }, // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```java Java theme={null} listResponse = index.list("example-namespace", "doc1#", "eyJza2lwX3Bhc3QiOiJ2MTg4IiwicHJlZml4IjpudWxsfQ=="); System.out.println(listResponse.getVectorsList()); // Response: // vectors { // id: "doc1#chunk3" // } // vectors { // id: "doc1#chunk4" // } // vectors { // id: "doc1#chunk5" // } // vectors { // id: "doc1#chunk6" // } // vectors { // id: "doc1#chunk7" // } // vectors { // id: "doc1#chunk8" // } // pagination { // next: "eyJza2lwX3Bhc3QiOiJhbHN0cm9lbWVyaWEtcGVydXZpYW4iLCJwcmVmaXgiOm51bGx9" // } // namespace: "example-namespace" // usage { // read_units: 1 // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(3) paginationToken := "dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==" res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, PaginationToken: &paginationToken, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk4", // "doc1#chunk5", // "doc1#chunk6" // ], // "usage": { // "read_units": 1 // }, // "next_pagination_token": "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var listResponse = await index.ListAsync(new ListRequest { Namespace = "example-namespace", Prefix = "document1#", PaginationToken= "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9", }); Console.WriteLine(listResponse); // Response: // { // "vectors": [ // { // "id": "doc1#chunk4" // }, // { // "id": "doc1#chunk5" // }, // { // "id": "doc1#chunk6" // } // ], // "pagination": "dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==", // "namespace": "example-namespace", // "usage": { // "readUnits": 1 // } // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=c2Vjb25kY2FsbA%3D%3D" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # { "id": "doc2#chunk1" }, # ... # ], # "pagination": { # "next": "mn23b4jB3Y9jpsS1" # }, # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` When there are no more IDs to return, the response does not includes a `pagination_token`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key='YOUR_API_KEY') index = pc.Index(host="INDEX_HOST") namespace = 'example-namespace' results = index.list_paginated( prefix='10103', limit=3, pagination_token='xndlsInByZWZpeCI6IjEwMTAzIn0==' ) print(results.namespace) print([v.id for v in results.vectors]) print(results.pagination.next) print(results.usage) # Response: # ['10103-4', '10103-5', '10103-6'] # {'read_units': 1} ``` ```js JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone(); const index = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const results = await index.listPaginated({ prefix: 'doc1#' }); console.log(results); // Response: // { // vectors: [ // { id: 'doc1#19' }, { id: 'doc1#20' }, { id: 'doc1#21' } // ], // namespace: 'example-namespace', // usage: { readUnits: 1 } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(3) paginationToken := "eyJza2lwX3Bhc3QiOiIwMDBkMTc4OC0zMDAxLTQwZmMtYjZjNC0wOWI2N2I5N2JjNDUiLCJwcmVmaXgiOm51bGx9" res, err := idxConnection.ListVectors(ctx, &pinecone.ListVectorsRequest{ Limit: &limit, paginationToken: &paginationToken, }) if len(res.VectorIds) == 0 { fmt.Println("No vectors found") } else { fmt.Printf(prettifyStruct(res)) } } // Response: // { // "vector_ids": [ // "doc1#chunk7", // "doc1#chunk8", // "doc1#chunk9" // ], // "usage": { // "read_units": 1 // } // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index(host: "INDEX_HOST"); var listResponse = await index.ListAsync(new ListRequest { Namespace = "example-namespace", Prefix = "document1#", PaginationToken= "dfajlkjfdsoijeowjoDJFKLJldLIFf34KFNLDSndaklqoLQJORN45afdlkJ==", }); Console.WriteLine(listResponse); // Response: // { // "vectors": [ // { // "id": "doc1#chunk7" // }, // { // "id": "doc1#chunk8" // }, // { // "id": "doc1#chunk9" // } // ], // "pagination": null, // "namespace": "example-namespace", // "usage": { // "readUnits": 1 // } // } ``` ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&paginationToken=mn23b4jB3Y9jpsS1" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "vectors": [ # { "id": "doc3#chunk1" }, # { "id": "doc5#chunk2" }, # { "id": "doc5#chunk3" }, # { "id": "doc5#chunk4" }, # ... # ], # "namespace": "example-namespace", # "usage": { # "readUnits": 1 # } # } ``` # Manage serverless indexes Source: https://docs.pinecone.io/guides/manage-data/manage-indexes List, describe, and configure serverless indexes. This page shows you how to manage your existing serverless indexes. ## List indexes Use the [`list_indexes`](/reference/api/latest/control-plane/list_indexes) operation to get a complete description of all indexes in a project: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_list = pc.list_indexes() print(index_list) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexList = await pc.listIndexes(); console.log(indexList); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ListIndexesExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexList indexList = pc.listIndexes(); System.out.println(indexList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idxs, err := pc.ListIndexes(ctx) if err != nil { log.Fatalf("Failed to list indexes: %v", err) } else { for _, index := range idxs { fmt.Printf("index: %v\n", prettifyStruct(index)) } } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexList = await pinecone.ListIndexesAsync(); Console.WriteLine(indexList); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```python Python theme={null} [{ "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse", "dimension": null, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense", "dimension": 1536, "deletion_protection": "disabled", "tags": { "environment": "development" } }] ``` ```javascript JavaScript theme={null} { indexes: [ { name: 'docs-example-sparse', dimension: undefined, metric: 'dotproduct', host: 'docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'sparse' }, { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ] } ``` ```java Java theme={null} class IndexList { indexes: [class IndexModel { name: docs-example-sparse dimension: null metric: dotproduct host: docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: sparse additionalProperties: null }, class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null }] additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-sparse", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "dotproduct", "vector_type": "sparse", "deletion_protection": "disabled", "dimension": null, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```csharp C# theme={null} { "indexes": [ { "name": "docs-example-sparse", "metric": "dotproduct", "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "deletion_protection": "disabled", "tags": { "environment": "development" }, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "sparse" }, { "name": "docs-example-dense", "dimension": 1536, "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "deletion_protection": "disabled", "tags": { "environment": "development" }, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense" } ] } ``` ```json curl theme={null} { "indexes": [ { "name": "docs-example-sparse", "vector_type": "sparse", "metric": "dotproduct", "dimension": null, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } }, { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ] } ``` With the Python SDK, you can use the `.names()` helper function to iterate over the index names in the `list_indexes()` response, for example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec for index_name in pc.list_indexes().names: print(index_name) ``` ## Describe an index Use the [`describe_index`](/reference/api/latest/control-plane/describe_index/) endpoint to get a complete description of a specific index: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOURE_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexModel = await pinecone.DescribeIndexAsync("docs-example"); Console.WriteLine(indexModel); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like this: ```Python Python theme={null} {'deletion_protection': 'disabled', 'dimension': 1536, 'host': 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', 'metric': 'cosine', 'name': 'docs-example-dense', 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, 'status': {'ready': True, 'state': 'Ready'}, 'tags': {'environment': 'development'}, 'vector_type': 'dense'} ``` ```javaScript JavaScript theme={null} { name: 'docs-example-dense', dimension: 1536, metric: 'cosine', host: 'docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'development', example: 'tag' }, embed: undefined, spec: { pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ``` ```java Java theme={null} class IndexModel { name: docs-example-dense dimension: 1536 metric: cosine host: docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io deletionProtection: disabled tags: {environment=development} embed: null spec: class IndexModelSpec { pod: null serverless: class ServerlessSpec { cloud: aws region: us-east-1 additionalProperties: null } additionalProperties: null } status: class IndexModelStatus { ready: true state: Ready additionalProperties: null } vectorType: dense additionalProperties: null } ``` ```go Go theme={null} index: { "name": "docs-example-dense", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "metric": "cosine", "vector_type": "dense", "deletion_protection": "disabled", "dimension": 1536, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "development" } } ``` ```csharp C# theme={null} { "name": "docs-example-dense", "dimension": 1536, "metric": "cosine", "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "deletion_protection": "disabled", "tags": { "environment": "development" }, "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "vector_type": "dense" } ``` ```json curl theme={null} { "name": "docs-example-dense", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "development" } } ``` **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Delete an index Use the [`delete_index`](reference/api/latest/control-plane/delete_index) operation to delete an index and all of its associated resources. ```python Python theme={null} # pip install "pinecone[grpc]" from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.delete_index(name="docs-example") ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.deleteIndex('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; public class DeleteIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.deleteIndex("docs-example"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" err = pc.DeleteIndex(ctx, indexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Println("Index \"%v\" deleted successfully", indexName) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); await pinecone.DeleteIndexAsync("docs-example"); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` If deletion protection is enabled on an index, requests to delete it will fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` Before you can delete such an index, you must first [disable deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). You can delete an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). For the index you want to delete, click the three dots to the right of the index name, then click **Delete**. ## Associate an embedding model [Integrated inference](/guides/index-data/indexing-overview#integrated-embedding) lets you upsert and search without extra steps for embedding data and reranking results. To configure an existing serverless index for an embedding model, use the [`configure_index`](/reference/api/latest/control-plane/configure_index) operation as follows: * Set `embed.model` to one of [Pinecone's hosted embedding models](/guides/index-data/create-an-index#embedding-models). * Set `embed.field_map` to the name of the field in your source document that contains the data for embedding. The `vector_type`, `metric`, and `dimension` of the index must be supported by the specified embedding model. ```python Python theme={null} # pip install --upgrade pinecone from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.configureIndex('docs-example', { embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' }, }, }); ``` ```json curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" } } }' ``` ## Configure deletion protection This feature requires [Pinecone API version](/reference/api/versioning) `2024-07`, [Python SDK](/reference/python-sdk) v5.0.0, [Node.js SDK](/reference/node-sdk) v3.0.0, [Java SDK](/reference/java-sdk) v2.0.0, or [Go SDK](/reference/go-sdk) v1.0.0 or later. ### Enable deletion protection You can prevent an index and its data from accidental deleting when [creating a new index](/guides/index-data/create-an-index) or after its been created. In both cases, you set the `deletion_protection` parameter to `enabled`. Enabling deletion protection does *not* prevent [namespace deletions](/guides/manage-data/manage-namespaces#delete-a-namespace). To enable deletion protection when creating a new index: ```python Python theme={null} # pip install "pinecone[grpc]" # Serverless index from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} // npm install @pinecone-database/pinecone // Serverles index import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'enabled', }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; // Serverless index public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.enabled); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Serverless index indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{ "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // Serverless index var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1536, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1", } }, DeletionProtection = DeletionProtection.Enabled }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # Serverless index curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "deletion_protection": "enabled" }' ``` To enable deletion protection when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'enabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "enabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexMetadata = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { DeletionProtection = DeletionProtection.Enabled, }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "enabled" }' ``` When deletion protection is enabled on an index, requests to delete the index fail and return a `403 - FORBIDDEN` status with the following error: ``` Deletion protection is enabled for this index. Disable deletion protection before retrying. ``` ### Disable deletion protection Before you can [delete an index](#delete-an-index) with deletion protection enabled, you must first disable deletion protection as follows: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", deletion_protection="disabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { deletionProtection: 'disabled' }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); pc.configureServerlessIndex("docs-example", DeletionProtection.DISABLED); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{DeletionProtection: "disabled"}) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var configureIndexRequest = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { DeletionProtection = DeletionProtection.Disabled, }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "disabled" }' ``` ## Configure index tags Tags are key-value pairs that you can use to categorize and identify the index. ### Add tags To add tags to an index, use the `tags` parameter when [creating a new index](/guides/index-data/create-an-index) or configuring an existing index. To add tags when creating a new index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "example": "tag", "environment": "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { example: 'tag', environment: 'development' }, }); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; import java.util.HashMap; // Serverless index public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("tag", "development"); pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1", DeletionProtection.DISABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Serverless index idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: "docs-example", Dimension: 1536, Metric: pinecone.Cosine, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: "disabled", Tags: &pinecone.IndexTags{ "example": "tag", "environment": "development" }, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var createIndexRequest = await pinecone.CreateIndexAsync(new CreateIndexRequest { Name = "docs-example", Dimension = 1536, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "example", "tag" }, { "environment", "development" } } }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" # Serverless index curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "example": "tag", "environment": "development" }, "deletion_protection": "disabled" }' ``` You can add tags during index creation using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/create-index/). To add or update tags when configuring an existing index: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", tags={ example: "tag", environment: "development" } ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { tags: { example: 'tag', environment: 'development' }}); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; import java.util.HashMap; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("tag", "development"); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{ Tags: pinecone.IndexTags{ "example": "tag", "environment": "development", }, }, ) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var configureIndexRequest = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { Tags = new Dictionary { { "example", "tag" }, { "environment", "development" } } }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "tags": { "example": "tag", "environment": "development" } }' ``` You can add or update tags when configuring an existing index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > Add tags**. ### View tags To view the tags of an index, [list all indexes](/guides/manage-data/manage-indexes) in a project or [get information about a specific index](/guides/manage-data/manage-indexes). ### Remove tags To remove a tag from an index, [configure the index](/reference/api/latest/control-plane/configure_index) and use the `tags` parameter to send the tag key with an empty value (`""`). The following example removes the `example: tag` tag from `docs-example`: ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.configure_index( name="docs-example", tags={"example": ""} ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await client.configureIndex('docs-example', { tags: { example: '' }}); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; import java.util.HashMap; public class ConfigureIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); HashMap tags = new HashMap<>(); tags.put("example", ""); pc.configureServerlessIndex("docs-example", DeletionProtection.ENABLED, tags); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.ConfigureIndex(ctx, "docs-example", pinecone.ConfigureIndexParams{ Tags: pinecone.IndexTags{ "example": "", }, }, ) if err != nil { log.Fatalf("Failed to configure index \"%v\": %v", idx.Name, err) } else { fmt.Printf("Successfully configured index \"%v\"", idx.Name) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var configureIndexRequest = await pinecone.ConfigureIndexAsync("docs-example", new ConfigureIndexRequest { Tags = new Dictionary { { "example", "" } } }); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s -X PATCH "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "tags": { "example": "" } }' ``` You can remove tags from an index using the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes). Find the index to edit and click the **ellipsis (...) menu > \_\_ tags**. ## List backups for an index Serverless indexes can be [backed up](/guides/manage-data/back-up-an-index). You can [list all backups for a specific index](/reference/api/latest/control-plane/list_index_backups), as in the following example: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index_backups = pc.list_backups(index_name="docs-example") print(index_backups) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const indexBackups = await pc.listBackups({ indexName: 'docs-example' }); console.log(indexBackups); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; BackupList indexBackupList = pc.listIndexBackups(indexName); System.out.println(indexBackupList); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" limit := 2 indexBackups, err := pc.ListBackups(ctx, &pinecone.ListBackupsParams{ Limit: &limit, IndexName: &indexName, }) if err != nil { log.Fatalf("Failed to list backups: %v", err) } fmt.Printf(prettifyStruct(indexBackups)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexBackups = await pinecone.Backups.ListByIndexAsync( "docs-example", new ListBackupsByIndexRequest()); Console.WriteLine(indexBackups); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` The example returns a response like the following: ```python Python theme={null} [{ "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_name": "docs-example", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "status": "Ready", "cloud": "aws", "region": "us-east-1", "tags": {}, "name": "example-backup", "description": "Monthly backup of production index", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-15T00:52:10.809305882Z" }] ``` ```javascript JavaScript theme={null} { data: [ { backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', sourceIndexName: 'docs-example', sourceIndexId: 'f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74', name: 'example-backup', description: 'Monthly backup of production index', status: 'Ready', cloud: 'aws', region: 'us-east-1', dimension: 1024, metric: undefined, recordCount: 98, namespaceCount: 3, sizeBytes: 1069169, tags: {}, createdAt: '2025-05-14T16:37:25.625540Z' } ], pagination: undefined } ``` ```java Java theme={null} class BackupList { data: [class BackupModel { backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 sourceIndexName: docs-example sourceIndexId: f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74 name: example-backup description: Monthly backup of production index status: Initializing cloud: aws region: us-east-1 dimension: null metric: null recordCount: null namespaceCount: null sizeBytes: null tags: {} createdAt: 2025-05-16T19:46:26.248428Z additionalProperties: null }] pagination: null additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "bf2cda5d-b233-4a0a-aae9-b592780ad3ff", "cloud": "aws", "created_at": "2025-05-16T18:01:51.531129Z", "description": "Monthly backup of production index", "dimension": 0, "name": "example-backup", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready", "tags": {} }, { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "cloud": "aws", "created_at": "2025-05-14T17:00:45.803146Z", "dimension": 0, "name": "example-backup2", "namespace_count": 1, "record_count": 96, "region": "us-east-1", "size_bytes": 86393, "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "status": "Ready" } ], "pagination": { "next": "eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ==" } } ``` ```csharp C# theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ] } ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` You can view the backups for a specific index from either the [Backups](https://app.pinecone.io/organizations/-/projects/-/backups) tab or the [Indexes](https://app.pinecone.io/organizations/-/projects/-/indexes) tab in the Pinecone console. # Manage namespaces Source: https://docs.pinecone.io/guides/manage-data/manage-namespaces Create and manage namespaces in serverless indexes. ## Create a namespace This feature is in [early access](/release-notes/feature-availability) and available only on the `2025-10` version of the API. Namespaces are created automatically during [upsert](/guides/index-data/upsert-data). However, you can also create namespaces ahead of time using the [`create_namespace`](/reference/api/2025-10/data-plane/createnamespace) operation. Specify a name for the namespace and, optionally, the [metadata fields to index](/guides/index-data/create-an-index#metadata-indexing). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": {"filterable": true}, "document_title": {"filterable": true}, "chunk_number": {"filterable": true}, "document_url": {"filterable": true}, "created_at": {"filterable": true} } } }' ``` The response will look like the following: ```json curl theme={null} { "name": "example-namespace", "record_count": "0", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` ## List all namespaces in an index Use the [`list_namespaces`](/reference/api/latest/data-plane/listnamespaces) operation to list all namespaces in a serverless index. Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") # Implicit pagination using a generator function for namespace in index.list_namespaces(): print(namespace.name, ":", namespace.record_count) # Manual pagination namespaces = index.list_namespaces_paginated( limit=2, pagination_token="eyJza2lwX3Bhc3QiOiIxMDEwMy0=" ) print(namespaces) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); const namespaceList = await index.listNamespaces(); console.log(namespaceList); ``` ```java Java theme={null} import io.pinecone.clients.AsyncIndex; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.ListNamespacesResponse; import org.openapitools.db_data.client.ApiException; public class Namespaces { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); // List all namespaces with default pagination limit (100) ListNamespacesResponse listNamespacesResponse = index.listNamespaces(null, null); // List all namespaces with pagination limit of 2 ListNamespacesResponse listNamespacesResponseWithLimit = index.listNamespaces(2); // List all namespaces with pagination limit and token ListNamespacesResponse listNamespacesResponsePaginated = index.listNamespaces(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0="); System.out.println(listNamespacesResponseWithLimit); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } limit := uint32(10) namespaces, err := idxConnection.ListNamespaces(ctx, &pinecone.ListNamespacesParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list namespaces: %v", err) } fmt.Printf(prettifyStruct(namespaces)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var namespaces = await index.ListNamespacesAsync(new ListNamespacesRequest()); Console.WriteLine(namespaces); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/namespaces" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like the following: ```python Python theme={null} # Implicit pagination example-namespace : 20000 example-namespace2 : 10500 example-namespace3 : 10000 ... # Manual pagination { "namespaces": [ { "name": "example-namespace", "record_count": "20000" }, { "name": "example-namespace2", "record_count": "10500" } ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` ```javascript JavaScript theme={null} { namespaces: [ { name: 'example-namespace', recordCount: '20000' }, { name: 'example-namespace2', recordCount: '10500' }, ... ], pagination: "Tm90aGluZyB0byBzZWUgaGVyZQo=" } ``` ```java Java theme={null} namespaces { name: "example-namespace" record_count: 20000 } namespaces { name: "example-namespace2" record_count: 10500 } pagination { next: "eyJza2lwX3Bhc3QiOiJlZDVhYzFiNi1kMDFiLTQ2NTgtYWVhZS1hYjJkMGI2YzBiZjQiLCJwcmVmaXgiOm51bGx9" } ``` ```go Go theme={null} { "Namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "Pagination": { "next": "eyJza2lwX3Bhc3QiOiIyNzQ5YTU1YS0zZTQ2LTQ4MDItOGFlNi1hZTJjZGNkMTE5N2IiLCJwcmVmaXgiOm51bGx9" } } ``` ```csharp C# theme={null} { "namespaces":[ {"name":"example-namespace","recordCount":20000}, {"name":"example-namespace2","recordCount":10500}, ... ], "pagination":"Tm90aGluZyB0byBzZWUgaGVyZQo=" } ``` ```json curl theme={null} { "namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` ## Describe a namespace Use the [`describe_namespace`](/reference/api/latest/data-plane/describenamespace) operation to get details about a namespace in a serverless index, including the total number of vectors in the namespace. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") namespace = index.describe_namespace(namespace="example-namespace") print(namespace) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const index = pc.index('docs-example'); const namespace = await index.describeNamespace('example-namespace'); console.log(namespace); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.NamespaceDescription; import org.openapitools.db_data.client.ApiException; public class Namespaces { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); NamespaceDescription namespaceDescription = index.describeNamespace("example-namespace"); System.out.println(namespaceDescription); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } namespace, err := idxConnection.DescribeNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to describe namespace: %v", err) } fmt.Printf(prettifyStruct(namespace)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var @namespace = await index.DescribeNamespaceAsync("example-namespace"); Console.WriteLine(@namespace); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" NAMESPACE="NAMESPACE_NAME" # To target the default namespace, use "__default__". curl -X GET "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response will look like the following: ```python Python theme={null} { "name": "example-namespace", "record_count": "20000" } ``` ```javascript JavaScript theme={null} { name: 'example-namespace', recordCount: '20000' } ``` ```java Java theme={null} name: "example-namespace" record_count: 20000 ``` ```go Go theme={null} { "name": "example-namespace", "record_count": 20000 } ``` ```csharp C# theme={null} {"name":"example-namespace","recordCount":20000} ``` ```json curl theme={null} { "name": "example-namespace", "record_count": 20000 } ``` ## Delete a namespace Use the [`delete_namespace`](/reference/api/latest/data-plane/deletenamespace) operation to delete a namespace in a serverless index. Deleting a namespace is irreversible. All data in the namespace is permanently deleted. ```python Python theme={null} # Not supported with pinecone["grpc"] extras installed from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") index.delete_namespace(namespace="example-namespace") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const index = pc.index('INDEX_NAME', 'INDEX_HOST'); const namespace = await index.deleteNamespace('example-namespace'); console.log(namespace); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import java.util.concurrent.ExecutionException; public class DeleteNamespace { public static void main(String[] args) throws ExecutionException, InterruptedException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "docs-example"); index.deleteNamespace("example-namespace"); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } err := idxConnection.DeleteNamespace(ctx, "example-namespace") if err != nil { log.Fatalf("Failed to delete namespace: %v", err) } } ``` ```csharp C# theme={null} using Pinecone; const pinecone = new PineconeClient("PINECONE_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pinecone.Index(host: "INDEX_HOST"); await index.DeleteNamespaceAsync("example-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 DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## Rename a namespace Pinecone does not support renaming namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the namespace and [upsert the records](/guides/index-data/upsert-data) to a new namespace. ## Move records to a new namespace Pinecone does not support moving records between namespaces directly. Instead, you must [delete the records](/guides/manage-data/delete-data) in the old namespace and [upsert the records](/guides/index-data/upsert-data) to the new namespace. ## Use the default namespace To use the default namespace for upserts, queries, or other data operations, set the `namespace` parameter to `__default__`, for example: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 2 }, fields=["category", "chunk_text"] ) print(results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 2, inputs: { text: 'Disease prevention' }, }, fields: ['chunk_text', 'category'], }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the dense index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 2, null, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 2, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 4, Inputs = new Dictionary { { "text", "Disease prevention" } }, }, Fields = ["category", "chunk_text"], } ); Console.WriteLine(response); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="NAMESPACE_NAME" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 2 }, "fields": ["category", "chunk_text"] }' ``` # Restore an index Source: https://docs.pinecone.io/guides/manage-data/restore-an-index Restore serverless indexes from backup snapshots. ## 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, dimension and similarity metric, and associated embedding model when restoring an index with [integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To [create a serverless index from a backup](/reference/api/latest/control-plane/create_index_from_backup), provide the ID of the backup, the name of the new index, and, optionally, changes to the index tags and deletion protection settings: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index_from_backup( backup_id="a65ff585-d987-4da5-a622-72e19a6ed5f4", name="restored-index", tags={ "tag0": "val0", "tag1": "val1" }, deletion_protection="enabled" ) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const response = await pc.createIndexFromBackup({ backupId: 'a65ff585-d987-4da5-a622-72e19a6ed5f4', name: 'restored-index', tags: { tag0: 'val0', tag1: 'val1' }, deletionProtection: 'enabled' }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); String backupID = "a65ff585-d987-4da5-a622-72e19a6ed5f4"; String indexName = "restored-index"; CreateIndexFromBackupResponse backupResponse = pc.createIndexFromBackup(backupID, indexName); System.out.println(backupResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "time" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "restored-index" restoredIndexTags := pinecone.IndexTags{"restored_on": time.Now().Format("2006-01-02 15:04")} createIndexFromBackupResp, err := pc.CreateIndexFromBackup(ctx, &pinecone.CreateIndexFromBackupParams{ BackupId: "e12269b0-a29b-4af0-9729-c7771dec03e3", Name: indexName, Tags: &restoredIndexTags, }) fmt.Printf(prettifyStruct(createIndexFromBackupResp)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var response = await pinecone.Backups.CreateIndexFromBackupAsync( "a65ff585-d987-4da5-a622-72e19a6ed5f4", new CreateIndexFromBackupRequest { Name = "restored-index", Tags = new Dictionary { { "tag0", "val0" }, { "tag1", "val1" } }, DeletionProtection = DeletionProtection.Enabled } ); Console.WriteLine(response); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4" curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H 'Content-Type: application/json' \ -d '{ "name": "restored-index", "tags": { "tag0": "val0", "tag1": "val1" }, "deletion_protection": "enabled" }' ``` The example returns a response like the following: ```python Python theme={null} {'deletion_protection': 'enabled', 'dimension': 1024, 'embed': {'dimension': 1024, 'field_map': {'text': 'chunk_text'}, 'metric': 'cosine', 'model': 'multilingual-e5-large', 'read_parameters': {'input_type': 'query', 'truncate': 'END'}, 'vector_type': 'dense', 'write_parameters': {'input_type': 'passage', 'truncate': 'END'}}, 'host': 'example-dense-index-python3-govk0nt.svc.aped-4627-b74a.pinecone.io', 'metric': 'cosine', 'name': 'example-dense-index-python3', 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, 'status': {'ready': True, 'state': 'Ready'}, 'tags': {'tag0': 'val0', 'tag1': 'val1'}, 'vector_type': 'dense'} ``` ```javascript JavaScript theme={null} { restoreJobId: 'e9ba8ff8-7948-4cfa-ba43-34227f6d30d4', indexId: '025117b3-e683-423c-b2d1-6d30fbe5027f' } ``` ```java Java theme={null} class CreateIndexFromBackupResponse { restoreJobId: e9ba8ff8-7948-4cfa-ba43-34227f6d30d4 indexId: 025117b3-e683-423c-b2d1-6d30fbe5027f additionalProperties: null } ``` ```go Go theme={null} { "index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4" } ``` ```csharp C# theme={null} { "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f" } ``` ```json curl theme={null} { "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f" } ``` You can create a serverless index from a backup using the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## List restore jobs You can [list all restore jobs](/reference/api/latest/control-plane/list_restore_jobs) as follows. Up to 100 restore jobs are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of restore jobs are returned instead. Whenever there are additional restore jobs to return, the response also includes a `pagination_token` that you can use to get the next batch of jobs. When the response does not include a `pagination_token`, there are no more restore jobs to return. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") restore_jobs = pc.list_restore_jobs() print(restore_jobs) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const restoreJobs = await pc.listRestoreJobs(); console.log(restoreJobs); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build(); // List all restore jobs with default pagination limit RestoreJobList restoreJobList = pc.listRestoreJobs(null, null); // List all restore jobs with pagination limit of 5 RestoreJobList restoreJobListWithLimit = pc.listRestoreJobs(5); // List all restore jobs with pagination limit and token RestoreJobList restoreJobListPaginated = pc.listRestoreJobs(5, "eyJza2lwX3Bhc3QiOiIxMDEwMy0="); System.out.println(restoreJobList); System.out.println(restoreJobListWithLimit); System.out.println(restoreJobListPaginated); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } limit := 2 restoreJobs, err := pc.ListRestoreJobs(ctx, &pinecone.ListRestoreJobsParams{ Limit: &limit, }) if err != nil { log.Fatalf("Failed to list restore jobs: %v", err) } fmt.Printf(prettifyStruct(restoreJobs)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var jobs = await pinecone.RestoreJobs.ListAsync(new ListRestoreJobsRequest()); Console.WriteLine(jobs); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/restore-jobs" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" ``` The example returns a response like the following: ```python Python theme={null} [{ "restore_job_id": "06b08366-a0a9-404d-96c2-e791c71743e5", "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "target_index_name": "restored-index", "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961", "status": "Completed", "created_at": "2025-05-15T13:59:51.439479+00:00", "completed_at": "2025-05-15T14:00:09.222998+00:00", "percent_complete": 100.0 }, { "restore_job_id": "4902f735-b876-4e53-a05c-bc01d99251cb", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "027aff93-de40-4f48-a573-6dbcd654f961", "status": "Completed", "created_at": "2025-05-15T21:06:19.906074+00:00", "completed_at": "2025-05-15T21:06:39.360509+00:00", "percent_complete": 100.0 }] ``` ```javascript JavaScript theme={null} { data: [ { restoreJobId: '69acc1d0-9105-4fcb-b1db-ebf97b285c5e', backupId: '8c85e612-ed1c-4f97-9f8c-8194e07bcf71', targetIndexName: 'restored-index2', targetIndexId: 'e6c0387f-33db-4227-9e91-32181106e56b', status: 'Completed', createdAt: 2025-05-14T17:25:59.378Z, completedAt: 2025-05-14T17:26:23.997Z, percentComplete: 100 }, { restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326', backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57', targetIndexName: 'restored-index', targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85', status: 'Completed', createdAt: 2025-04-25T18:14:05.227Z, completedAt: 2025-04-25T18:14:11.074Z, percentComplete: 100 } ], pagination: undefined } ``` ```java Java theme={null} class RestoreJobList { data: [class RestoreJobModel { restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa backupId: 0d75b99f-be61-4a93-905e-77201286c02e targetIndexName: restored-index targetIndexId: 8a810881-1505-46c0-b906-947c048b15f5 status: Completed createdAt: 2025-05-16T20:09:18.700631Z completedAt: 2025-05-16T20:11:30.673296Z percentComplete: 100.0 additionalProperties: null }, class RestoreJobModel { restoreJobId: 4902f735-b876-4e53-a05c-bc01d99251cb backupId: 8c85e612-ed1c-4f97-9f8c-8194e07bcf71 targetIndexName: restored-index2 targetIndexId: 710cb6e6-bfb4-4bf5-a425-9754e5bbc832 status: Completed createdAt: 2025-05-15T21:06:19.906074Z completedAt: 2025-05-15T21:06:39.360509Z percentComplete: 100.0 additionalProperties: null }] pagination: class PaginationResponse { next: eyJsaW1pdCI6Miwib2Zmc2V0IjoyfQ== additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "data": [ { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "completed_at": "2025-05-16T20:11:30.673296Z", "created_at": "2025-05-16T20:09:18.700631Z", "percent_complete": 100, "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "status": "Completed", "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "target_index_name": "restored-index" }, { "backup_id": "95707edb-e482-49cf-b5a5-312219a51a97", "completed_at": "2025-05-15T21:04:34.2463Z", "created_at": "2025-05-15T21:04:15.949067Z", "percent_complete": 100, "restore_job_id": "eee4f8b8-cd3e-45fe-9ed5-93c28e237f24", "status": "Completed", "target_index_id": "5a0d555f-7ccd-422a-a3a6-78f7b73350c0", "target_index_name": "restored-index2" } ], "pagination": { "next": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9" } } ``` ```csharp C# 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 } ] } ``` ```json curl theme={null} { "data": [ { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 }, { "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b", "status": "Completed", "created_at": "2025-05-14T17:25:59.378989Z", "completed_at": "2025-05-14T17:26:23.997284Z", "percent_complete": 100 } ], "pagination": null } ``` ## View restore job details You can [view the details of a specific restore job](/reference/api/latest/control-plane/describe_restore_job), as in the following example: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") restore_job = pc.describe_restore_job(job_id="9857add2-99d4-4399-870e-aa7f15d8d326") print(restore_job) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }) const restoreJob = await pc.describeRestoreJob('9857add2-99d4-4399-870e-aa7f15d8d326'); console.log(restoreJob); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.ApiException; import org.openapitools.db_control.client.model.*; public class CreateIndexFromBackup { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API-KEY").build(); RestoreJobModel restoreJob = pc.describeRestoreJob("9857add2-99d4-4399-870e-aa7f15d8d326"); System.out.println(restoreJob); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } restoreJob, err := pc.DescribeRestoreJob(ctx, "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4") if err != nil { log.Fatalf("Failed to describe restore job: %v", err) } fmt.Printf(prettifyStruct(restoreJob)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var job = await pinecone.RestoreJobs.GetAsync("9857add2-99d4-4399-870e-aa7f15d8d326"); Console.WriteLine(job); ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326" curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' ``` The example returns a response like the following: ```python Python theme={null} {'backup_id': '94a63aeb-efae-4f7a-b059-75d32c27ca57', 'completed_at': datetime.datetime(2025, 4, 25, 18, 14, 11, 74618, tzinfo=tzutc()), 'created_at': datetime.datetime(2025, 4, 25, 18, 14, 5, 227526, tzinfo=tzutc()), 'percent_complete': 100.0, 'restore_job_id': '9857add2-99d4-4399-870e-aa7f15d8d326', 'status': 'Completed', 'target_index_id': '0d8aed24-adf8-4b77-8e10-fd674309dc85', 'target_index_name': 'restored-index'} ``` ```javascript JavaScript theme={null} { restoreJobId: '9857add2-99d4-4399-870e-aa7f15d8d326', backupId: '94a63aeb-efae-4f7a-b059-75d32c27ca57', targetIndexName: 'restored-index', targetIndexId: '0d8aed24-adf8-4b77-8e10-fd674309dc85', status: 'Completed', createdAt: 2025-04-25T18:14:05.227Z, completedAt: 2025-04-25T18:14:11.074Z, percentComplete: 100 } ``` ```java Java theme={null} class RestoreJobModel { restoreJobId: cf597d76-4484-4b6c-b07c-2bfcac3388aa backupId: 0d75b99f-be61-4a93-905e-77201286c02e targetIndexName: restored-index targetIndexId: 0d8aed24-adf8-4b77-8e10-fd674309dc85 status: Completed createdAt: 2025-05-16T20:09:18.700631Z completedAt: 2025-05-16T20:11:30.673296Z percentComplete: 100.0 additionalProperties: null } ``` ```go Go theme={null} { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "completed_at": "2025-05-16T20:11:30.673296Z", "created_at": "2025-05-16T20:09:18.700631Z", "percent_complete": 100, "restore_job_id": "e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "status": "Completed", "target_index_id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "target_index_name": "restored-index" } ``` ```csharp C# 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 } ``` ```json curl theme={null} { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 } ``` # Target an index Source: https://docs.pinecone.io/guides/manage-data/target-an-index Target an index by host or name for data operations such as upsert and query. **Do not target an index by name in production.** When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. ## Target by index host (recommended) This method is recommended for production: When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/connect-to-aws-privatelink#run-data-plane-commands) for the host. ```Python Python {5} theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") ``` ```javascript JavaScript {6} theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index("INDEX_NAME", "INDEX_HOST"); ``` ```java Java {11} theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; public class TargetIndexByHostExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); // For the Java SDK, you must specify both the index host and name. Index index = new Index(connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // This creates a new gRPC index connection, targeting the namespace "example-namespace" idxConnectionNs1, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } // This reuses the gRPC index connection, targeting a different namespace idxConnectionNs2 := idxConnectionNs1.WithNamespace("example-namespace2") } ``` ```csharp C# {5} theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index(host: "INDEX_HOST"); ``` ### Get an index host You can get the unique DNS host for an index from the Pinecone console or the Pinecone API. To get an index host from the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index. 3. Select the index. 4. Copy the URL under **HOST**. To get an index host from the Pinecone API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the index host as the `host` value: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") pc.describe_index(name="docs-example") # Response: # {'deletion_protection': 'disabled', # 'dimension': 1536, # 'host': 'docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io', # 'metric': 'cosine', # 'name': 'docs-example', # 'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}}, # 'status': {'ready': True, 'state': 'Ready'}} ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io", // "deletionProtection": "disabled", // "spec": { // "serverless": { // "cloud": "aws", // "region": "us-east-1" // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class DescribeIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); IndexModel indexModel = pc.describeIndex("docs-example"); System.out.println(indexModel); } } // Response: // class IndexModel { // name: docs-example-java // dimension: 1536 // metric: cosine // host: docs-example-4zo0ijk.svc.us-west2-aws.pinecone.io // deletionProtection: enabled // spec: class IndexModelSpec { // pod: null // serverless: class ServerlessSpec { // cloud: aws // region: us-east-1 // } // } // status: class IndexModelStatus { // ready: true // state: Ready // } // } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } // Response: // index: { // "name": "docs-example", // "dimension": 1536, // "host": "docs-example-govk0nt.svc.apw5-4e34-81fa.pinecone.io", // "metric": "cosine", // "deletion_protection": "disabled", // "spec": { // "serverless": { // "cloud": "aws", // "region": "us-east-1" // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var indexModel = await pinecone.DescribeIndexAsync("docs-example"); Console.WriteLine(indexModel); // Response: // { // "name": "docs-example", // "dimension": 1536, // "metric": "cosine", // "host": "docs-example-govk0nt.svc.aped-4627-b74a.pinecone.io", // "deletion_protection": "disabled", // "spec": { // "pod": null, // "serverless": { // "cloud": "aws", // "region": "us-east-1" // } // }, // "status": { // "ready": true, // "state": "Ready" // } // } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example-curl" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" # Response: # { # "name": "docs-example", # "metric": "cosine", # "dimension": 1536, # "status": { # "ready": true, # "state": "Ready" # }, # "host": "docs-example-4zo0ijk.svc.us-east1-aws.pinecone.io", # "spec": { # "serverless": { # "region": "us-east-1", # "cloud": "aws" # } # } # } ``` ## Target by index name This method is convenient for testing but is not recommended for production: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("docs-example") ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index('docs-example'); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; public class GenerateEmbeddings { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Index index = pc.getIndexConnection("docs-example"); } } ``` ```go Go theme={null} // It is not possible to target an index by name in the Go SDK. // You must target an index by host. ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("docs-example"); ``` # Update records Source: https://docs.pinecone.io/guides/manage-data/update-data Update vectors and metadata for existing records You can [update](/reference/api/latest/data-plane/update) a single record using the record ID or multiple records using a metadata filter. * When updating by ID, you change the vector and/or metadata of a single record. * When updating by metadata, you change metadata across multiple records using a metadata filter. To update entire records, use the [upsert](/guides/index-data/upsert-data) operation instead. ## Update by ID To update the vector and/or metadata of a single record, use the [`update`](/reference/api/latest/data-plane/update) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the record to update. To use the default namespace, set the namespace to `"__default__"`. * `id`: The ID of the record to update. * One or both of the following: * Updated values for the vector. Specify one of the following: * `values`: For dense vectors. Must have the same length as the existing vector. * `sparse_values`: For sparse vectors. * `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified, and if a specified metadata field does not exist, it is added. If a non-existent record ID is specified, no records are affected and a `200 OK` status is returned. In this example, assume you are updating the dense vector values and one metadata value of the following record in the `example-namespace` namespace: ``` ( namespace="example-namespace", id="id-3", values=[4.0, 2.0], setMetadata={"type": "doc", "genre": "drama"} ) ``` ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.update( namespace="example-namespace", id="id-3", values=[5.0, 3.0], set_metadata={"genre": "comedy"} ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") await index.namespace('example-namespace').update({ id: 'id-3', values: [5.0, 3.0], metadata: { genre: "comedy", }, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.proto.UpdateResponse; import java.util.Arrays; import java.util.List; public class UpdateExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List values = Arrays.asList(5.0f, 3.0f); Struct metaData = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("comedy").build()) .build(); UpdateResponse updateResponse = index.update("id-3", values, metaData, "example-namespace", null, null); System.out.println(updateResponse); } } ``` ```go Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } id := "id-3" metadataMap := map[string]interface{}{ "genre": "comedy", } metadataFilter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } err = idxConnection.UpdateVector(ctx, &pinecone.UpdateVectorRequest{ Id: id, Values: []float32{5.0, 3.0}, Metadata: metadataFilter, }) if err != nil { log.Fatalf("Failed to update vector with ID %v: %v", id, err) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var updateResponse = await index.UpdateAsync(new UpdateRequest { Id = "id-3", Namespace = "example-namespace", Values = new[] { 5.0f, 3.0f }, SetMetadata = new Metadata { ["genre"] = new("comedy") } }); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" # Update both values and metadata curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "id-3", "values": [5.0, 3.0], "setMetadata": {"genre": "comedy"}, "namespace": "example-namespace" }' ``` After the update, the dense vector values and the `genre` metadata value are changed, but the `type` metadata value is unchanged: ``` ( id="id-3", values=[5.0, 3.0], metadata={"type": "doc", "genre": "comedy"} ) ``` ## Update by metadata This feature is in [public preview](/release-notes/feature-availability) and is available only on the `2025-10` version of the API. See [limitations](#limitations) for details. To add or change metadata across multiple records in a namespace, use the `update` operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) containing the records to update. To use the default namespace, set this to `"__default__"`. * `filter`: A [metadata filter expression](/guides/index-data/indexing-overview#metadata-filter-expressions) to match the records to update. * `setMetadata`: The metadata to add or change. When updating metadata, only the specified metadata fields are modified. If a specified metadata field does not exist, it is added. * `dry_run`: Optional. If `true`, the number of records that match the filter expression is returned, but the records are not updated. Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example below for details. For example, let's say you have records that represent chunks of a single document with metadata that keeps track of chunk and document details, and you want to store the author's name with each chunk of the document: ```json theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1" } }, ... ``` 1. To check how many records match the filter expression, send a request with `"dry_run": true`: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` The response contains the number of records that match the filter expression: ```json theme={null} { "matchedVectors": 150000 } ``` Since this number exceeds the 100,000 record limit, you'll need to run the update request multiple times. 2. Initiate the first update by sending the request without the `dry_run` parameter: ```bash curl theme={null} curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` Again, the response contains the total number of records that match the filter expression, but only 100,000 will be updated: ```json theme={null} { "matchedVectors": 150000 } ``` 3. Pinecone is eventually consistent, so there can be a slight delay before your update request is processed. Repeat the `dry_run` request until the number of matching records shows that the first 100,000 records have been updated: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedVectors": 50000 } ``` 4. Once the first 100,000 records have been updated, update the remaining records: ```bash curl theme={null} curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` 5. Repeat the `dry_run` request until the number of matching records shows that the remaining records have been updated: ```bash curl {11} theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "dry_run": true, "namespace": "example-namespace", "filter": { "document_title": {"$eq": "Introduction to Vector Databases"} }, "setMetadata": { "author": "Del Klein" } }' ``` ```json theme={null} { "matchedVectors": 0 } ``` Once the request has completed, all matching records include the author name as metadata: ```json {10,22} theme={null} { "id": "document1#chunk1", "values": [0.0236663818359375, -0.032989501953125, ..., -0.01041412353515625, 0.0086669921875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 1, "chunk_text": "First chunk of the document content...", "document_url": "https://example.com/docs/document1", "author": "Del Klein" } }, { "id": "document1#chunk2", "values": [-0.0412445068359375, 0.028839111328125, ..., 0.01953125, -0.0174560546875], "metadata": { "document_id": "document1", "document_title": "Introduction to Vector Databases", "chunk_number": 2, "chunk_text": "Second chunk of the document content...", "document_url": "https://example.com/docs/document1", "author": "Del Klein" } }, ... ``` ### Limitations * This feature is available only on the `2025-10` version of the API. * Each request updates a maximum of 100,000 records. Use `"dry_run": true` to check if you need to run the request multiple times. See the example above for details. * You can add or change metadata across multiple records, but you cannot remove metadata fields. ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before updates are visible to queries. You can [use log sequence numbers](/guides/index-data/check-data-freshness#check-the-log-sequence-number) to check whether an update request has completed. # Integrate with Amazon S3 Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-amazon-s3 Set up Amazon S3 integrationfor data import and audit logs. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page shows you how to integrate Pinecone with an Amazon S3 bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index hosted on AWS, or to [export audit logs](/guides/production/configure-audit-logs) to your Amazon S3 bucket. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/). * An [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets.html). ## 1. Create an IAM policy In the [AWS IAM console](https://console.aws.amazon.com/iam/home): 1. In the navigation pane, click **Policies**. 2. Click **Create policy**. 3. In **Select a service** section, select **S3**. 4. Select the following actions to allow: * `ListBucket`: Permission to list some or all of the objects in an S3 bucket. Required for [importing data](/guides/index-data/import-data) and [exporting audit logs](/guides/production/configure-audit-logs). * `GetObject`: Permission to retrieve objects from an S3 bucket. Required for [importing data](/guides/index-data/import-data). * `PutObject`: Permission to add an object to an S3 bucket. Required for [exporting audit logs](/guides/production/configure-audit-logs). 5. In the **Resources** section, select **Specific**. 6. For the **bucket**, specify the ARN of the bucket you created. For example: `arn:aws:s3:::example-bucket-name` 7. For the **object**, specify an object ARN as the target resource. For example: `arn:aws:s3:::example-bucket-name/*` 8. Click **Next**. 9. Specify the name of your policy. For example: "Pinecone-S3-Access". 10. Click **Create policy**. ### Targeting a subdirectory (optional) To write [audit logs](/guides/production/configure-audit-logs) to a specific subdirectory within your S3 bucket (e.g., `my-bucket/pinecone-logs/`), you need to configure your IAM policy differently for `ListBucket` vs. object-level actions: 1. For `ListBucket`, use a **Condition** block with `StringLike` to specify the prefix. Include both the directory path with and without the trailing wildcard: ```json theme={null} { "Sid": "ListBucketWithPrefix", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example-bucket-name", "Condition": { "StringLike": { "s3:prefix": [ "pinecone-logs/", "pinecone-logs/*" ] } } } ``` 2. For `PutObject` and `GetObject`, use the **Resource** specifier with the subdirectory path: ```json theme={null} { "Sid": "ObjectActionsInSubdirectory", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject" ], "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*" } ``` **Complete example policy for subdirectory access:** ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "ListBucketWithPrefix", "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::example-bucket-name", "Condition": { "StringLike": { "s3:prefix": [ "pinecone-logs/", "pinecone-logs/*" ] } } }, { "Sid": "ObjectActionsInSubdirectory", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:GetObject" ], "Resource": "arn:aws:s3:::example-bucket-name/pinecone-logs/*" } ] } ``` The key difference is that `ListBucket` operates on the bucket resource and uses conditions to filter by prefix, while object-level actions (`PutObject`, `GetObject`) operate directly on object resources specified in the ARN. ## 2. Set up access using an IAM role In the [AWS IAM console](https://console.aws.amazon.com/iam/home): 1. In the navigation pane, click **Roles**. 2. Click **Create role**. 3. In the **Trusted entity type** section, select **AWS account**. 4. Select **Another AWS account**. 5. Enter the Pinecone AWS VPC account ID: `713131977538` 6. Click **Next**. 7. Select the [policy you created](#1-create-an-iam-policy). 8. Click **Next**. 9. Specify the role name. For example: "Pinecone". 10. Click **Create role**. 11. Click the role you created. 12. On the **Summary** page for the role, find the **ARN**. For example: `arn:aws:iam::123456789012:role/PineconeAccess` 13. Copy the **ARN**. You will need to enter the ARN into Pinecone later. ## 3. Add a storage integration This step is required for [importing data](/guides/index-data/import-data). It is not required for [storing audit logs](/guides/production/configure-audit-logs). In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Amazon S3.. 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Amazon S3**. 6. Enter the **ARN** of the [IAM role you created](/guides/operations/integrations/integrate-with-amazon-s3#2-set-up-access-using-an-iam-role). 7. Click **Add integration**. ## Next steps * [Import data](/guides/index-data/import-data) from your Amazon S3 bucket into a Pinecone index. * [Configure audit logs](/guides/production/configure-audit-logs) to export logs to your Amazon S3 bucket. # Integrate with Azure Blob Storage Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-azure-blob-storage Set up Azure Blob Storage integration for data import. This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page describes how to integrate Pinecone with Azure Blob Storage. After setting up an integration, you can [import data](/guides/index-data/import-data) from an Azure Blob Storage container into a Pinecone index hosted on AWS, GCP, or Azure. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/) * An [Azure Blob Storage container](https://learn.microsoft.com/azure/storage/blobs/storage-blobs-introduction) ## 1. Create an app registration and service principal Pinecone uses a service principal to access your Azure Blob Storage container. 1. [Create an app registration](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app) for your Pinecone integration. This automatically creates a service principal. When creating your app registration: * Do not specify a **Redirect URI**. * Copy the **Application (client) ID** and the **Directory (tenant) ID**. You'll use these values when adding a storage integration in Pinecone. 2. [Create a client secret](https://learn.microsoft.com/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for the service principal. Copy the secret's **Value** (not its **ID**). You'll use this when creating a storage integration in Pinecone. ## 2. Grant access to the storage account [Assign the service principal to your storage account](https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal#assign-azure-rbac-roles-using-the-azure-portal): 1. In the Azure portal, navigate to the subscription associated with your storage account. 2. Select **Access control (IAM)**. 3. Click **Add** > **Add role assignment**. 4. Select **Storage Blob Data Reader** or another role that has permission to list and read blobs in a container. 5. Click **Next**. 6. Select **User, group, or service principal** and click **Select members**. 7. Select the app you created in the previous step. 8. Click **Review + assign** (you may need to click this twice). ## 3. In Pinecone, add a storage integration In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Azure Blob Storage: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Azure Blob Storage**. 6. For **Tenant ID**, **Client ID**, and **Client secret**, enter the values you copied from Azure. 7. Click **Add integration**. ## Next steps [Import data](/guides/index-data/import-data) from your Azure Blob Storage container into your Pinecone index. # Integrate with Google Cloud Storage Source: https://docs.pinecone.io/guides/operations/integrations/integrate-with-google-cloud-storage Integrate Google Cloud Storage for bulk data import This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). This page shows you how to integrate Pinecone with a Google Cloud Storage (GCS) bucket. Once your integration is set up, you can use it to [import data](/guides/index-data/import-data) from your bucket into a Pinecone index hosted on AWS, GCP, or Azure. ## Before you begin Ensure you have the following: * A [Pinecone account](https://app.pinecone.io/) * A [Google Cloud Storage bucket](https://cloud.google.com/storage/docs/creating-buckets) ## 1. Create a service account and key Pinecone will use a service account to access your GCS bucket. 1. [Create a service account](https://cloud.google.com/iam/docs/service-accounts-create) for your Pinecone integration. 2. [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating). Select **JSON** as the key type. The key will be downloaded to your computer. You'll use this key when adding a storage integration in Pinecone. ## 2. Grant access to the bucket [Add your service account as a principal to the bucket](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add). * For the principal, use your service account email address. * For the role, select **Storage Object Viewer** or another role that has permission to list and read objects in a bucket. ## 3. Add a storage integration In the [Pinecone console](https://app.pinecone.io/organizations/-/projects), add an integration with Google Cloud Storage: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. Click **Add integration**. 4. Enter a unique integration name. 5. Select **Google Cloud Storage**. 6. Open the JSON key file for your service account. 7. Copy the contents of the key file and paste them into the **Index account key JSON** field. 8. Click **Add integration**. ## Next steps [Import data](/guides/index-data/import-data) from your GCS bucket into your Pinecone index. # Manage storage integrations Source: https://docs.pinecone.io/guides/operations/integrations/manage-storage-integrations Update and manage cloud storage integrations. 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 manage storage integrations for your Pinecone project. To set up cloud storage for integration with Pinecone, see the following guides: * [Integrate with Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3) * [Integrate with Google Cloud Storage](/guides/operations/integrations/integrate-with-google-cloud-storage) * [Integrate with Azure Blob Storage](/guides/operations/integrations/integrate-with-azure-blob-storage) ## Update an integration To update information for a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. For the integration you want to update, click the *...* (Actions) icon. 4. Click **Manage**. 5. Update the integration details as needed. 6. Click **Add integration**. ## Delete an integration To delete a storage integration through the [Pinecone console](https://app.pinecone.io/organizations/-/projects), take the following steps: 1. Select your project. 2. Go to [**Manage > Storage integrations**](https://app.pinecone.io/organizations/-/projects/-/storage). 3. For the integration you want to update, click the *...* (Actions) icon. 4. Click **Delete**. 5. Enter the integration name. 6. Click **Confirm deletion**. # Local development with Pinecone Local Source: https://docs.pinecone.io/guides/operations/local-development Develop locally with an in-memory Pinecone emulator. Pinecone Local is an in-memory Pinecone emulator available as a Docker image. This page shows you how to use Pinecone Local to develop your applications locally without connecting to your Pinecone account or incurring usage or storage fees. Pinecone Local is not suitable for production. See [Limitations](#limitations) for details. This feature is in [public preview](/release-notes/feature-availability). ## Limitations Pinecone Local has the following limitations: * Pinecone Local uses the `2025-01` API version, which is not the latest stable version. * Pinecone Local is available in Docker only. * Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped. * Pinecone Local does not authenticate client requests. API keys are ignored. * Max number of records per index: 100,000. Pinecone Local does not currently support the following features: * [Import from object storage](/guides/index-data/import-data) * [Backup/restore of serverless indexes](/guides/manage-data/backups-overview) * [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections) * [Namespace management](/guides/manage-data/manage-namespaces) * [Pinecone Inference](/reference/api/introduction#inference) * [Pinecone Assistant](/guides/assistant/overview) ## 1. Start Pinecone Local You can configure Pinecone Local as an index emulator or database emulator: * **Index emulator** - This approach uses the `pinecone-index` Docker image to create and configure indexes on startup. This is recommended when you want to quickly experiment with reading and writing data without needing to manage the index lifecycle. With index emulation, you can only read and write data to the indexes created at startup. You cannot create new indexes, list indexes, or run other operations that do not involve reading and writing data. * **Database emulator** - This approach uses the `pinecone-local` Docker image to emulate Pinecone Database more broadly. This is recommended when you want to test your production app or manually create and manage indexes. ### Index emulator Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Create a `docker-compose.yaml` file that defines a service for each index that Pinecone Local should create on startup. In this file, include the `pinecone-index` Docker image, a localhost port for the index to use, and other details: ```yaml theme={null} services: dense-index: image: ghcr.io/pinecone-io/pinecone-index:latest container_name: dense-index environment: PORT: 5081 INDEX_TYPE: serverless VECTOR_TYPE: dense DIMENSION: 2 METRIC: cosine ports: - "5081:5081" platform: linux/amd64 sparse-index: image: ghcr.io/pinecone-io/pinecone-index:latest container_name: sparse-index environment: PORT: 5082 INDEX_TYPE: serverless VECTOR_TYPE: sparse DIMENSION: 0 METRIC: dotproduct ports: - "5082:5082" platform: linux/amd64 ``` For each index, update the environment variables as needed: * `PORT`: Specify the port number for the index to listen on. * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`. * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`. Sparse is supported only with serverless indexes. * `DIMENSION`: Specify the dimension of vectors you will store in the index. For sparse indexes, this must be set to `0`. * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values for dense indexes: `cosine`, `euclidean`, or `dotproduct`. Accepted value for sparse indexes: `dotproduct`. To start Pinecone Local, run the following command: ```shell theme={null} docker compose up -d ``` You'll see a message with details about each index. Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Download the latest `pinecone-index` Docker image: ```shell theme={null} docker pull ghcr.io/pinecone-io/pinecone-index:latest ``` Start Pinecone Local with one or more indexes: ```shell theme={null} docker run -d \ --name dense-index \ -e PORT=5081 \ -e INDEX_TYPE=serverless \ -e VECTOR_TYPE=dense \ -e DIMENSION=2 \ -e METRIC=cosine \ -p 5081:5081 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-index:latest ``` ```shell theme={null} docker run -d \ --name sparse-index \ -e PORT=5082 \ -e INDEX_TYPE=serverless \ -e VECTOR_TYPE=sparse \ -e DIMENSION=0 \ -e METRIC=dotproduct \ -p 5082:5082 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-index:latest ``` For each index, update the environment variables as needed: * `PORT`: Specify the port number for the index to listen on. * `INDEX_TYPE`: Specify the type of Pinecone index to create. Accepted values: `serverless` or `pod`. * `VECTOR_TYPE`: Specify the [type of vectors](/guides/index-data/indexing-overview#indexes) you will store in the index. Accepted values: `dense` or `sparse`. Sparse is supported only with serverless indexes. * `DIMENSION`: Specify the dimension of vectors you will store in the index. For sparse indexes, this must be set to `0`. * `METRIC`: Specify the [distance metric](/guides/index-data/indexing-overview#distance-metrics) for calculating the similarity between vectors in the index. Accepted values for dense indexes: `cosine`, `euclidean`, or `dotproduct`. Accepted value for sparse indexes: `dotproduct`. ### Database emulator Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Create a `docker-compose.yaml` file that defines a service for Pinecone local, including the `pinecone-local` Docker image, the host and port that Pinecone Local will run on and the range of ports that will be available for indexes: ```yaml theme={null} services: pinecone: image: ghcr.io/pinecone-io/pinecone-local:latest environment: PORT: 5080 PINECONE_HOST: localhost ports: - "5080-5090:5080-5090" platform: linux/amd64 ``` To start Pinecone Local, run the following command: ```shell theme={null} docker compose up -d ``` You'll see a message with details about the Pinecone Local instance. Make sure [Docker](https://docs.docker.com/get-docker/) is installed and running on your local machine. Download the latest `pinecone-local` Docker image: ```shell theme={null} docker pull ghcr.io/pinecone-io/pinecone-local:latest ``` Start Pinecone Local: ```shell theme={null} docker run -d \ --name pinecone-local \ -e PORT=5080 \ -e PINECONE_HOST=localhost \ -p 5080-5090:5080-5090 \ --platform linux/amd64 \ ghcr.io/pinecone-io/pinecone-local:latest ``` This command defines the host and port that Pinecone Local will run on, as well as the range of ports that will be available for indexes. ## 2. Develop your app Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences: * Pinecone Local does not authenticate client requests. API keys are ignored. * The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/python-sdk) `v6.x` or later, [Node.js SDK](/reference/node-sdk) `v5.x` or later, [Java SDK](/reference/java-sdk) `v4.x` or later, [Go SDK](/reference/go-sdk) `v3.x` or later, and [.NET SDK](/reference/dotnet-sdk) `v3.x` or later. Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing. **Example** The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates a [dense index](/guides/index-data/indexing-overview#dense-indexes) and a [sparse index](/guides/index-data/indexing-overview#sparse-indexes), upserts records into the indexes, checks their record counts, and queries the indexes. ```python Python theme={null} from pinecone.grpc import PineconeGRPC, GRPCClientConfig from pinecone import ServerlessSpec # Initialize a client. # API key is required, but the value does not matter. # Host and port of the Pinecone Local instance # is required when starting without indexes. pc = PineconeGRPC( api_key="pclocal", host="http://localhost:5080" ) # Create two indexes, one dense and one sparse dense_index_name = "dense-index" sparse_index_name = "sparse-index" if not pc.has_index(dense_index_name): dense_index_model = pc.create_index( name=dense_index_name, vector_type="dense", dimension=2, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("Dense index model:\n", dense_index_model) if not pc.has_index(sparse_index_name): sparse_index_model = pc.create_index( name=sparse_index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("\nSparse index model:\n", sparse_index_model) # Target each index, disabling tls dense_index_host = pc.describe_index(name=dense_index_name).host dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False)) sparse_index_host = pc.describe_index(name=sparse_index_name).host sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False)) # Upsert records into the dense index dense_index.upsert( vectors=[ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ], namespace="example-namespace" ) # Upsert records into the sparse index sparse_index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] ) # Check the number of records in each index print("\nDense index stats:\n", dense_index.describe_index_stats()) print("\nSparse index stats:\n", sparse_index.describe_index_stats()) # Query the dense index with a metadata filter dense_response = dense_index.query( namespace="example-namespace", vector=[3.0, -2.0], filter={"genre": {"$eq": "documentary"}}, top_k=1, include_values=False, include_metadata=True ) print("\nDense query response:\n", dense_response) # Query the sparse index with a metadata filter sparse_response = sparse_index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, filter={ "quarter": {"$eq": "Q4"} }, top_k=1, include_values=False, include_metadata=True ) print("/nSparse query response:\n", sparse_response) # Delete the indexes pc.delete_index(name=dense_index_name) pc.delete_index(name=sparse_index_name) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a client. // API key is required, but the value does not matter. // Host and port of the Pinecone Local instance // is required when starting without indexes. const pc = new Pinecone({ apiKey: 'pclocal', controllerHostUrl: 'http://localhost:5080' }); // Create two indexes, one dense and one sparse const denseIndexName = 'dense-index'; const sparseIndexName = 'sparse-index'; const denseIndexModel = await pc.createIndex({ name: denseIndexName, vectorType: 'dense', dimension: 2, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('Dense index model:', denseIndexModel); const sparseIndexModel = await pc.createIndex({ name: sparseIndexName, vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('\nSparse index model:', sparseIndexModel); // Target each index const denseIndexHost = (await pc.describeIndex(denseIndexName)).host; const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost); const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host; const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost); // Upsert records into the dense index await denseIndex.namespace('example-namespace').upsert([ { id: 'vec1', values: [1.0, -2.5], metadata: { genre: 'drama' }, }, { id: 'vec2', values: [3.0, -2.0], metadata: { genre: 'documentary' }, }, { id: 'vec3', values: [0.5, -1.5], metadata: { genre: 'documentary' }, } ]); // Upsert records into the sparse index await sparseIndex.namespace('example-namespace').upsert([ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } } ]); // Check the number of records in each index console.log('\nDense index stats:', await denseIndex.describeIndexStats()); console.log('\nSparse index stats:', await sparseIndex.describeIndexStats()); // Query the dense index with a metadata filter const denseQueryResponse = await denseIndex.namespace('example-namespace').query({ vector: [3.0, -2.0], filter: { 'genre': {'$eq': 'documentary'} }, topK: 1, includeValues: false, includeMetadata: true, }); console.log('\nDense query response:', denseQueryResponse); const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 1, includeValues: false, includeMetadata: true }); console.log('\nSparse query response:', sparseQueryResponse); // Delete the index await pc.deleteIndex(denseIndexName); await pc.deleteIndex(sparseIndexName); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.DescribeIndexStatsResponse; import org.openapitools.db_control.client.model.DeletionProtection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.*; public class PineconeLocalExample { public static void main(String[] args) { // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. String host = "http://localhost:5080"; Pinecone pc = new Pinecone.Builder("pclocal") .withHost(host) .withTlsEnabled(false) .build(); // Create two indexes, one dense and one sparse String denseIndexName = "dense-index"; String sparseIndexName = "sparse-index"; HashMap tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( denseIndexName, "cosine", 2, "aws", "us-east-1", DeletionProtection.DISABLED, tags ); pc.createSparseServelessIndex( sparseIndexName, "aws", "us-east-1", DeletionProtection.DISABLED, tags, "sparse" ); // Get index connection objects Index denseIndexConnection = pc.getIndexConnection(denseIndexName); Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName); // Upsert records into the dense index Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f), null, null, metaData1, "example-namespace"); denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f), null, null, metaData2, "example-namespace"); denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f), null, null, metaData3, "example-namespace"); // Upsert records into the sparse index ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct sparseMetaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct sparseMetaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct sparseMetaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace"); sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace"); sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace"); // Check the number of records each the index DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null); System.out.println("Dense index stats:"); System.out.println(denseIndexStatsResponse); DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null); System.out.println("Sparse index stats:"); System.out.println(sparseIndexStatsResponse); // Query the dense index with a metadata filter List queryVector = Arrays.asList(1.0f, 1.5f); QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true); System.out.println("Dense query response:"); System.out.println(denseQueryResponse); // Query the sparse index with a metadata filter List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println("Sparse query response:"); System.out.println(sparseQueryResponse); // Delete the indexes pc.deleteIndex(denseIndexName); pc.deleteIndex(sparseIndexName); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a client. // No API key is required. // Host and port of the Pinecone Local instance // is required when starting without indexes. pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{ Host: "http://localhost:5080", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Create two indexes, one dense and one sparse denseIndexName := "dense-index" denseVectorType := "dense" dimension := int32(2) denseMetric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: denseIndexName, VectorType: &denseVectorType, Dimension: &dimension, Metric: &denseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", denseIdx.Name) } else { fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name) } sparseIndexName := "sparse-index" sparseVectorType := "sparse" sparseMetric := pinecone.Dotproduct sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: sparseIndexName, VectorType: &sparseVectorType, Metric: &sparseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name) } else { fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name) } // Get the index hosts denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err) } sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err) } // Target the indexes. // Make sure to prefix the hosts with http:// to let the SDK know to disable tls. denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into the dense index denseMetadataMap1 := map[string]interface{}{ "genre": "drama", } denseMetadata1, err := structpb.NewStruct(denseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap2 := map[string]interface{}{ "genre": "documentary", } denseMetadata2, err := structpb.NewStruct(denseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap3 := map[string]interface{}{ "genre": "documentary", } denseMetadata3, err := structpb.NewStruct(denseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseVectors := []*pinecone.Vector{ { Id: "vec1", Values: &[]float32{1.0, -2.5}, Metadata: denseMetadata1, }, { Id: "vec2", Values: &[]float32{3.0, -2.0}, Metadata: denseMetadata2, }, { Id: "vec3", Values: &[]float32{0.5, -1.5}, Metadata: denseMetadata3, }, } denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount) } // Upsert records into the sparse index sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } sparseMetadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } sparseMetadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } sparseMetadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseVectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: sparseMetadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: sparseMetadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: sparseMetadata3, }, } sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount) } // Check the number of records in each index denseStats, err := denseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nDense index stats: %+v\n", prettifyStruct(*denseStats)) } sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nSparse index stats: %+v\n", prettifyStruct(*sparseStats)) } // Query the dense index with a metadata filter queryVector := []float32{3.0, -2.0} queryMetadataMap := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } metadataFilter, err := structpb.NewStruct(queryMetadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 1, MetadataFilter: metadataFilter, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes)) } // Query the sparse index with a metadata filter sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 1, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes)) } // Delete the indexes err = pc.DeleteIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName) } err = pc.DeleteIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName) } } ``` ```csharp C# theme={null} using Pinecone; // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. var pc = new PineconeClient("pclocal", new ClientOptions { BaseUrl = "http://localhost:5080", IsTlsEnabled = false } ); // Create two indexes, one dense and one sparse var denseIndexName = "dense-index"; var sparseIndexName = "sparse-index"; var createDenseIndexRequest = await pc.CreateIndexAsync(new CreateIndexRequest { Name = denseIndexName, VectorType = VectorType.Dense, Dimension = 2, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } }); Console.WriteLine("Dense index model:" + createDenseIndexRequest); var createSparseIndexRequest = await pc.CreateIndexAsync(new CreateIndexRequest { Name = sparseIndexName, VectorType = VectorType.Sparse, Metric = MetricType.Dotproduct, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } }); Console.WriteLine("\nSparse index model:" + createSparseIndexRequest); // Target the indexes var denseIndex = pc.Index(denseIndexName); var sparseIndex = pc.Index(sparseIndexName); // Upsert records into the dense index var denseUpsertResponse = await denseIndex.UpsertAsync(new UpsertRequest() { Namespace = "example-namespace", Vectors = new List { new Vector { Id = "vec1", Values = new ReadOnlyMemory([1.0f, -2.5f]), Metadata = new Metadata { ["genre"] = new("drama"), }, }, new Vector { Id = "vec2", Values = new ReadOnlyMemory([3.0f, -2.0f]), Metadata = new Metadata { ["genre"] = new("documentary"), }, }, new Vector { Id = "vec3", Values = new ReadOnlyMemory([0.5f, -1.5f]), Metadata = new Metadata { ["genre"] = new("documentary"), } } } }); Console.WriteLine($"\nUpserted {denseUpsertResponse.UpsertedCount} dense vectors"); // Upsert records into the sparse index var sparseVector1 = new Vector { Id = "vec1", SparseValues = new SparseValues { Indices = new uint[] { 822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var sparseVector2 = new Vector { Id = "vec2", SparseValues = new SparseValues { Indices = new uint[] { 131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."), ["category"] = new("technology"), ["quarter"] = new("Q4"), }, }; var sparseVector3 = new Vector { Id = "vec3", SparseValues = new SparseValues { Indices = new uint[] { 8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var sparseUpsertResponse = await sparseIndex.UpsertAsync(new UpsertRequest { Vectors = new List { sparseVector1, sparseVector2, sparseVector3 }, Namespace = "example-namespace" }); Console.WriteLine($"\nUpserted {sparseUpsertResponse.UpsertedCount} sparse vectors"); // Check the number of records in each index var denseIndexStatsResponse = await denseIndex.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine("\nDense index stats:" + denseIndexStatsResponse); var sparseIndexStatsResponse = await sparseIndex.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine("\nSparse index stats:" + sparseIndexStatsResponse); // Query the dense index with a metadata filter var denseQueryResponse = await denseIndex.QueryAsync(new QueryRequest { Vector = new ReadOnlyMemory([3.0f, -2.0f]), TopK = 1, Namespace = "example-namespace", Filter = new Metadata { ["genre"] = new Metadata { ["$eq"] = "documentary", } }, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine("\nDense query response:" + denseQueryResponse); // Query the sparse index with a metadata filter var sparseQueryResponse = await sparseIndex.QueryAsync(new QueryRequest { Namespace = "example-namespace", TopK = 1, SparseVector = new SparseValues { Indices = [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], Values = new[] { 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f }, }, Filter = new Metadata { ["quarter"] = new Metadata { ["$eq"] = "Q4", } }, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine("\nSparse query response:" + sparseQueryResponse); // Delete the indexes await pc.DeleteIndexAsync(denseIndexName); await pc.DeleteIndexAsync(sparseIndexName); ``` ```shell curl theme={null} PINECONE_LOCAL_HOST="localhost:5080" DENSE_INDEX_HOST="localhost:5081" SPARSE_INDEX_HOST="localhost:5082" # Create two indexes, one dense and one sparse curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "dense-index", "vector_type": "dense", "dimension": 2, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "sparse-index", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' # Upsert records into the dense index curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ] }' # Upsert records into the sparse index curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] }' # Check the number of records in each index curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' # Query the dense index with a metadata filter curl "http://$DENSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [3.0, -2.0], "filter": {"genre": {"$eq": "documentary"}}, "topK": 1, "includeMetadata": true, "includeValues": false, "namespace": "example-namespace" }' # Query the sparse index with a metadata filter curl "http://$SPARSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "filter": {"quarter": {"$eq": "Q4"}}, "namespace": "example-namespace", "topK": 1, "includeMetadata": true, "includeValues": false }' # Delete the index curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \ -H "X-Pinecone-Api-Version: 2025-10" curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 3. Stop Pinecone Local Pinecone Local is an in-memory emulator. Records loaded into Pinecone Local do not persist after Pinecone Local is stopped. To stop and remove the resources for Pinecone Local, run the following command: ```shell Docker Compose theme={null} docker compose down ``` ```shell Docker CLI theme={null} # If you started Pinecone Local with indexes: docker stop dense-index sparse-index docker rm dense-index sparse-index # If you started Pinecone Local without indexes: docker stop pinecone-local docker rm pinecone-local ``` ## Moving from Pinecone Local to your Pinecone account When you're ready to run your application against your Pinecone account, be sure to do the following: * Update your application to [use your Pinecone API key](/reference/api/authentication). * Update your application to [target your Pinecone indexes](/guides/manage-data/target-an-index). * [Use Pinecone's import feature](/guides/index-data/import-data) to efficiently load large amounts of data into your indexes and then [use batch upserts](/guides/index-data/upsert-data#upsert-in-batches) for ongoing writes. * Follow Pinecone's [production best practices](/guides/production/production-checklist). # Use the Pinecone MCP server Source: https://docs.pinecone.io/guides/operations/mcp-server Use Pinecone MCP server for AI agent integration. This feature is in [early access](/release-notes/feature-availability) and is not intended for production usage. 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 [Cursor](https://www.cursor.com/) and [Claude Desktop](https://claude.ai/download) to connect with the Pinecone MCP server. ## Tools The Pinecone MCP server provides the following tools: * `search-docs`: Search the official Pinecone documentation. * `list-indexes`: Lists all Pinecone indexes. * `describe-index`: Describes the configuration of an index. * `describe-index-stats`: Provides statistics about the data in the index, including the number of records and available namespaces. * `create-index-for-model`: Creates a new index that uses an integrated inference model to embed text as vectors. * `upsert-records`: Inserts or updates records in an index with integrated inference. * `search-records`: Searches for records in an index based on a text query, using integrated inference for embedding. Has options for metadata filtering and reranking. * `cascading-search`: Searches for records across multiple indexes, deduplicating and reranking the results. * `rerank-documents`: Reranks a collection of records or text documents using a specialized reranking model. The Pinecone MCP supports only [indexes with integrated embedding](/guides/index-data/indexing-overview#vector-embedding). Indexes for vectors you create with external embedding models are not supported. ## Before you begin Ensure you have the following: * A [Pinecone API key](https://app.pinecone.io/organizations/-/keys) * [Node.js](https://nodejs.org/en) installed, with `node` and `npx` available on your `PATH` ## Configure Cursor 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" } } } } ``` Replace `YOUR_API_KEY` with your Pinecone API key. Go to **Cursor Settings > MCP**. You should see the server and its list of tools. The Pinecone MCP server works well out-of-the-box. However, you can add explicit rules to ensure the server behaves as expected. In your project root, create a `.cursor/rules/pinecone.mdc` file and add the following: ```mdx [expandable] theme={null} ### Tool Usage for Code Generation - When generating code related to Pinecone, always use the `pinecone` MCP and the `search_docs` tool. - Perform at least two distinct searches per request using different, relevant questions to ensure comprehensive context is gathered before writing code. ### Error Handling - If an error occurs while executing Pinecone-related code, immediately invoke the `pinecone` MCP and the `search_docs` tool. - Search for guidance on the specific error encountered and incorporate any relevant findings into your resolution strategy. ### Syntax and Version Accuracy - Before writing any code, verify and use the correct syntax for the latest stable version of the Pinecone SDK. - Prefer official code snippets and examples from documentation over generated or assumed field values. - Do not fabricate field names, parameter values, or request formats. ### SDK Installation Best Practices - When providing installation instructions, always reference the current official package name. - For Pinecone, use `pip install pinecone` not deprecated packages like `pinecone-client`. ``` Press `Command + i` to open the Agent chat. Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates a dense index with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create a dense index with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. ## Configure Claude Desktop Go to **Settings > Developer > Edit Config** and add the following configuration: ```json theme={null} { "mcpServers": { "pinecone": { "command": "npx", "args": [ "-y", "@pinecone-database/mcp" ], "env": { "PINECONE_API_KEY": "YOUR_API_KEY" } } } } ``` Replace `YOUR_API_KEY` with your Pinecone API key. Restart Claude Desktop. On the new chat screen, you should see a hammer (MCP) icon appear with the new MCP tools available. Test the Pinecone MCP server with prompts that required the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates a dense index with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create a dense index with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. ## Configure Claude Code 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"}}' ``` Replace `YOUR_API_KEY` with your Pinecone API key. Restart Claude Code. Then, run the `/mcp` command to check the status of the Pinecone MCP. You should see the following: ```bash theme={null} > /mcp ⎿ MCP Server Status • pinecone-mcp: ✓ connected ``` Test the Pinecone MCP server with prompts to Claude Code that require the server to generate Pinceone-compatible code and perform tasks in your Pinecone account. Generate code: > Write a Python script that creates a dense index with integrated embedding, upserts 20 sentences about dogs, waits 10 seconds, searches the index, and reranks the results. Perform tasks: > Create a dense index with integrated embedding, upsert 20 sentences about dogs, waits 10 seconds, search the index, and reranks the results. # Decrease latency Source: https://docs.pinecone.io/guides/optimize/decrease-latency Learn techniques to decrease latency for search and upsert operations. ## Use namespaces When you divide records into [namespaces](/guides/index-data/indexing-overview#namespaces) in a logical way, you speed up queries by ensuring only relevant records are scanned. The same applies to [fetching records](/guides/manage-data/fetch-data), [listing record IDs](/guides/manage-data/list-record-ids), and other data operations. ## Filter by metadata In addition to increasing search accuracy and relevance, [searching with metadata filters](/guides/search/filter-by-metadata) can also help decrease latency by retrieving only records that match the filter. ## Target indexes by host When you target an index by name for data operations such as `upsert` and `query`, the SDK gets the unique DNS host for the index using the `describe_index` operation. This is convenient for testing but should be avoided in production because `describe_index` uses a different API than data operations and therefore adds an additional network call and point of failure. Instead, you should get an index host once and cache it for reuse or specify the host directly. You can get index hosts in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes) or using the [`describe_index`](/guides/manage-data/manage-indexes#describe-an-index) operation. The following example shows how to target an index by host directly: When using Private Endpoints for private connectivity between your application and Pinecone, you must target the index using the [Private Endpoint URL](/guides/production/connect-to-aws-privatelink#run-data-plane-commands) for the host. ```Python Python {5} theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index(host="INDEX_HOST") ``` ```javascript JavaScript {6} theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // For the Node.js SDK, you must specify both the index host and name. const index = pc.index("INDEX_NAME", "INDEX_HOST"); ``` ```java Java {11} theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; public class TargetIndexByHostExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); // For the Java SDK, you must specify both the index host and name. Index index = new Index(connection, "INDEX_NAME"); } } ``` ```go Go {21} theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host %v: %v", idx.Host, err) } } ``` ```csharp C# {5} theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index(host: "INDEX_HOST"); ``` ## Reuse connections When you target an index for upserting or querying, the client establishes a TCP connection, which is a three-step process. To avoid going through this process on every request, and reduce average request latency, [cache and reuse the index connection object](/reference/api/authentication#initialize-a-client) whenever possible. ## Use a cloud environment If you experience slow uploads or high query latencies, it might be because you are accessing Pinecone from your home network. To decrease latency, access Pinecone/deploy your application from a cloud environment instead, ideally from the same [cloud and region](/guides/index-data/create-an-index#cloud-regions) as your index. ## Work with database limits Pinecone has [rate limits](/reference/api/database-limits#rate-limits) to protect your applications and maintain infrastructure health. Rate limits vary based on pricing plan and apply to serverless indexes only. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. To handle rate limits effectively: * [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429). * If you need higher limits for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Most limits can be adjusted to accommodate your scaling needs. # Increase search relevance Source: https://docs.pinecone.io/guides/optimize/increase-relevance Learn techniques to improve search result quality. This page describes helpful techniques for improving search accuracy and relevance. ## Rerank results [Reranking](/guides/search/rerank-results) is used as part of a two-stage vector retrieval process to improve the quality of results. You first query an index for a given number of relevant results, and then you send the query and results to a reranking model. The reranking model scores the results based on their semantic relevance to the query and returns a new, more accurate ranking. This approach is one of the simplest methods for improving quality in retrieval augmented generation (RAG) pipelines. Pinecone provides [hosted reranking models](/guides/search/rerank-results#reranking-models) so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. ## Filter by metadata Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector, depending on the [type of index](/guides/index-data/indexing-overview#indexes). In addition, you can include metadata key-value pairs to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching a filter expression. For example, if an index contains records about books, you could use a metadata field to associate each record with a genre, like `"genre": "fiction"` or `"genre": "poetry"`. When you query the index, you could then use a metadata filter to limit your search to records related to a specific genre. For more details, see [Filter by metadata](/guides/search/filter-by-metadata). ## Use hybrid search [Semantic search](/guides/search/semantic-search) and [lexical search](/guides/search/lexical-search) are powerful information retrieval techniques, but each has notable limitations. For example, semantic search can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology, while lexical search can miss results based on relationships, such as synonyms and paraphrases. To lift these limitations, you can search both dense and sparse indexes, combine the results from both, and use one of Pinecone’s hosted reranking models to assign a unified relevance score, reorder the result accordingly, and return the most relevant matches. This is often called hybrid search or cascading retrieval. For more details, 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 Learn techniques to improve data operation performance and query throughput. ## Import from object storage [Importing from object storage](/guides/index-data/import-data) is the most efficient and cost-effective method to load large numbers of records into an index. You store your data as Parquet files in object storage, integrate your object storage with Pinecone, and then start an asynchronous, long-running operation that imports and indexes your records. ## Upsert in batches [Upserting in batches](/guides/index-data/upsert-data#upsert-in-batches) is another efficient way to ingest large numbers of records (up to 1000 per batch). Batch upserting is also a good option if you cannot work around bulk import's current [limitations](/guides/index-data/import-data#import-limits). ## Upsert/search in parallel Pinecone is thread-safe, so you can send multiple [upsert](/guides/index-data/upsert-data#upsert-in-parallel) requests and multiple [query](/guides/search/semantic-search#parallel-queries) requests in parallel to help increase throughput. ## Python SDK options ### Use gRPC Use the [Python SDK with gRPC extras](/reference/python-sdk) to run data operations such as upserts and queries over [gRPC](https://grpc.io/) rather than HTTP for a modest performance improvement. ### Upsert from a dataframe To quickly ingest data when using the Python SDK, use the [`upsert_from_dataframe` method](/reference/python-sdk#upsert-from-a-dataframe). The method includes retry logic and `batch_size`, and is performant especially with Parquet file data sets. ## See also Read more about [high-throughput optimizations](https://www.pinecone.io/blog/working-at-scale/) on our blog. # Access your invoices Source: https://docs.pinecone.io/guides/organizations/manage-billing/access-your-invoices View and download organization billing invoices. You can access your billing history and invoices in the Pinecone console: 1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 2. Scroll down to the **Payment history and invoices** section. 3. For each billing period, you can download the invoice by clicking the **Download** button. Each invoice includes line items for the services used during the billing period. If the total cost of that usage is below the monthly minimum, the invoice also includes a line item covering the rest of the minimum usage commitment. # Change your payment method Source: https://docs.pinecone.io/guides/organizations/manage-billing/change-payment-method Update your billing payment method. You can pay for the [Standard and Enterprise plans](https://www.pinecone.io/pricing/) with a credit/debit card or through the AWS Marketplace, Microsoft Marketplace, or Google Cloud Marketplace. This page describes how to switch between these payment methods. To change your payment method, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). ## Credit card → marketplace To change from credit card to marketplace billing, you'll need to: 1. Create a new Pinecone organization through the marketplace 2. Migrate your existing projects to the new Pinecone organization 3. Add your team members to the new Pinecone organization 4. Downgrade your original Pinecone organization once migration is complete To change from paying with a credit card to paying through the Google Cloud Marketplace, do the following: 1. Subscribe to Pinecone in the Google Cloud Marketplace: 1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone). 2. Click **Subscribe**. 3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone sign-up page. 5. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your Google Cloud Marketplace account: 1. On the **Connect GCP to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. Enter the name of the new organization and click **Connect to Pinecone**. 3. On the **Confirm GCP marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Google Cloud Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying with a credit card to paying through the AWS Marketplace, do the following: 1. Subscribe to Pinecone in the AWS Marketplace: 1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk). 2. Click **View purchase options**. 3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone sign-up page. 5. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your AWS account: 1. On the **Connect AWS to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 1. Enter the name of the new organization and click **Connect to Pinecone**. 2. On the **Confirm AWS Marketplace Connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Google Cloud Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the AWS Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying with a credit card to paying through the Microsoft Marketplace, do the following: 1. Subscribe to Pinecone in the Microsoft Marketplace: 1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas). 2. Click **Get it now**. 3. Select the **Pinecone - Pay As You Go** plan. 4. Click **Subscribe**. 5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. Click **Subscribe**. 7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 8. Sign up using the same authentication method as your existing Pinecone organization. 2. Create a new Pinecone organization and connect it to your Microsoft Marketplace account: 1. On the **Connect Azure to Pinecone** page, choose **Select an organization > + Create New Organization**. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 1. Enter the name of the new organization and click **Connect to Pinecone**. 2. On the **Connect Azure marketplace connection** modal, click **Connect**. This takes you to your new organization in the Pinecone console. 3. Migrate your projects to the new Pinecone organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. Make sure the **Owner** email address for your original organization is set as an **Owner** or **Billing Admin** for your new organization. This allows Pinecone to verify that both the original and new organizations are owned by the same person. 3. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 4. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 5. For **Ticket category**, select **Project or Organization Management**. 6. For **Subject**, enter "Migrate projects to a new organization". 7. For **Description**, enter the following: ``` I am changing my payment method from credit card to Microsoft Marketplace. Please migrate my projects to my new organization: `` ``` 8. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to **Settings > Billing > Plans**. 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. ## Marketplace → credit card To change from marketplace billing to credit card, you'll need to: 1. Create a new organization in your Pinecone account 2. Upgrade the new organization to the Standard or Enterprise plan 3. Migrate your existing projects to the new organization 4. Add your team members to the new organization 5. Downgrade your original organization once migration is complete To change from paying through the Google Cloud Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from Google Cloud Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace. 6. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your original organization. If you don't see the order, check that the correct billing account is selected. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying through the AWS Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from AWS Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 6. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. To change from paying through the Microsoft Marketplace to paying with a credit card, do the following: 1. Create a new organization in your Pinecone account: 1. In the Pinecone console, go to [**Organizations**](https://app.pinecone.io/organizations/-/settings/account/organizations). 2. Click **+ Create organization**. 3. Enter the name of the new organization and click **Create**. 2. Upgrade the new organization: 1. Go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. The new organization is now set up with credit card billing. You'll use this organization after completing the rest of this process. 3. Migrate your projects to the new Pinecone organization: 1. Go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage) and copy your new organization ID. 2. Go to [**Settings > Support > Tickets**](https://app.pinecone.io/organizations/-/settings/support/ticket/create). 3. For **Ticket category**, select **Project or Organization Management**. 4. For **Subject**, enter "Migrate projects to a new organization". 5. For **Description**, enter the following: ``` I am changing my payment method from Microsoft Marketplace to credit card. Please migrate my projects to my new organization: `` ``` 6. Click **Submit**. 4. Add your team members to the new organization: 1. In the Pinecone console, go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. [Add your team members to the new organization](/guides/organizations/manage-organization-members#add-a-member-to-an-organization). 5. Downgrade your original Pinecone organization: Do not downgrade your original organization until you receive a confirmation that Pinecone has finished the migration to your new organization. 1. In the Pinecone console, go to your original organization. 2. Go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 3. In the **Starter** section, click **Downgrade**. 4. Click **Confirm downgrade**. 5. On the **Continue your downgrade on Azure marketplace** modal, click **Continue to marketplace**. 6. On the **SaaS** page, click your subscription to Pinecone. 7. Click **Cancel subscription**. 8. Confirm the cancellation. Going forward, you'll use your new organization and your usage will be billed through the credit card you provided. You can [delete your original organization](/troubleshooting/delete-your-organization). However, before deleting, make sure to [download your past invoices](/guides/organizations/manage-billing/access-your-invoices) since you will lose access to them once the organization is deleted. ## Marketplace → marketplace To change from one marketplace to another, you'll need to: 1. Subscribe to Pinecone in the new marketplace 2. Connect your existing org to the new marketplace 3. Cancel your subscription in the old marketplace To change to a Google Cloud Marketplace billing account, do the following: 1. Subscribe to Pinecone in the Google Cloud Marketplace: 1. In the Google Cloud Marketplace, go to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone). 2. Click **Subscribe**. 3. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page. 5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your Google account: 1. On the **Connect GCP to Pinecone** page, select the Pinecone organization that you want to use Google Cloud Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm GCP marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the Google Cloud Marketplace. 3. Cancel your subscription in your previous marketplace: * For AWS: 1. In the AWS Marketplace, go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. * For Microsoft: 1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources). 2. Select your subscription to Pinecone. 3. Click **Cancel subscription**. 4. Confirm the cancellation. To change to an AWS Marketplace billing account, do the following: 1. Subscribe to Pinecone in the AWS Marketplace: 1. In the AWS Marketplace, go to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace. 2. Click **View purchase options**. 3. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 4. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page. 5. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your AWS account: 1. On the **Connect AWS to Pinecone** page, select the Pinecone organization that you want to change to AWS Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm AWS marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the AWS Marketplace. 3. Cancel your subscription in your previous marketplace: * For Google Cloud Marketplace: 1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page. 2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone. * For Microsoft Marketplace: 1. Go to [Azure SaaS Resource Management](https://portal.azure.com/#blade/HubsExtension/BrowseResourceBlade/resourceType/Microsoft.SaaS%2Fresources). 2. Select your subscription to Pinecone. 3. Click **Cancel subscription**. 4. Confirm the cancellation. To change to a Microsoft Marketplace billing account, do the following: 1. Subscribe to Pinecone in the Microsoft Marketplace: 1. In the Microsoft Marketplace, go to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas). 2. Click **Get it now**. 3. Select the **Pinecone - Pay As You Go** plan. 4. Click **Subscribe**. 5. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. Click **Subscribe**. 7. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 8. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 2. Connect your existing org to your Microsoft account: 1. On the **Connect Azure to Pinecone** page, select the Pinecone organization that you want to change to Microsoft Marketplace. If you see a message saying that the subscription is still in process, wait a few minutes, refresh the page, and proceed only when the message has disappeared. 2. On the **Confirm Azure marketplace connection** modal, click **Connect**. This takes you to your organization in the Pinecone console. Going forward, your usage of Pinecone will be billed through the Microsoft Marketplace. 3. Cancel your subscription in your previous marketplace: * For Google Cloud Marketplace: 1. Go to the [Orders](https://console.cloud.google.com/marketplace/orders) page. 2. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for Pinecone. * For AWS Marketplace: 1. Go to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 2. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. ## Credit card → credit card To update your credit card information in the Pinecone console, do the following: 1. Go to [**Settings > Billing > Overview**](https://app.pinecone.io/organizations/-/settings/billing). 2. In the **Billing Contact** section, click **Edit**. 3. Enter your new credit card information. 4. Click **Update**. # Downgrade your plan Source: https://docs.pinecone.io/guides/organizations/manage-billing/downgrade-billing-plan Downgrade from a paid plan to the free Starter plan. To change your billing plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). ## Requirements Before you can downgrade, your organization must be under the [Starter plan quotas](/reference/api/database-limits): * No more than 5 indexes, all serverless and in the `us-east-1` region of AWS * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index). * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer. * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index). * No more than 1 project * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project). * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project. * No more than 2 GB of data across all of your serverless indexes * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB. * No more than 100 namespaces per serverless index * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining. * No more than 3 [assistants](/guides/assistant/overview) * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer. * No more than 10 files per assistant * If you have more than 10 files uploaded to an assistant, [delete files](/guides/assistant/manage-files#delete-a-file) until the assistant has 10 or fewer. * No more than 1 GB of assistant storage * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB. * No more than 2 users * No collections or backups (these are automatically deleted as part of the downgrade process) ## Downgrade to the Starter plan The downgrade process is different depending on how you are paying for Pinecone. It is important to start the downgrade process in the Pinecone console, as described below. When you do so, Pinecone checks that you are under the [Starter plan quotas](#requirements) before allowing you to downgrade. In contrast, if you start the downgrade process in one of the cloud marketplaces, Pinecone cannot check that you are under these quotas before allowing you to downgrade. If you are over the quotas, Pinecone will deactivate your account, and you will need to [contact support](https://www.pinecone.io/contact/support/). If you are paying with a credit card, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Downgrade** in the **Starter** plan section. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the Google Cloud Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on the GCP marketplace** modal, click **Continue to marketplace**. This takes you to your orders page in Google Cloud Marketplace. 5. [Cancel the order](https://cloud.google.com/marketplace/docs/manage-billing#saas-products) for your Pinecone subscription. If you don't see the order, check that the correct billing account is selected. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the AWS Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on the AWS marketplace** modal, click **Continue to marketplace**. This takes you to the [Manage subscriptions](https://console.aws.amazon.com/marketplace) page in the AWS Marketplace. 5. [Cancel the subscription](https://docs.aws.amazon.com/marketplace/latest/buyerguide/cancel-subscription.html#cancel-saas-subscription) to Pinecone. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. If you are paying through the Microsoft Marketplace, downgrade as follows: 1. In the Pinecone console, go to [**Settings > Billing > Plans**](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. In the **Starter** section, click **Downgrade**. 3. Click **Confirm downgrade**. 4. On the **Continue your downgrade on Microsoft marketplace** modal, click **Continue to marketplace**. 5. On the **SaaS** page, click your subscription to Pinecone. 6. Click **Cancel subscription**. 7. Confirm the cancellation. Your billing will end immediately. However, you will receive a final invoice for any charges accrued in the current month. # Download a usage report Source: https://docs.pinecone.io/guides/organizations/manage-billing/download-usage-report Download detailed usage and cost reports. To view usage and costs across your Pinecone organization, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-owners). Also, this feature is available only to organizations on the Standard or Enterprise plans. The **Usage** dashboard in the Pinecone console gives you a detailed report of usage and costs across your organization, broken down by each billable SKU or aggregated by project or service. You can view the report in the console or download it as a CSV file for more detailed analysis. 1. Go to [**Settings > Usage**](https://app.pinecone.io/organizations/-/settings/usage) in the Pinecone console. 2. Select the time range to report on. This defaults to the last 30 days. 3. Select the scope for your report: * **SKU:** The usage and cost for each billable SKU, for example, read units per cloud region, storage size per cloud region, or tokens per embedding model. * **Project:** The aggregated cost for each project in your organization. * **Service:** The aggregated cost for each service your organization uses, for example, database (includes serverless back up and restore), assistants, inference (embedding and reranking), and collections. 4. Choose the specific SKUs, projects, or services you want to report on. This defaults to all. 5. To download the report as a CSV file, click **Download**. The CSV download provides more granular detail than the console view, including breakdowns by individual index as well as project and index tags. Dates are shown in UTC to match billing invoices. Cost data is delayed up to three days from the actual usage date. # Standard trial Source: https://docs.pinecone.io/guides/organizations/manage-billing/standard-trial Get $300 credits for 21 days with the Standard plan trial. The Standard trial lets you evaluate Pinecone without requiring any up-front payment. You get \$300 in credits over 21 days with access to Standard plan [features](https://www.pinecone.io/pricing/) and [limits](/reference/api/database-limits) that are suitable for testing Pinecone at scale. If you're building a small or personal project, consider the free [Starter plan](https://www.pinecone.io/pricing/) instead. ## Key features * \$300 in credits * 21 days of access to Standard plan [features](https://www.pinecone.io/pricing/), including: * [Bulk import](/guides/index-data/import-data) * [Backup and restore](/guides/manage-data/backups-overview) * [RBAC (role-based access control)](/guides/production/security-overview#role-based-access-control) * [Higher limits](/reference/api/database-limits) for testing at scale * Access to all [cloud regions](/guides/index-data/create-an-index#cloud-regions) * Access to [Developer Support](https://www.pinecone.io/pricing/?plans=support\&scrollTo=product-pricing-modal-section) ## Expiration At the end of a Standard trial, or when you've used all of your credits, you can take one of the following actions: * Add a payment method and continue on with the Standard plan. * Upgrade to the Enterprise plan. * [Downgrade to a Starter plan](#downgrading-to-the-starter-plan) (you can also do this before your trial expires, if you choose). Learn more about [pricing](https://www.pinecone.io/pricing/). ## Downgrading to the Starter plan To downgrade from a Standard trial to the Starter plan, you'll need to bring your usage within Starter plan limits. * No more than 5 indexes, all serverless and in the `us-east-1` region of AWS * If you have serverless indexes in a region other than `us-east-1`, [create a new serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in `us-east-1`, [re-upsert your data](/guides/index-data/upsert-data) into the new index, and [delete the old index](/guides/manage-data/manage-indexes#delete-an-index). * If you have more than 5 serverless indexes, [delete indexes](/guides/manage-data/manage-indexes#delete-an-index) until you have 5 or fewer. * If you have pod-based indexes, [delete them](/guides/manage-data/manage-indexes#delete-an-index). * No more than 1 project * If you have more than 1 project, [delete all but 1 project](/guides/projects/manage-projects#delete-a-project). * Before you can delete a project, you must [delete all indexes](/guides/manage-data/manage-indexes#delete-an-index) and [delete all collections](/guides/manage-data/back-up-an-index#delete-a-collection) in the project. * No more than 2 GB of data across all of your serverless indexes * If you are storing more than 2 GB of data, [delete records](/guides/manage-data/delete-data) until you're storing less than 2 GB. * No more than 100 namespaces per serverless index * If any serverless index has more than 100 namespaces, [delete namespaces](/guides/manage-data/delete-data#delete-all-records-from-a-namespace) until it has 100 or fewer remaining. * No more than 3 [assistants](/guides/assistant/overview) * If you have more than 3 assistants, [delete assistants](/guides/assistant/manage-assistants#delete-an-assistant) until you have 3 or fewer. * No more than 10 files per assistant * If you have more than 10 files uploaded to an assistant, [delete files](/guides/assistant/manage-files#delete-a-file) until the assistant has 10 or fewer. * No more than 1 GB of assistant storage * If you have more than 1 GB of assistant storage, [delete files](https://docs.pinecone.io/guides/assistant/manage-files#delete-a-file) until you're storing less than 1 GB. * No more than 2 users * No collections or backups (these are automatically deleted as part of the downgrade process) If you have questions, [contact Support](https://www.pinecone.io/contact/support/). ## Limits * Each organization is allowed only one trial. * Organizations already on a Standard or Enterprise plan cannot activate a Standard plan trial. * Organizations that initially subscribed to Pinecone through marketplace partners cannot activate a Standard plan trial. If you have any questions, [contact Support](https://www.pinecone.io/contact/support/). # Upgrade your plan Source: https://docs.pinecone.io/guides/organizations/manage-billing/upgrade-billing-plan Upgrade to a paid plan to access advanced features and limits. This page describes how to upgrade from the free Starter plan to the [Standard or Enterprise plan](https://www.pinecone.io/pricing/), paying either with a credit/debit card or through a supported cloud marketplace. To change your plan, you must be an [organization owner or billing admin](/guides/organizations/understanding-organizations#organization-roles). To commit to annual spending, [contact Pinecone](https://www.pinecone.io/contact). ## Pay with a credit/debit card To upgrade your plan to Standard or Enterprise and pay with a credit/debit card, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Credit / Debit card**. 4. Enter your credit card information. 5. Click **Upgrade**. After upgrading, you will immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ## Pay through the Google Cloud Marketplace To upgrade your plan to Standard or Enterprise and pay through the Google Cloud Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through GCP**. This takes you to the [Pinecone listing](https://console.cloud.google.com/marketplace/product/pinecone-public/pinecone) in the Google Cloud Marketplace. 4. Click **Subscribe**. 5. On the **Order Summary** page, select a billing account, accept the terms and conditions, and click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. On the **Your order request has been sent to Pinecone** modal, click **Sign up with Pinecone**. This takes you to a Google-specific Pinecone login page. 7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ## Pay through the AWS Marketplace To upgrade your plan to Standard or Enterprise and pay through the AWS Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through AWS**. This takes you to the [Pinecone listing](https://aws.amazon.com/marketplace/pp/prodview-xhgyscinlz4jk) in the AWS Marketplace. 4. Click **View purchase options**. 5. On the **Subscribe to Pinecone Vector Database** page, review the offer and then click **Subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 6. You'll see a message stating that your subscription is in process. Click **Set up your account**. This takes you to an AWS-specific Pinecone login page. If the [Pinecone subscription page](https://aws.amazon.com/marketplace/saas/ordering?productId=738798c3-eeca-494a-a2a9-161bee9450b2) shows a message stating, “You are currently subscribed to this offer,” contact your team members to request an invitation to the existing AWS-linked organization. The **Set up your account** button is clickable, but Pinecone does not create a new AWS-linked organization. 7. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 8. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 9. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). ## Pay through the Microsoft Marketplace To upgrade your plan to Standard or Enterprise and pay through the Microsoft Marketplace, do the following: 1. In the Pinecone console, go to [Settings > Billing > Plans](https://app.pinecone.io/organizations/-/settings/billing/plans). 2. Click **Upgrade** in the **Standard** or **Enterprise** plan section. 3. Click **Billing through Azure**. This takes you to the [Pinecone listing](https://marketplace.microsoft.com/product/saas/pineconesystemsinc1688761585469.pineconesaas) in the Microsoft Marketplace. 4. Click **Get it now**. 5. Select the **Pinecone - Pay As You Go** plan. 6. Click **Subscribe**. 7. On the **Subscribe to Pinecone** page, select the required details and click **Review + subscribe**. The billing unit listed does not reflect the actual cost or metering of costs for Pinecone. See the [Pinecone Pricing page](https://www.pinecone.io/pricing/) for accurate details. 8. Click **Subscribe**. 9. After the subscription is approved, click **Configure account now**. This redirects you to an Microsoft-specific Pinecone login page. 10. Log in to your Pinecone account. Use the same authentication method as your existing Pinecone organization. 11. Select an organization from the list. You can only connect to organizations that are on the [Starter plan](https://www.pinecone.io/pricing/). Alternatively, you can opt to create a new organization. 12. Click **Connect to Pinecone** and follow the prompts. Once your organization is connected and upgraded, you will receive a confirmation message. You will then immediately start paying for usage of your Pinecone indexes, including the serverless indexes that were free on the Starter plan. For more details about how costs are calculated, see [Understanding cost](/guides/manage-cost/understanding-cost). # Manage organization members Source: https://docs.pinecone.io/guides/organizations/manage-organization-members Add and manage organization members and roles. This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage organization members. For information about managing members at the **project-level**, see [Manage project members](/guides/projects/manage-project-members). ## Add a member to an organization You can add members to your organization in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the **Invite by email** field, enter the member's email address. 3. Choose an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the member. The role determines the member's permissions within Pinecone. 4. Click **Invite**. When you invite a member to join your organization, Pinecone sends them an email containing a link that enables them to gain access to the organization or project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project. ## Change a member's role You can change a member's role in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the row of the member whose role you want to change, click **ellipsis (...) menu > Edit role**. 3. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. 4. Click **Edit role**. ## Remove a member You can remove a member from your organization in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Members**](https://app.pinecone.io/organizations/-/settings/access/members). 2. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**. 3. Click **Remove Member**. To remove yourself from an organization, click the **Leave organization** button in your user's row and confirm. # Manage service accounts at the organization-level Source: https://docs.pinecone.io/guides/organizations/manage-service-accounts Create service accounts for organization-level API access. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) can add and manage service accounts at the organization-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. Once a service account is added at the organization-level, it can be added to a project. For more information, see [Manage service accounts at the project-level](/guides/projects/manage-service-accounts). ## Create a service account You can create a service account in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/access/service-accounts). 2. Enter a **Name** for the service account. 3. Choose an [**Organization Role**](/guides/organizations/understanding-organizations#organization-roles) for the service account. The role determines the service account's permissions within Pinecone. 4. Click **Create**. 5. Copy and save the **Client secret** in a secure place for future use. You will need the client secret to retrieve an access token. You will not be able to see the client secret again after you close the dialog. 6. Click **Close**. Once you have created a service account, [add it to a project](/guides/projects/manage-service-accounts#add-a-service-account-to-a-project) to allow it access to the project's resources. ## Retrieve an access token To access the Admin API, you must provide an access token to authenticate. Retrieve the access token using the client secret of a service account, which was [provided at time of creation](#create-a-service-account). You can retrieve an access token for a service account from the `https://login.pinecone.io/oauth/token` endpoint, as shown in the following example: ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io -H "X-Pinecone-Api-Version: 2025-10" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "audience": "https://api.pinecone.io/" }' ``` The response will include an `access_token` field, which you can use to authenticate with the Admin API. ``` { "access_token":"YOUR_ACCESS_TOKEN", "expires_in":86400, "token_type":"Bearer" } ``` ## Change a service account's role You can change a service account's role in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**. 3. Select an [**Organization role**](/guides/organizations/understanding-organizations#organization-roles) for the service account. 4. Click **Update**. ## Update service account name You can change a service account's name in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Manage**. 3. Enter a new **Service account name**. 4. Click **Update**. ## Rotate a service account's secret You can rotate a service account's client secret in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Rotate secret**. 3. **Enter the service account name** to confirm. 4. Click **Rotate client secret**. 5. Copy and save the **Client secret** in a secure place for future use. You will not be able to see the client secret again after you close the dialog. 6. Click **Close**. ## Delete a service account Deleting a service account will remove it from all projects and will disrupt any applications using it to access Pinecone. You delete a service account in the [Pinecone console](https://app.pinecone.io): 1. Go to [**Settings > Access > Service accounts**](https://app.pinecone.io/organizations/-/settings/service-accounts). 2. In the row of the service account you want to update, click **ellipsis (...) menu > Delete**. 3. **Enter the service account name** to confirm. 4. Click **Delete service account**. # Understanding organizations Source: https://docs.pinecone.io/guides/organizations/understanding-organizations Understand organization structure, projects, and billing. A Pinecone organization is a set of [projects](/guides/projects/understanding-projects) that use the same billing. Organizations allow one or more users to control billing and project permissions for all of the projects belonging to the organization. Each project belongs to an organization. While an email address can be associated with multiple organizations, it cannot be used to create more than one organization. For information about managing organization members, see [Manage organization members](/guides/organizations/manage-organization-members). ## Projects in an organization Each organization contains one or more projects that share the same organization owners and billing settings. Each project belongs to exactly one organization. If you need to move a project from one organization to another, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ## Billing settings All of the projects in an organization share the same billing method and settings. The billing settings for the organization are controlled by the organization owners. Organization owners can update the billing contact information, update the payment method, and view and download invoices using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/billing). ## Organization roles Organization owners can manage access to their organizations and projects by assigning roles to organization members and service accounts. The role determines the entity's permissions within Pinecone. The organization roles are as follows: * **Organization owner**: Organization owners have global permissions across the organization. This includes managing billing details, organization members, and all projects. Organization owners are automatically [project owners](/guides/projects/understanding-projects#project-roles) and, therefore, have all project owner permissions as well. * **Organization user**: Organization users have restricted organization-level permissions. When inviting organization users, you also choose the projects they belong to and the project role they should have. * **Billing admin**: Billing admins have permissions to view and update billing details, but they cannot manage organization members. Billing admins cannot manage projects unless they are also [project owners](/guides/projects/understanding-projects#project-roles). The following table summarizes the permissions for each organization role: | Permission | Org Owner | Org User | Billing Admin | | ------------------------------------ | --------- | -------- | ------------- | | View account details | ✓ | ✓ | ✓ | | Update organization name | ✓ | | | | Delete the organization | ✓ | | | | View billing details | ✓ | | ✓ | | Update billing details | ✓ | | ✓ | | View usage details | ✓ | | ✓ | | View support plans | ✓ | | ✓ | | Invite members to the organization | ✓ | | | | Delete pending member invites | ✓ | | | | Remove members from the organization | ✓ | | | | Update organization member roles | ✓ | | | | Create projects | ✓ | ✓ | | ## Organization single sign-on (SSO) SSO allows organizations to manage their teams' access to Pinecone through their identity management solution. Once your integration is configured, you can specify a default role for teammates when they sign up. For more information, see [Configure single sign-on](/guides/production/configure-single-sign-on/okta). SSO is available on Standard and Enterprise plans. ## Service accounts This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). [Service accounts](/guides/organizations/manage-service-accounts) enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. Use service accounts to automate infrastructure management and integrate Pinecone into your deployment workflows, rather than through manual actions in the Pinecone console. Service accounts use the [organization roles](/guides/organizations/understanding-organizations#organization-roles) and [project role](/guides/projects/understanding-projects#project-roles) for permissioning, and provide a secure and auditable way to handle programmatic access. ## See also * [Manage organization members](/guides/organizations/manage-organization-members) * [Manage project members](/guides/projects/manage-project-members) # CI/CD with Pinecone Local and GitHub Actions Source: https://docs.pinecone.io/guides/production/automated-testing Test Pinecone integration with CI/CD workflows. Pinecone Local is an in-memory Pinecone Database emulator available as a Docker image. This page shows you how to build a CI/CD workflow with Pinecone Local and [GitHub Actions](https://docs.github.com/en/actions) to test your integration without connecting to your Pinecone account, affecting production data, or incurring any usage or storage fees. Pinecone Local is not suitable for production. See [Limitations](#limitations) for details. This feature is in [public preview](/release-notes/feature-availability). ## Limitations Pinecone Local has the following limitations: * Pinecone Local uses the `2025-01` API version, which is not the latest stable version. * Pinecone Local is available in Docker only. * Pinecone Local is an in-memory emulator and is not suitable for production. Records loaded into Pinecone Local do not persist after it is stopped. * Pinecone Local does not authenticate client requests. API keys are ignored. * Max number of records per index: 100,000. Pinecone Local does not currently support the following features: * [Import from object storage](/guides/index-data/import-data) * [Backup/restore of serverless indexes](/guides/manage-data/backups-overview) * [Collections for pod-based indexes](/guides/indexes/pods/understanding-collections) * [Namespace management](/guides/manage-data/manage-namespaces) * [Pinecone Inference](/reference/api/introduction#inference) * [Pinecone Assistant](/guides/assistant/overview) ## 1. Write your tests Running code against Pinecone Local is just like running code against your Pinecone account, with the following differences: * Pinecone Local does not authenticate client requests. API keys are ignored. * The latest version of Pinecone Local uses [Pinecone API version](/reference/api/versioning) `2025-01` and requires [Python SDK](/reference/python-sdk) `v6.x` or later, [Node.js SDK](/reference/node-sdk) `v5.x` or later, [Java SDK](/reference/java-sdk) `v4.x` or later, [Go SDK](/reference/go-sdk) `v3.x` or later, and [.NET SDK](/reference/dotnet-sdk) `v3.x` or later. Be sure to review the [limitations](#limitations) of Pinecone Local before using it for development or testing. **Example** The following example assumes that you have [started Pinecone Local without indexes](/guides/operations/local-development#database-emulator). It initializes a client, creates a [dense index](/guides/index-data/indexing-overview#dense-indexes) and a [sparse index](/guides/index-data/indexing-overview#sparse-indexes), upserts records into the indexes, checks their record counts, and queries the indexes. ```python Python theme={null} from pinecone.grpc import PineconeGRPC, GRPCClientConfig from pinecone import ServerlessSpec # Initialize a client. # API key is required, but the value does not matter. # Host and port of the Pinecone Local instance # is required when starting without indexes. pc = PineconeGRPC( api_key="pclocal", host="http://localhost:5080" ) # Create two indexes, one dense and one sparse dense_index_name = "dense-index" sparse_index_name = "sparse-index" if not pc.has_index(dense_index_name): dense_index_model = pc.create_index( name=dense_index_name, vector_type="dense", dimension=2, metric="cosine", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("Dense index model:\n", dense_index_model) if not pc.has_index(sparse_index_name): sparse_index_model = pc.create_index( name=sparse_index_name, vector_type="sparse", metric="dotproduct", spec=ServerlessSpec(cloud="aws", region="us-east-1"), deletion_protection="disabled", tags={"environment": "development"} ) print("\nSparse index model:\n", sparse_index_model) # Target each index, disabling tls dense_index_host = pc.describe_index(name=dense_index_name).host dense_index = pc.Index(host=dense_index_host, grpc_config=GRPCClientConfig(secure=False)) sparse_index_host = pc.describe_index(name=sparse_index_name).host sparse_index = pc.Index(host=sparse_index_host, grpc_config=GRPCClientConfig(secure=False)) # Upsert records into the dense index dense_index.upsert( vectors=[ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ], namespace="example-namespace" ) # Upsert records into the sparse index sparse_index.upsert( namespace="example-namespace", vectors=[ { "id": "vec1", "sparse_values": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparse_values": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparse_values": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] ) # Check the number of records in each index print("\nDense index stats:\n", dense_index.describe_index_stats()) print("\nSparse index stats:\n", sparse_index.describe_index_stats()) # Query the dense index with a metadata filter dense_response = dense_index.query( namespace="example-namespace", vector=[3.0, -2.0], filter={"genre": {"$eq": "documentary"}}, top_k=1, include_values=False, include_metadata=True ) print("\nDense query response:\n", dense_response) # Query the sparse index with a metadata filter sparse_response = sparse_index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, filter={ "quarter": {"$eq": "Q4"} }, top_k=1, include_values=False, include_metadata=True ) print("/nSparse query response:\n", sparse_response) # Delete the indexes pc.delete_index(name=dense_index_name) pc.delete_index(name=sparse_index_name) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; // Initialize a client. // API key is required, but the value does not matter. // Host and port of the Pinecone Local instance // is required when starting without indexes. const pc = new Pinecone({ apiKey: 'pclocal', controllerHostUrl: 'http://localhost:5080' }); // Create two indexes, one dense and one sparse const denseIndexName = 'dense-index'; const sparseIndexName = 'sparse-index'; const denseIndexModel = await pc.createIndex({ name: denseIndexName, vectorType: 'dense', dimension: 2, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('Dense index model:', denseIndexModel); const sparseIndexModel = await pc.createIndex({ name: sparseIndexName, vectorType: 'sparse', metric: 'dotproduct', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, deletionProtection: 'disabled', tags: { environment: 'development' }, }); console.log('\nSparse index model:', sparseIndexModel); // Target each index const denseIndexHost = (await pc.describeIndex(denseIndexName)).host; const denseIndex = await pc.index(denseIndexName, 'http://' + denseIndexHost); const sparseIndexHost = (await pc.describeIndex(sparseIndexName)).host; const sparseIndex = await pc.index(sparseIndexName, 'http://' + sparseIndexHost); // Upsert records into the dense index await denseIndex.namespace('example-namespace').upsert([ { id: 'vec1', values: [1.0, -2.5], metadata: { genre: 'drama' }, }, { id: 'vec2', values: [3.0, -2.0], metadata: { genre: 'documentary' }, }, { id: 'vec3', values: [0.5, -1.5], metadata: { genre: 'documentary' }, } ]); // Upsert records into the sparse index await sparseIndex.namespace('example-namespace').upsert([ { id: 'vec1', sparseValues: { indices: [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191], values: [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688] }, metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } }, { id: 'vec2', sparseValues: { indices: [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697], values: [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469] }, metadata: { chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', sparseValues: { indices: [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697], values: [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094] }, metadata: { chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", category: 'technology', quarter: 'Q3' } } ]); // Check the number of records in each index console.log('\nDense index stats:', await denseIndex.describeIndexStats()); console.log('\nSparse index stats:', await sparseIndex.describeIndexStats()); // Query the dense index with a metadata filter const denseQueryResponse = await denseIndex.namespace('example-namespace').query({ vector: [3.0, -2.0], filter: { 'genre': {'$eq': 'documentary'} }, topK: 1, includeValues: false, includeMetadata: true, }); console.log('\nDense query response:', denseQueryResponse); const sparseQueryResponse = await sparseIndex.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 1, includeValues: false, includeMetadata: true }); console.log('\nSparse query response:', sparseQueryResponse); // Delete the index await pc.deleteIndex(denseIndexName); await pc.deleteIndex(sparseIndexName); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.clients.Pinecone; import io.pinecone.proto.DescribeIndexStatsResponse; import org.openapitools.db_control.client.model.DeletionProtection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.*; public class PineconeLocalExample { public static void main(String[] args) { // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. String host = "http://localhost:5080"; Pinecone pc = new Pinecone.Builder("pclocal") .withHost(host) .withTlsEnabled(false) .build(); // Create two indexes, one dense and one sparse String denseIndexName = "dense-index"; String sparseIndexName = "sparse-index"; HashMap tags = new HashMap<>(); tags.put("environment", "development"); pc.createServerlessIndex( denseIndexName, "cosine", 2, "aws", "us-east-1", DeletionProtection.DISABLED, tags ); pc.createSparseServelessIndex( sparseIndexName, "aws", "us-east-1", DeletionProtection.DISABLED, tags, "sparse" ); // Get index connection objects Index denseIndexConnection = pc.getIndexConnection(denseIndexName); Index sparseIndexConnection = pc.getIndexConnection(sparseIndexName); // Upsert records into the dense index Struct metaData1 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("drama").build()) .build(); Struct metaData2 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); Struct metaData3 = Struct.newBuilder() .putFields("genre", Value.newBuilder().setStringValue("documentary").build()) .build(); denseIndexConnection.upsert("vec1", Arrays.asList(1.0f, -2.5f), null, null, metaData1, "example-namespace"); denseIndexConnection.upsert("vec2", Arrays.asList(3.0f, -2.0f), null, null, metaData2, "example-namespace"); denseIndexConnection.upsert("vec3", Arrays.asList(0.5f, -1.5f), null, null, metaData3, "example-namespace"); // Upsert records into the sparse index ArrayList indices1 = new ArrayList<>(Arrays.asList( 822745112L, 1009084850L, 1221765879L, 1408993854L, 1504846510L, 1596856843L, 1640781426L, 1656251611L, 1807131503L, 2543655733L, 2902766088L, 2909307736L, 3246437992L, 3517203014L, 3590924191L )); ArrayList values1 = new ArrayList<>(Arrays.asList( 1.7958984f, 0.41577148f, 2.828125f, 2.8027344f, 2.8691406f, 1.6533203f, 5.3671875f, 1.3046875f, 0.49780273f, 0.5722656f, 2.71875f, 3.0820312f, 2.5019531f, 4.4414062f, 3.3554688f )); Struct sparseMetaData1 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); ArrayList indices2 = new ArrayList<>(Arrays.asList( 131900689L, 592326839L, 710158994L, 838729363L, 1304885087L, 1640781426L, 1690623792L, 1807131503L, 2066971792L, 2428553208L, 2548600401L, 2577534050L, 3162218338L, 3319279674L, 3343062801L, 3476647774L, 3485013322L, 3517203014L, 4283091697L )); ArrayList values2 = new ArrayList<>(Arrays.asList( 0.4362793f, 3.3457031f, 2.7714844f, 3.0273438f, 3.3164062f, 5.6015625f, 2.4863281f, 0.38134766f, 1.25f, 2.9609375f, 0.34179688f, 1.4306641f, 0.34375f, 3.3613281f, 1.4404297f, 2.2558594f, 2.2597656f, 4.8710938f, 0.5605469f )); Struct sparseMetaData2 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("Analysts suggest that AAPL'\\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q4").build()) .build(); ArrayList indices3 = new ArrayList<>(Arrays.asList( 8661920L, 350356213L, 391213188L, 554637446L, 1024951234L, 1640781426L, 1780689102L, 1799010313L, 2194093370L, 2632344667L, 2641553256L, 2779594451L, 3517203014L, 3543799498L, 3837503950L, 4283091697L )); ArrayList values3 = new ArrayList<>(Arrays.asList( 2.6875f, 4.2929688f, 3.609375f, 3.0722656f, 2.1152344f, 5.78125f, 3.7460938f, 3.7363281f, 1.2695312f, 3.4824219f, 0.7207031f, 0.0826416f, 4.671875f, 3.7011719f, 2.796875f, 0.61621094f )); Struct sparseMetaData3 = Struct.newBuilder() .putFields("chunk_text", Value.newBuilder().setStringValue("AAPL'\\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production").build()) .putFields("category", Value.newBuilder().setStringValue("technology").build()) .putFields("quarter", Value.newBuilder().setStringValue("Q3").build()) .build(); sparseIndexConnection.upsert("vec1", Collections.emptyList(), indices1, values1, sparseMetaData1, "example-namespace"); sparseIndexConnection.upsert("vec2", Collections.emptyList(), indices2, values2, sparseMetaData2, "example-namespace"); sparseIndexConnection.upsert("vec3", Collections.emptyList(), indices3, values3, sparseMetaData3, "example-namespace"); // Check the number of records each the index DescribeIndexStatsResponse denseIndexStatsResponse = denseIndexConnection.describeIndexStats(null); System.out.println("Dense index stats:"); System.out.println(denseIndexStatsResponse); DescribeIndexStatsResponse sparseIndexStatsResponse = sparseIndexConnection.describeIndexStats(null); System.out.println("Sparse index stats:"); System.out.println(sparseIndexStatsResponse); // Query the dense index with a metadata filter List queryVector = Arrays.asList(1.0f, 1.5f); QueryResponseWithUnsignedIndices denseQueryResponse = denseIndexConnection.query(1, queryVector, null, null, null, "example-namespace", null, false, true); System.out.println("Dense query response:"); System.out.println(denseQueryResponse); // Query the sparse index with a metadata filter List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices sparseQueryResponse = sparseIndexConnection.query(1, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println("Sparse query response:"); System.out.println(sparseQueryResponse); // Delete the indexes pc.deleteIndex(denseIndexName); pc.deleteIndex(sparseIndexName); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" "google.golang.org/protobuf/types/known/structpb" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() // Initialize a client. // No API key is required. // Host and port of the Pinecone Local instance // is required when starting without indexes. pc, err := pinecone.NewClientBase(pinecone.NewClientBaseParams{ Host: "http://localhost:5080", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // Create two indexes, one dense and one sparse denseIndexName := "dense-index" denseVectorType := "dense" dimension := int32(2) denseMetric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled denseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: denseIndexName, VectorType: &denseVectorType, Dimension: &dimension, Metric: &denseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", denseIdx.Name) } else { fmt.Printf("Successfully created serverless index: %v\n", denseIdx.Name) } sparseIndexName := "sparse-index" sparseVectorType := "sparse" sparseMetric := pinecone.Dotproduct sparseIdx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: sparseIndexName, VectorType: &sparseVectorType, Metric: &sparseMetric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, Tags: &pinecone.IndexTags{"environment": "development"}, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", sparseIdx.Name) } else { fmt.Printf("\nSuccessfully created serverless index: %v\n", sparseIdx.Name) } // Get the index hosts denseIdxModel, err := pc.DescribeIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", denseIndexName, err) } sparseIdxModel, err := pc.DescribeIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", sparseIndexName, err) } // Target the indexes. // Make sure to prefix the hosts with http:// to let the SDK know to disable tls. denseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + denseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseIdxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "http://" + sparseIdxModel.Host, Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } // Upsert records into the dense index denseMetadataMap1 := map[string]interface{}{ "genre": "drama", } denseMetadata1, err := structpb.NewStruct(denseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap2 := map[string]interface{}{ "genre": "documentary", } denseMetadata2, err := structpb.NewStruct(denseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseMetadataMap3 := map[string]interface{}{ "genre": "documentary", } denseMetadata3, err := structpb.NewStruct(denseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseVectors := []*pinecone.Vector{ { Id: "vec1", Values: &[]float32{1.0, -2.5}, Metadata: denseMetadata1, }, { Id: "vec2", Values: &[]float32{3.0, -2.0}, Metadata: denseMetadata2, }, { Id: "vec3", Values: &[]float32{0.5, -1.5}, Metadata: denseMetadata3, }, } denseCount, err := denseIdxConnection.UpsertVectors(ctx, denseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", denseCount) } // Upsert records into the sparse index sparseValues1 := pinecone.SparseValues{ Indices: []uint32{822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191}, Values: []float32{1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688}, } sparseMetadataMap1 := map[string]interface{}{ "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones", "category": "technology", "quarter": "Q3", } sparseMetadata1, err := structpb.NewStruct(sparseMetadataMap1) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues2 := pinecone.SparseValues{ Indices: []uint32{131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697}, Values: []float32{0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.560546}, } sparseMetadataMap2 := map[string]interface{}{ "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4", } sparseMetadata2, err := structpb.NewStruct(sparseMetadataMap2) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseValues3 := pinecone.SparseValues{ Indices: []uint32{8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697}, Values: []float32{2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094}, } sparseMetadataMap3 := map[string]interface{}{ "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3", } sparseMetadata3, err := structpb.NewStruct(sparseMetadataMap3) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } sparseVectors := []*pinecone.Vector{ { Id: "vec1", SparseValues: &sparseValues1, Metadata: sparseMetadata1, }, { Id: "vec2", SparseValues: &sparseValues2, Metadata: sparseMetadata2, }, { Id: "vec3", SparseValues: &sparseValues3, Metadata: sparseMetadata3, }, } sparseCount, err := sparseIdxConnection.UpsertVectors(ctx, sparseVectors) if err != nil { log.Fatalf("Failed to upsert vectors: %v", err) } else { fmt.Printf("\nSuccessfully upserted %d vector(s)!\n", sparseCount) } // Check the number of records in each index denseStats, err := denseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nDense index stats: %+v\n", prettifyStruct(*denseStats)) } sparseStats, err := sparseIdxConnection.DescribeIndexStats(ctx) if err != nil { log.Fatalf("Failed to describe index: %v", err) } else { fmt.Printf("\nSparse index stats: %+v\n", prettifyStruct(*sparseStats)) } // Query the dense index with a metadata filter queryVector := []float32{3.0, -2.0} queryMetadataMap := map[string]interface{}{ "genre": map[string]interface{}{ "$eq": "documentary", }, } metadataFilter, err := structpb.NewStruct(queryMetadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } denseRes, err := denseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 1, MetadataFilter: metadataFilter, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nDense query response: %v\n", prettifyStruct(denseRes)) } // Query the sparse index with a metadata filter sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } sparseRes, err := sparseIdxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 1, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf("\nSparse query response: %v\n", prettifyStruct(sparseRes)) } // Delete the indexes err = pc.DeleteIndex(ctx, denseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", denseIndexName) } err = pc.DeleteIndex(ctx, sparseIndexName) if err != nil { log.Fatalf("Failed to delete index: %v", err) } else { fmt.Printf("\nIndex \"%v\" deleted successfully\n", sparseIndexName) } } ``` ```csharp C# theme={null} using Pinecone; // Initialize a client. // API key is required, but the value does not matter. // When starting without indexes, disable TLS and // provide the host and port of the Pinecone Local instance. var pc = new PineconeClient("pclocal", new ClientOptions { BaseUrl = "http://localhost:5080", IsTlsEnabled = false } ); // Create two indexes, one dense and one sparse var denseIndexName = "dense-index"; var sparseIndexName = "sparse-index"; var createDenseIndexRequest = await pc.CreateIndexAsync(new CreateIndexRequest { Name = denseIndexName, VectorType = VectorType.Dense, Dimension = 2, Metric = MetricType.Cosine, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } }); Console.WriteLine("Dense index model:" + createDenseIndexRequest); var createSparseIndexRequest = await pc.CreateIndexAsync(new CreateIndexRequest { Name = sparseIndexName, VectorType = VectorType.Sparse, Metric = MetricType.Dotproduct, Spec = new ServerlessIndexSpec { Serverless = new ServerlessSpec { Cloud = ServerlessSpecCloud.Aws, Region = "us-east-1" } }, DeletionProtection = DeletionProtection.Disabled, Tags = new Dictionary { { "environment", "development" } } }); Console.WriteLine("\nSparse index model:" + createSparseIndexRequest); // Target the indexes var denseIndex = pc.Index(denseIndexName); var sparseIndex = pc.Index(sparseIndexName); // Upsert records into the dense index var denseUpsertResponse = await denseIndex.UpsertAsync(new UpsertRequest() { Namespace = "example-namespace", Vectors = new List { new Vector { Id = "vec1", Values = new ReadOnlyMemory([1.0f, -2.5f]), Metadata = new Metadata { ["genre"] = new("drama"), }, }, new Vector { Id = "vec2", Values = new ReadOnlyMemory([3.0f, -2.0f]), Metadata = new Metadata { ["genre"] = new("documentary"), }, }, new Vector { Id = "vec3", Values = new ReadOnlyMemory([0.5f, -1.5f]), Metadata = new Metadata { ["genre"] = new("documentary"), } } } }); Console.WriteLine($"\nUpserted {denseUpsertResponse.UpsertedCount} dense vectors"); // Upsert records into the sparse index var sparseVector1 = new Vector { Id = "vec1", SparseValues = new SparseValues { Indices = new uint[] { 822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var sparseVector2 = new Vector { Id = "vec2", SparseValues = new SparseValues { Indices = new uint[] { 131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."), ["category"] = new("technology"), ["quarter"] = new("Q4"), }, }; var sparseVector3 = new Vector { Id = "vec3", SparseValues = new SparseValues { Indices = new uint[] { 8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697 }, Values = new ReadOnlyMemory([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]) }, Metadata = new Metadata { ["chunk_text"] = new("AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"), ["category"] = new("technology"), ["quarter"] = new("Q3"), }, }; var sparseUpsertResponse = await sparseIndex.UpsertAsync(new UpsertRequest { Vectors = new List { sparseVector1, sparseVector2, sparseVector3 }, Namespace = "example-namespace" }); Console.WriteLine($"\nUpserted {sparseUpsertResponse.UpsertedCount} sparse vectors"); // Check the number of records in each index var denseIndexStatsResponse = await denseIndex.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine("\nDense index stats:" + denseIndexStatsResponse); var sparseIndexStatsResponse = await sparseIndex.DescribeIndexStatsAsync(new DescribeIndexStatsRequest()); Console.WriteLine("\nSparse index stats:" + sparseIndexStatsResponse); // Query the dense index with a metadata filter var denseQueryResponse = await denseIndex.QueryAsync(new QueryRequest { Vector = new ReadOnlyMemory([3.0f, -2.0f]), TopK = 1, Namespace = "example-namespace", Filter = new Metadata { ["genre"] = new Metadata { ["$eq"] = "documentary", } }, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine("\nDense query response:" + denseQueryResponse); // Query the sparse index with a metadata filter var sparseQueryResponse = await sparseIndex.QueryAsync(new QueryRequest { Namespace = "example-namespace", TopK = 1, SparseVector = new SparseValues { Indices = [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], Values = new[] { 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f }, }, Filter = new Metadata { ["quarter"] = new Metadata { ["$eq"] = "Q4", } }, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine("\nSparse query response:" + sparseQueryResponse); // Delete the indexes await pc.DeleteIndexAsync(denseIndexName); await pc.DeleteIndexAsync(sparseIndexName); ``` ```shell curl theme={null} PINECONE_LOCAL_HOST="localhost:5080" DENSE_INDEX_HOST="localhost:5081" SPARSE_INDEX_HOST="localhost:5082" # Create two indexes, one dense and one sparse curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "dense-index", "vector_type": "dense", "dimension": 2, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' curl -X POST "http://$PINECONE_LOCAL_HOST/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "sparse-index", "vector_type": "sparse", "metric": "dotproduct", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "environment": "development" }, "deletion_protection": "disabled" }' # Upsert records into the dense index curl -X POST "http://$DENSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "values": [1.0, -2.5], "metadata": {"genre": "drama"} }, { "id": "vec2", "values": [3.0, -2.0], "metadata": {"genre": "documentary"} }, { "id": "vec3", "values": [0.5, -1.5], "metadata": {"genre": "documentary"} } ] }' # Upsert records into the sparse index curl -X POST "http://$SPARSE_INDEX_HOST/vectors/upsert" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vectors": [ { "id": "vec1", "sparseValues": { "values": [1.7958984, 0.41577148, 2.828125, 2.8027344, 2.8691406, 1.6533203, 5.3671875, 1.3046875, 0.49780273, 0.5722656, 2.71875, 3.0820312, 2.5019531, 4.4414062, 3.3554688], "indices": [822745112, 1009084850, 1221765879, 1408993854, 1504846510, 1596856843, 1640781426, 1656251611, 1807131503, 2543655733, 2902766088, 2909307736, 3246437992, 3517203014, 3590924191] }, "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } }, { "id": "vec2", "sparseValues": { "values": [0.4362793, 3.3457031, 2.7714844, 3.0273438, 3.3164062, 5.6015625, 2.4863281, 0.38134766, 1.25, 2.9609375, 0.34179688, 1.4306641, 0.34375, 3.3613281, 1.4404297, 2.2558594, 2.2597656, 4.8710938, 0.5605469], "indices": [131900689, 592326839, 710158994, 838729363, 1304885087, 1640781426, 1690623792, 1807131503, 2066971792, 2428553208, 2548600401, 2577534050, 3162218338, 3319279674, 3343062801, 3476647774, 3485013322, 3517203014, 4283091697] }, "metadata": { "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "sparseValues": { "values": [2.6875, 4.2929688, 3.609375, 3.0722656, 2.1152344, 5.78125, 3.7460938, 3.7363281, 1.2695312, 3.4824219, 0.7207031, 0.0826416, 4.671875, 3.7011719, 2.796875, 0.61621094], "indices": [8661920, 350356213, 391213188, 554637446, 1024951234, 1640781426, 1780689102, 1799010313, 2194093370, 2632344667, 2641553256, 2779594451, 3517203014, 3543799498, 3837503950, 4283091697] }, "metadata": { "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "category": "technology", "quarter": "Q3" } } ] }' # Check the number of records in each index curl -X POST "http://$DENSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' curl -X POST "http://$SPARSE_INDEX_HOST/describe_index_stats" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{}' # Query the dense index with a metadata filter curl "http://$DENSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [3.0, -2.0], "filter": {"genre": {"$eq": "documentary"}}, "topK": 1, "includeMetadata": true, "includeValues": false, "namespace": "example-namespace" }' # Query the sparse index with a metadata filter curl "http://$SPARSE_INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "filter": {"quarter": {"$eq": "Q4"}}, "namespace": "example-namespace", "topK": 1, "includeMetadata": true, "includeValues": false }' # Delete the index curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/dense-index" \ -H "X-Pinecone-Api-Version: 2025-10" curl -X DELETE "http://$PINECONE_LOCAL_HOST/indexes/sparse-index" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ## 2. Set up GitHub Actions [Set up a GitHub Actions workflow](https://docs.github.com/en/actions/writing-workflows/quickstart) to do the following: 1. Pull the Pinecone Local Docker image. 2. Start a Pinecone Local instance for each test run. 3. Execute tests against the local instance. 4. Tear down the instance after tests complete. Here's a sample GitHub Actions workflow that you can extend for your own needs: ```yaml theme={null} name: CI/CD with Pinecone Local on: pull_request: branches: - main push: branches: - main jobs: pc-local-tests: name: Pinecone Local tests runs-on: ubuntu-latest services: pc-local: image: ghcr.io/pinecone-io/pinecone-local:latest env: PORT: 5080 ports: - "5080-6000:5080-6000" steps: - name: Check out repository code uses: actions/checkout@v4 - name: Install dependencies run: | python -m pip install --upgrade pip pip install "pinecone[grpc]" - name: Run tests run: | pytest test/ ``` ## 3. Run your tests GitHub Actions will automaticaly run your tests against Pinecone Local when the events you specified in your workflow occur. For a list of the events that can trigger a workflow and more details about using GitHub Actions for CI/CD, see the [GitHub Actions documentation](https://docs.github.com/en/actions). # Bring your own cloud Source: https://docs.pinecone.io/guides/production/bring-your-own-cloud Deploy Pinecone in your AWS or GCP account Bring your own cloud (BYOC) lets you deploy Pinecone Database in your own AWS or GCP account to ensure data sovereignty and compliance, with Pinecone handling provisioning, operations, and maintenance. BYOC is in [public preview](/release-notes/feature-availability) on AWS and GCP. To learn more about the offering, [contact Pinecone](https://www.pinecone.io/contact/?contact_form_inquiry_type=Product+Information). ## Use cases Pinecone BYOC is designed for organizations with high security and compliance requirements, for example: * **Data sovereignty**: If your organization has strict data governance policies, Pinecone BYOC can help ensure that all data is stored and processed locally and does not leave your security perimeter. * **Data residency**: The standard Pinecone managed service can be deployed in several [AWS or GCP cloud regions](/guides/index-data/create-an-index#cloud-regions). If your organization has specific data residency or latency constraints that require you to deploy in regions that Pinecone does not yet support, Pinecone BYOC gives you that flexibility. ## Architecture The BYOC architecture employs a split model: * **Data plane**: The data plane is responsible for storing and processing your records, executing queries, and interacting with object storage for index data. In a BYOC deployment, the data plane is hosted in your own AWS or GCP account within a dedicated VPC, ensuring that all data is stored and processed locally and does not leave your organizational boundaries. You use a [private endpoint](#configure-a-private-endpoint) (AWS PrivateLink or GCP Private Service Connect) as an additional measure to secure requests to your indexes. * **Control plane**: The control plane is responsible for managing the index lifecycle as well as region-agnostic services such as user management, authentication, and billing. The control plane does not hold or process any records. In a BYOC deployment, the control plane is managed by Pinecone and hosted globally. Communication between the data plane and control plane is encrypted using TLS and employs role-based access control (RBAC) with minimal IAM permissions. ## Onboarding The onboarding process for BYOC in AWS or GCP involves the following general stages: If you don't already have an AWS or GCP account where you want to deploy Pinecone, you create one for this purpose. You download and run a Terraform template provided by Pinecone. This template creates essential resources, including an IAM role with scoped-down permissions and a trust relationship with Pinecone's AWS or GCP account. Pinecone deploys a data plane cluster within a dedicated VPC in your AWS or GCP account, and you [configure a private endpoint](#configure-a-private-endpoint) for securely connecting to your indexes via AWS PrivateLink or GCP Private Service Connect. Once the environment is operational, Pinecone performs validation tests to ensure proper functionality. ## Configure a private endpoint You use a [private endpoint](#configure-a-private-endpoint) to securely connect to your BYOC indexes. On AWS, you use the [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) service; on GCP, you use the [GCP Private Service Connect](https://cloud.google.com/vpc/docs/private-service-connect) service. 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**, select the relevant resource for your Pinecone BYOC deployment. * For **Network settings**, select the VPC for your BYOC deployment. * In **Additional settings**, select **Enable DNS name** to allow you to access your indexes using a DNS name. Follow the instructions in the GCP documentation to [create a private endpoint](https://cloud.google.com/vpc/docs/configure-private-service-connect-services#create-endpoint) for connecting to your indexes via GCP Private Service Connect. * Set the **Target service** to the following: ``` projects//regions//serviceAttachments/pinecone-psc ``` * Copy the IP address of the private endpoint. You'll need it later. Follow the instructions in the GCP documentation to [create a private DNS zone](https://cloud.google.com/dns/docs/zones#create-private-zone). * Set the **DNS name** to the following: ``` private..pinecone.io ``` * Select the same VPC network as the private endpoint. Follow the instructions in the GCP documentation to [add a resource record set](https://cloud.google.com/dns/docs/records#add-rrset). * Set the **DNS name** to **\***. * Set the **Resource record type** to **A**. * Set the **Ipv4 Address** to the IP address of the private endpoint. ## Create an index Once your BYOC environment is ready, you can create a BYOC index in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes) or via Pinecone API or [Python SDK](/reference/python-sdk). To create a BYOC index, set the `spec` parameter to the environment name provided to you during onboarding, for example: ```python Python {9-11} theme={null} from pinecone import Pinecone, ByocSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="example-byoc-index", dimension=1536, metric="cosine", spec=ByocSpec( environment="aws-us-east-1-b921" ), deletion_protection="disabled", tags={ "example": "tag" } ) ``` ```shell curl {11-15} theme={null} 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": "example-byoc-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "byoc": { "environment": "aws-us-east-1-b921" } }, "tags": { "example": "tag" }, "deletion_protection": "disabled" }' ``` ## Read and write data BYOC does not support reading and writing data from the index browser in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser). Once your private endpoint is configured, you can run data operations against an index as usual, but you must target the index using its private endpoint URL. The only difference in the URL is that `.svc.` is changed to `.svc.private.`. You can get the private endpoint URL for an index from the Pinecone console or API. To get the private endpoint URL for an index from the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index. 3. Select the index. 4. Copy the URL under **PRIVATE ENDPOINT**. To get the private endpoint URL for an index from the API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the private endpoint URL as the `private_host` value: ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: YOUR_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response includes the private endpoint URL as the `private_host` value: ```json JavaScript {6} theme={null} { name: 'docs-example', dimension: 1536, metric: 'cosine', host: 'docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io', privateHost: 'docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'production' }, embed: undefined, spec: { byoc: undefined, pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ``` ```go Go {5} theme={null} index: { "name": "docs-example", "dimension": 1536, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "metric": "cosine", "deletion_protection": "disabled", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "production" } } ``` ```json curl {12} theme={null} { "id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "vector_type": "dense", "name": "docs-example", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "production" } ``` If you run data operations against an index from outside the Private Endpoint, you will get an `Unauthorized` response. ## Monitoring Pinecone engineers monitor the state of your BYOC deployment and manage incidents if they arise. In addition, you can [monitor performance metrics](/guides/production/monitoring) for your BYOC indexes in the Pinecone Console or with Prometheus or Datadog. To use Prometheus, your monitoring tool must have access to your VPC. ## Limitations BYOC does not support the following: * [Integrated embedding](/guides/index-data/indexing-overview#integrated-embedding), which relies on models hosted by Pinecone that are outsite of your AWS or GCP account. * Reading and writing data from the index browser in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/indexes/-/browser). You must use the Pinecone API or SDKs instead. * Using [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek) to secure data within a Pinecone project. Also, to [monitor performance metrics with Prometheus](/guides/production/monitoring#monitor-with-prometheus), you must configure Prometheus within your VPC. ## FAQs In the standard service, Pinecone manages all cloud resources and includes their cost in the service fee. In BYOC, customers provision and pay for cloud resources directly through their AWS or GCP account, providing greater control and data sovereignty as well as access to available AWS or GCP credits or discounts. Also, BYOC does not support certain features. See [Limitations](#limitations) for details. Data is stored and processed exclusively within the customer's AWS or GCP account, with encryption applied at rest and in transit. Communication between the data plane and control plane is encrypted using TLS, and access is controlled via RBAC and scoped IAM permissions. AWS PrivateLink or GCP Private Service Connect is used for secure data plane API calls. Currently, BYOC is available in AWS and GCP. Support for Azure is planned for future releases. # Configure audit logs Source: https://docs.pinecone.io/guides/production/configure-audit-logs Enable audit logging to Amazon S3 for compliance This page describes how to configure audit logs in Pinecone. Audit logs provide a detailed record of user, service account, and API actions that occur on the management and [control plane](/guides/get-started/database-architecture#control-plane) within Pinecone. Pinecone supports Amazon S3 as a destination for audit logs. To enable and manage audit logs, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/). ## Enable audit logs 1. Set up a [IAM policy and role in Amazon S3](/guides/operations/integrations/integrate-with-amazon-s3). 2. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging) in the Pinecone console. 3. Enter the **Role ARN** of the IAM role you created. 4. Enter the name of the Amazon S3 bucket you created. **Targeting a subdirectory:** You can write audit logs to a specific subdirectory by entering `bucket-name/subdirectory-path` in the bucket name field. For example: `my-bucket/pinecone-logs`. Make sure your [IAM policy is configured for subdirectory access](/guides/operations/integrations/integrate-with-amazon-s3#targeting-a-subdirectory-optional). 5. Click **Enable audit logging**. Once you enable audit logs, Pinecone will start writing logs to the S3 bucket. In your bucket, you will also see a file named `audit-log-access-test`, which is a test file that Pinecone writes to verify that it has the necessary permissions to write logs to the bucket. ## View audit logs Logs are written to the S3 bucket approximately every 30 minutes. Each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved. For more information about the log schema and captured events, see [Understanding security - Audit logs](/guides/production/security-overview#audit-logs). ## Edit audit log integration details You can edit the details of the audit log integration in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Enter the new **Role ARN** or **AWS Bucket**. 3. Click **Update settings**. ## Disable audit logs If you disable audit logs, logs not yet saved will be lost. You can disable audit logs in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. Click the toggle next to **Audit logs are active**. 3. Click **Confirm**. ## Remove audit log integration If you remove the audit log integration, logs not yet saved will be lost. You can remove the audit log integration in the Pinecone console: 1. Go to [**Settings > Audit logs**](https://app.pinecone.io/organizations/-/settings/logging). 2. At the top of the page, click the **ellipsis (...) menu > Remove integration**. 3. Click **Remove integration**. # Configure customer-managed encryption keys Source: https://docs.pinecone.io/guides/production/configure-cmek Use customer-managed encryption keys with AWS KMS. 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. This feature is in [public preview](/release-notes/feature-availability). ## Set up CMEK using AWS KMS ### Before you begin The following steps assume you have: * Access to the [AWS console](https://console.aws.amazon.com/console/home). * A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/). ### 1. Create a role In the [AWS console](https://console.aws.amazon.com/console/home), create a role that Pinecone can use to access the AWS Key Management System (KMS) key. You can either grant Pinecone access to a key in your account, or if your customers provide their own keys, you can grant access to keys that are outside of your account. 1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/). 2. In the navigation pane, click **Roles**. 3. Click **Create role**. 4. In the **Trusted entity type** section, select **Custom trust policy**. 5. In the **Custom trust policy** section, enter one of the following JSON snippets. Pick a snippet based on whether you want to allow Pinecone to assume a role from all regions or from explicit regions. Add an optional external ID for additional security. If you use an external ID, you must provide it to Pinecone when [adding a CMEK key](#add-a-key). ```json 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" ] }, "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" } } } ] } ``` ```json 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" ] }, "Action": "sts:AssumeRole" } ] } ``` ```json JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowPineconeToAssumeIntoRoleFromAllRegions", "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key. "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" }, "StringLike": { // Replace XXXXXXXXXXXX with Pinecone's AWS account number. "aws:PrincipalArn": "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_*" } } } ] } ``` Replace `XXXXXXXXXXXX` with Pinecone's AWS account number, which can be found by going to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) in the Pinecone console and clicking **Add CMEK**. 6. Click **Next**. 7. Keep the default permissions as is and click **Next**. 8. Enter a **Role name** and click **Create role**. 9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project). 1. Open the [Amazon Identity and Access Management (IAM) console](https://console.aws.amazon.com/iam/). 2. In the navigation pane, click **Roles**. 3. Click **Create role**. 4. In the **Trusted entity type** section, select **Custom trust policy**. 5. In the **Custom trust policy** section, enter the following JSON: ```json JSON theme={null} { "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:Encrypt" ], "Resource": "arn:aws:kms:*:XXXXXX:key/*" } ] } ``` * Replace `XXXXXX` with the account ID of the customer who owns the key. * Add a `Statement` array for each customer account ID. 6. Click **Next**. 7. Keep the default permissions as is and click **Next**. 8. Enter a **Role name** and click **Create role**. 9. Copy the **Role ARN** (e.g., `arn:aws:iam::XXXXXX:role/YYYYYY`). This will be used to [create a CMEK-enabled project](#3-create-a-cmek-enabled-project). ### 2. Create an AWS KMS key In the [AWS console](https://console.aws.amazon.com/console/home), create the KMS key that Pinecone will use to encrypt your data: 1. Open the [Amazon Key Management Service (KMS) console](https://console.aws.amazon.com/kms/home). 2. In the navigation pane, click **Customer managed keys**. 3. Click **Create key**. 4. In the **Key type** section, select **Symmetric**. 5. In the **Key usage** section, select **Encrypt and decrypt**. 6. Under **Advanced options > Key material origin**, select **KMS**. 7. In the **Regionality** section, select **Single-Region key**. You can create a multi-regional key to safeguard against data loss in case of regional failure. However, Pinecone only accepts one Key ARN per project. If you set a multi-regional key and need to change the Key ARN to switch region, please [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) for help. 8. Click **Next**. 9. Enter an **Alias** and click **Next**. 10. Keep the default administrators as is and click **Next**. 11. Select the [role you created](#1-create-a-role) from the **Key users** list and click **Next**. 12. Click **Finish**. 13. Copy the **Key ARN** (e.g., `arn:aws:kms:us-east-1:XXXXXXX:key/YYYYYYY`). This will be used to [create a CMEK-enabled project](#create-a-cmek-enabled-project). ### 3. Create a CMEK-enabled project Once your [role and key is configured](#set-up-cmek-using-aws-kms), you can create a CMEK-enabled project using the Pinecone console: 1. Go to [**Settings > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click **+Create project**. 3. Enter a **Name**. 4. Select **Encrypt with Customer Managed Encryption Key**. 5. Click **Create project**. 6. Copy and save the generated API key in a secure place for future use. You will not be able to see the API key again after you close the dialog. 7. Click **Close**. ## Add a key To start encrypting your data with a customer-managed key, you need to add the key to the [CMEK-enabled project](#3-create-a-cmek-enabled-project) using the Pinecone console: 1. Go to [**Manage > CMEK**](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the CMEK-enabled project. 2. Click **Add CMEK**. You can only add one key per project, and you cannot change the key in Pinecone once it is set. 3. Enter a **Key name**. 4. Enter the **Role ARN** for the [role you created](#1-create-a-role). 5. Enter a **Key ARN** for the [key you created](#2-create-a-aws-kms-key). 6. If you [created a role](#1-create-a-role) with an external ID, enter the **External ID**. If not, leave this field blank. 7. Click **Create key**. ## Delete a key Before a key can be deleted from a project, all indexes in the project must be deleted. Then, you can delete the key using the Pinecone console: 1. Go to the [Manage > CMEK tab](https://app.pinecone.io/organizations/-/projects/-/cmek-encryption) for the project in which the key was created. 2. For the key you want to delete, click the **ellipsis (...) menu > Delete**. 3. Enter the key name to confirm deletion. 4. Click **Delete key**. ## Limitations * CMEK can be enabled for serverless indexes in AWS regions only. * [Backups](/guides/manage-data/back-up-an-index) are unavailable for indexes created in a CMEK-enabled project. * You cannot change a key once it is set. * You can add only one key per project. # Configure SSO with Okta Source: https://docs.pinecone.io/guides/production/configure-single-sign-on/okta Configure SAML SSO with Okta for enterprise. This page describes how to set up Pinecone with Okta as the single sign-on (SSO) provider. These instructions can be adapted for any provider with SAML 2.0 support. SSO is available on Standard and Enterprise plans. ## Before you begin This page assumes you have the following: * Access to your organization's [Pinecone console](https://login.pinecone.io) as an [organization owner](/guides/organizations/understanding-organizations#organization-owners). * Access to your organization's [Okta Admin console](https://login.okta.com/). ## 1. Start SSO setup in Pinecone First, start setting up SSO in Pinecone. In this step, you'll capture a couple values necessary for configuring Okta in [Step 2](#2-create-an-app-integration-in-okta). 1. In the Pinecone console, go to [**Settings > Manage**](https://app.pinecone.io/organizations/-/settings/manage). 2. In the **Single Sign-On** section, click **Enable SSO**. 3. In the **Setup SSO** dialog, copy the **Entity ID** and the **Assertion Consumer Service (ACS) URL**. You'll need these values in [Step 2](#2-create-an-app-integration-in-okta). 4. Click **Next**. Keep this window or browser tab open. You'll come back to it in [Step 4](#4-complete-sso-setup-in-pinecone). ## 2. Create an app integration in Okta In [Okta](https://login.okta.com/), follow these steps to create and configure a Pinecone app integration: 1. If you're not already on the Okta Admin console, navigate there by clicking the **Admin** button. 2. Navigate to **Applications > Applications**. 3. Click **Create App Integration**. 4. Select **SAML 2.0**. 5. Click **Next**. 6. Enter the **General Settings**: * **App name**: `Pinecone` * **App logo**: (optional) * **App visibility**: Set according to your organization's needs. 7. Click **Next**. 8. For **SAML Settings**, enter values you copied in [Step 1](#1-start-sso-setup-in-pinecone): * **Single sign-on URL**: Your **Assertion Consumer Service (ACS) URL** * **Audience URI (SP Entity ID)**: Your **Entity ID** * **Name ID format**: `EmailAddress` * **Application username**: `Okta username` * **Update application username on**: `Create and update` 9. In the **Attribute Statements** section, create the following attribute: * **Name**: `email` * **Value**: `user.email` 10. Click **Next**. 11. Click **Finish**. ## 3. Get the sign on URL and certificate from Okta Next, in Okta, get the URL and certificate for the Pinecone application you just created. You'll use these in [Step 4](#4-complete-sso-setup-in-pinecone). 1. In the Okta Admin console, navigate to **Applications > Pinecone > Sign On**. If you're continuing from the previous step, you should already be on the right page. 2. In the **SAML 2.0** section, expand **More details**. 3. Copy the **Sign on URL**. 4. Download the **Signing Certificate**. Download the certificate, don't copy it. The downloaded version contains necessary `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. ## 4. Complete SSO setup in Pinecone In the browser tab or window you kept open in [Step 1](#1-start-sso-setup-in-pinecone), complete the SSO setup in Pinecone: 1. In the **SSO Setup** window, enter the following values: * **Login URL**: The URL copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta). * **Email domain**: Your company's email domain. To target multiple domains, enter each domain separated by a comma. * **Certificate**: The contents of the certificate file you copied in [Step 3](#3-get-the-sign-on-url-and-certificate-from-okta). When pasting the certificate, be sure to include the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines. 2. Choose whether or not to **Enforce SSO for all users**. * If enabled, all members of your organization must use SSO to log in to Pinecone. * If disabled, members can choose to log in with SSO or with their Pinecone credentials. 3. Click **Next**. 4. Select a **Default role** for all users who log in with SSO. You can change user roles later. Okta is now ready to be used for single sign-on. Follow the [Okta docs](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-main.htm) to learn how to add users and groups. # Configure Private Endpoints for AWS PrivateLink Source: https://docs.pinecone.io/guides/production/connect-to-aws-privatelink Secure Pinecone with private VPC endpoints. This page describes how to create and use [Private Endpoints](/guides/production/security-overview#private-endpoints-for-aws-privatelink) to connect AWS PrivateLink to Pinecone while keeping your VPC private from the public internet. ## Use Private Endpoints to connect to PrivateLink ### Before you begin The following steps assume you have: * Access to the [AWS console](https://console.aws.amazon.com/console/home). * [Created an Amazon VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html#create-vpc-and-other-resources) in the same AWS [region](/guides/index-data/create-an-index#cloud-regions) as the index you want to connect to. You can optionally enable DNS hostnames and resolution, if you want your VPC to automatically discover the DNS CNAME for your PrivateLink and do not want configure a CNAME. * To [configure the routing](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-vpc-interface-endpoint.html) yourself, use one of Pinecone's DNS entry for the corresponding region: | Index region | Pinecone DNS entry | | ------------------------- | -------------------------------------- | | `us-east-1` (N. Virginia) | `*.private.aped-4627-b74a.pinecone.io` | | `us-west-2` (Oregon) | `*.private.apw5-4e34-81fa.pinecone.io` | | `eu-west-1` (Ireland) | `*.private.apu-57e2-42f6.pinecone.io` | * A [Pinecone Enterprise plan](https://www.pinecone.io/pricing/). * [Created a serverless index](/guides/index-data/create-an-index#create-a-serverless-index) in the same AWS [region](/guides/index-data/create-an-index#cloud-regions) as your Amazon VPC. Private Endpoints are configured at the project-level and you can add up to 10 endpoints per project. If you have multiple projects in your organization, Private Endpoints need to be set up separately for each. ### 1. Create an Amazon VPC endpoint In the [AWS console](https://console.aws.amazon.com/console/home): 1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/). 2. In the navigation pane, click **Endpoint**. 3. Click **Create endpoint**. 4. For **Service category**, select **Other endpoint services**. 5. In **Service settings**, enter the **Service name**, based on the region your Pinecone index is in: | Index region | Service name | | ------------------------- | --------------------------------------------------------- | | `us-east-1` (N. Virginia) | `com.amazonaws.vpce.us-east-1.vpce-svc-05ef6f1f0b9130b54` | | `us-west-2` (Oregon) | `com.amazonaws.vpce.us-west-2.vpce-svc-04ecb9a0e0d5aab01` | | `eu-west-1` (Ireland) | `com.amazonaws.vpce.eu-west-1.vpce-svc-03c6b7e17ff02a70f` | 6. Click **Verify service**. 7. Select the **VPC** to host the endpoint. 8. (Optional) In **Additional settings**, **Enable DNS name**. The enables you to access our service with the DNS name we configure. An additional CNAME record is needed if you disable this option. 9. Select the **Subnets** and **Subnet ID** for the endpoint. 10. Select the **Security groups** to apply to the endpoint. 11. Click **Create endpoint**. 12. Copy the **VPC endpoint ID** (e.g., `vpce-XXXXXXX`). This will be used to [add a Private Endpoint in Pinecone](#2-add-a-private-endpoint-in-pinecone). ### 2. Add a Private Endpoint in Pinecone To add a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. 3. Click **Add a connection**. 4. Select your VPC region. Only indexes in the selected region in this project will be affected. 5. Click **Next**. 6. Enter the AWS VPC endpoint ID you copied in the [section above](#create-an-amazon-vpc-endpoint). 7. Click **Next**. 8. (optional) To **enable VPC endpoint access only**, turn the toggle on. This can also be enabled later. For more information, see [Manage internet access to your project](#optional-manage-internet-access-to-your-project). 9. Click **Finish setup**. Private Endpoints only affect [data plane](/reference/api/latest/data-plane) access. [Control plane](/reference/api/latest/control-plane) access will continue over the public internet. ## Read and write data Once your private endpoint is configured, you can run data operations against an index as usual, but you must target the index using its private endpoint URL. The only difference in the URL is that `.svc.` is changed to `.svc.private.`. You can get the private endpoint URL for an index from the Pinecone console or API. To get the private endpoint URL for an index from the Pinecone console: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project containing the index. 3. Select the index. 4. Copy the URL under **PRIVATE ENDPOINT**. To get the private endpoint URL for an index from the API, use the [`describe_index`](/reference/api/latest/control-plane/describe_index) operation, which returns the private endpoint URL as the `private_host` value: ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); await pc.describeIndex('docs-example'); ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } idx, err := pc.DescribeIndex(ctx, "docs-example") if err != nil { log.Fatalf("Failed to describe index \"%v\": %v", idx.Name, err) } else { fmt.Printf("index: %v\n", prettifyStruct(idx)) } } ``` ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: YOUR_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` The response includes the private endpoint URL as the `private_host` value: ```json JavaScript {6} theme={null} { name: 'docs-example', dimension: 1536, metric: 'cosine', host: 'docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io', privateHost: 'docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io', deletionProtection: 'disabled', tags: { environment: 'production' }, embed: undefined, spec: { byoc: undefined, pod: undefined, serverless: { cloud: 'aws', region: 'us-east-1' } }, status: { ready: true, state: 'Ready' }, vectorType: 'dense' } ``` ```go Go {5} theme={null} index: { "name": "docs-example", "dimension": 1536, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "metric": "cosine", "deletion_protection": "disabled", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "status": { "ready": true, "state": "Ready" }, "tags": { "environment": "production" } } ``` ```json curl {12} theme={null} { "id": "025117b3-e683-423c-b2d1-6d30fbe5027f", "vector_type": "dense", "name": "docs-example", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "docs-example-jl7boae.svc.aped-4627-b74a.pinecone.io", "private_host": "docs-example-jl7boae.svc.private.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": { "environment": "production" } ``` If you run data operations against an index from outside the Private Endpoint, you will get an `Unauthorized` response. ## Manage internet access to your project Once your Private Endpoint is configured, you can turn off internet access to your project. To enable VPC endpoint access only: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to **Network > Access**. 4. Turn the **VPC endpoint access only** toggle on. This will turn off internet access to the project. This can be turned off at any point. This access control is set at the *project-level* and can unintentionally affect Pinecone indexes that communicate via the internet in the same project. Only indexes communicating through Private Endpoints will continue to work. ## Manage Private Endpoints In addition to [creating Private Endpoints](#2-add-a-private-endpoint-in-pinecone), you can also: * [View Private Endpoints](#view-private-endpoints) * [Delete a Private Endpoint](#delete-a-private-endpoint) ### View Private Endpoints To view Private Endpoints using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. A list of Private Endpoints displays with the associated **VPC ID** and **Cloud** provider. ### Delete a Private Endpoint To delete a Private Endpoint using the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to **Manage > Network**. 3. For the Private Endpoint you want to delete, click the *...* (Actions) icon. 4. Click **Delete**. 5. Enter the endpoint name. 6. Click **Delete Endpoint**. # Data deletion on Pinecone Source: https://docs.pinecone.io/guides/production/data-deletion Understand Pinecone's secure data deletion process. 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/concepts#record), [indexes](/guides/get-started/concepts#index), [backups](/guides/get-started/concepts#backup-or-collection), [projects](/guides/get-started/concepts#project), [API keys](/guides/get-started/concepts#api-key), [users](/guides/get-started/concepts#user), [assistants](/guides/get-started/concepts#pinecone-assistant), and [organizations](/guides/get-started/concepts#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. ## Soft deletion After you initiate a deletion request, Pinecone marks the data for deletion. The data is not immediately removed from the system. Instead, Pinecone retains the data for a maximum of 90 days. During this period, the data is not 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 is no longer recoverable. Pinecone creates an [audit log](/guides/production/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 are permanently deleted. ## See also * [Delete records](/guides/manage-data/delete-data) * [Delete an index](/guides/manage-data/manage-indexes#delete-an-index) * [Delete a project](/guides/projects/manage-projects#delete-a-project) * [Delete an API key](/guides/projects/manage-api-keys#delete-an-api-key) * [Delete a user](/guides/projects/manage-project-members#remove-members) * [Delete an organization](/troubleshooting/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 errors with retry logic and best practices. ## 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](/guides/projects/manage-api-keys). * **402 - Payment Required**: Your account has a payment issue. Check your billing status in the [console](https://app.pinecone.io). * **403 - Forbidden**: You've exceeded a [quota](/reference/api/database-limits#object-limits) or hit [deletion protection](/guides/manage-data/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 did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. **Best practice for 5xx errors**: [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). These errors are typically transient. ## Capture errors Each SDK provides error handling mechanisms specific to the language: ### Python SDK The Python SDK raises exceptions that you can catch and handle: ```python theme={null} from pinecone import Pinecone from pinecone.exceptions import PineconeException pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index("your-index") try: index.upsert( vectors=[ {"id": "vec1", "values": [0.1, 0.2, 0.3]} ] ) 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 theme={null} const { Pinecone } = require('@pinecone-database/pinecone'); const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); try { const index = pc.index('your-index'); await index.upsert([ { id: 'vec1', values: [0.1, 0.2, 0.3] } ]); } 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 SDK-specific error handling patterns, see the documentation for your language: * [Go SDK](/reference/go-sdk) * [Java SDK](/reference/java-sdk) * [.NET SDK](/reference/dotnet-sdk) ## 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 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: 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 try: simple_retry(lambda: index.upsert(vectors)) except Exception as e: print(f"Failed after {max_retries} attempts: {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 theme={null} import time import random 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', 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 try: exponential_backoff_retry(lambda: index.upsert(vectors)) except Exception as e: print(f"Failed after retries: {e}") ``` ### Key retry principles 1. **Add jitter**: Random variation in retry timing helps avoid thundering herd problems. 2. **Set max retries**: Prevent infinite retry loops. 3. **Cap delay time**: Don't wait indefinitely between retries. 4. **Don't retry client errors**: 4xx errors (except 429) won't resolve with retries. 5. **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 help protect your applications and maintain the health of the serverless infrastructure. **Most limits can be adjusted upon request**—if you need higher limits to scale, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. **Best practices**: * Implement exponential backoff as described above. * Proactively [monitor request metrics](/guides/production/monitoring) and reduce the request rate if you're approaching limits. * Use [batching](/guides/index-data/upsert-data#upsert-in-batches) to reduce the number of requests. * For high-throughput needs, see [Increase throughput](/guides/optimize/increase-throughput). ## Getting support If you've implemented error handling and retry logic but continue to experience issues: 1. Review [How to work with Support](/troubleshooting/how-to-work-with-support) for best practices. 2. Gather the following information: * Index name and project name * Error messages and stack traces * Timestamp of errors * Request/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. ## See also * [API error codes](/reference/api/errors) * [Database limits](/reference/api/database-limits) * [Assistant limits](/reference/api/assistant/assistant-limits) * [Monitoring](/guides/production/monitoring) * [Production checklist](/guides/production/production-checklist) # Monitor performance Source: https://docs.pinecone.io/guides/production/monitoring Monitor performance metrics in the Pinecone console or with Prometheus or 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. ## 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). This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ## Monitor with Prometheus This feature is available on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). When using [Bring Your Own Cloud](/guides/production/bring-your-own-cloud), you must configure Prometheus monitoring within your VPC. To monitor all 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: 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](/guides/projects/understanding-projects#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](/guides/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_op_upsert_total` | counter | The number of [upsert](/guides/index-data/upsert-data) requests made to an index. | | `pinecone_db_op_upsert_duration_total` | counter | The total time taken processing upsert requests for an index in milliseconds. | | `pinecone_db_op_query_total` | counter | The number of [query](/guides/search/search-overview) requests made to an index. | | `pinecone_db_op_query_duration_total` | counter | The total time taken processing [query](/guides/search/search-overview) requests for an index in milliseconds. | | `pinecone_db_op_fetch_total` | counter | The number of [fetch](/guides/manage-data/fetch-data) requests made to an index. | | `pinecone_db_op_fetch_duration_total` | counter | The total time taken processing fetch requests for an index in milliseconds. | | `pinecone_db_op_update_total` | counter | The number of [update](/guides/manage-data/update-data) requests made to an index. | | `pinecone_db_op_update_duration_total` | counter | The total time taken processing update requests for an index in milliseconds. | | `pinecone_db_op_delete_total` | counter | The number of [delete](/guides/manage-data/delete-data) requests made to an index. | | `pinecone_db_op_delete_duration_total` | counter | The total time taken processing delete requests for an index in milliseconds. | | `pinecone_db_write_unit_total` | counter | The total number of [write units](/guides/manage-cost/understanding-cost#write-units) consumed by an index. | | `pinecone_db_read_unit_total` | counter | The total number of [read units](/guides/manage-cost/understanding-cost#read-units) consumed by an index. | | `pinecone_db_storage_size_bytes` | gauge | The total size of the index in bytes. | ### 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`. | ### 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"} ``` Return the total number of upsert requests per index: ```shell theme={null} sum by (index_name) (pinecone_db_op_upsert_total) ``` Return the average processing time in millisconds for upsert requests per index: ```shell theme={null} sum by (index_name) (pinecone_db_op_upsert_duration_total/pinecone_db_op_upsert_total) ``` Return the total read units consumed per index: ```shell theme={null} sum by (index_name) (pinecone_db_read_unit_total) ``` Return the total write units consumed for the Pinecone index `docs-example`: ```shell theme={null} pinecone_db_write_unit_total{index_name="docs-example"} ``` # Production checklist Source: https://docs.pinecone.io/guides/production/production-checklist Prepare your indexes for production with best practices. 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](/guides/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](/guides/projects/understanding-projects#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](/guides/projects/manage-api-keys) and using API key permissions. Consider how best to [manage the API keys](/guides/projects/manage-api-keys) associated with your production project. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. ## Enforce security Use Pinecone's [security features](/guides/production/security-overview) to protect your production data: * Data security * Private endpoints * Customer-managed encryption keys (CMEK) * 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/index-data/import-data) for the most efficient and cost-effective ingestion. For ongoing ingestion, [upsert in batches](/guides/index-data/upsert-data#upsert-in-batches) to optimize speed and efficiency. See the [data ingestion overview](/guides/index-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/index-data/data-modeling#use-structured-ids) (e.g., `document_id#chunk_number`) for efficient operations. Design [metadata](/guides/index-data/data-modeling#include-metadata) to support filtering, linking related chunks, and traceability. See the [data modeling guide](/guides/index-data/data-modeling) for details. * **Namespaces**: When indexing, try to [use namespaces to keep your data among tenants separate](/guides/index-data/implement-multitenancy), and do not 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/index-data/data-modeling) accordingly. * **Index limits**: Plan for index capacity based on your [plan tier](https://www.pinecone.io/pricing/). Use [namespaces](/guides/index-data/implement-multitenancy) to partition data within indexes rather than creating multiple indexes. * **Plan limits**: Starter plans have monthly read/write unit limits. Upgrade to Standard or Enterprise for unlimited read/write units and higher throughput needs. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ## 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 leverage 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. ## Backup up your indexes In order 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/manage-data/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/monitoring). ## Configure CI/CD Use [Pinecone in CI/CD](/guides/production/automated-testing) to safely test changes before deploying them to production. ## 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. # Security overview Source: https://docs.pinecone.io/guides/production/security-overview Understand Pinecone's security features, including authentication, encryption, and audit logs. ## Access management ### API keys Each Pinecone [project](/guides/projects/understanding-projects) has one or more [API keys](/guides/projects/manage-api-keys). In order to make calls to the Pinecone API, a user must provide a valid API key for the relevant Pinecone project. You can [manage API key permissions](/guides/projects/manage-api-keys) in the [Pinecone console](https://app.pinecone.io/organizations/-/projects/-/keys). The available permission roles are as follows: #### General permissions | Role | Permissions | | :--- | :---------------------------------------------- | | All | Permissions to read and write all project data. | | Role | Permissions | | :-------------- | :----------------------------------------------- | | `ProjectEditor` | Permissions to read and write all project data. | | `ProjectViewer` | Permissions to read all project data. | #### Control plane permissions | Role | Permissions | | :-------- | :---------------------------------------------------------------------------------------------------------- | | ReadWrite | Permissions to list, describe, create, delete, and configure indexes, backups, collections, and assistants. | | ReadOnly | Permissions to list and describe indexes, backups, collections, and assistants. | | None | No 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 | | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ReadWrite |
  • Indexes: Permissions to query, import, fetch, add, update, and delete index data.
  • Pinecone Assistant: Permissions to add, list, view, and delete files; chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | ReadOnly |
  • Indexes: Permissions to query, fetch, list ID, and view stats.
  • Pinecone Assistant: Permissions to list and view files, chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | None | No data plane permissions. | | Role | Permissions | | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DataPlaneEditor` |
  • Indexes: Permissions to query, import, fetch, add, update, and delete index data.
  • Pinecone Assistant: Permissions to add, list, view, and delete files; chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | `DataPlaneViewer` |
  • Indexes: Permissions to query, fetch, list ID, and view stats.
  • Pinecone Assistant: Permissions to list and view files, chat with an assistant, and evaluate responses.
  • Pinecone Inference: Permissions to generate embeddings and rerank documents.
| | None | No data plane permissions. | ### 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 require that users from your domain sign in through SSO, and you can specify a default role for teammates when they sign up. SSO is available on Standard and Enterprise plans. For more information, see [configure single sign on](/guides/production/configure-single-sign-on/okta). ### Role-based access controls (RBAC) Pinecone uses role-based access controls (RBAC) to manage access to resources. Service accounts, API keys, and users are all *principals*. A principal's access is determined by the *roles* assigned to it. Roles are assigned to a principal for a *resource*, either a project or an organization. The roles available to be assigned depend on the type of principal and resource. #### Service account roles A service account can be assigned roles for the organization it belongs to, and any projects within that organization. For more information, see [Organization roles](/guides/organizations/understanding-organizations#organization-roles) and [Project roles](/guides/projects/understanding-projects#project-roles). #### API key roles An API key can only be assigned permissions for the projects it belongs to. For more information, see [API keys](#api-keys). #### User roles A user can be assigned roles for each organization they belong to, and any projects within that organization. For more information, see [Organization roles](/guides/organizations/understanding-organizations#organization-roles) and [Project roles](/guides/projects/understanding-projects#project-roles). ## Compliance To learn more about data privacy and compliance at Pinecone, visit the [Pinecone Trust and Security Center](https://security.pinecone.io/). ### Audit logs To enable and manage audit logs, you must be an [organization owner](/guides/organizations/understanding-organizations#organization-roles). This feature is available only on [Enterprise plans](https://www.pinecone.io/pricing/). [Audit logs](/guides/production/configure-audit-logs) provide a detailed record of user and API actions that occur within Pinecone. Events are captured every 30 minutes and each log batch will be saved into its own file as a JSON blob, keyed by the time of the log to be written. Only logs since the integration was created and enabled will be saved. Audit log events adhere to a standard JSON schema and include the following fields: ```json JSON theme={null} { "id": "00000000-0000-0000-0000-000000000000", "organization_id": "AA1bbbbCCdd2EEEe3FF", "organization_name": "example-org", "client": { "userAgent": "rawUserAgent" }, "actor": { "principal_id": "00000000-0000-0000-0000-000000000000", "principal_name": "example@pinecone.io", "principal_type": "user", // user, api_key, service_account "display_name": "Example Person" // Only in case of user }, "event": { "time": "2024-10-21T20:51:53.697Z", "action": "create", "resource_type": "index", "resource_id": "uuid", "resource_name": "docs-example", "outcome": { "result": "success", "reason": "", // Only displays for "result": "failure" "error_code": "", // Only displays for "result": "failure" }, "parameters": { // Varies based on event } } } ``` The following events are captured in the audit logs: * [Organization events](#organization-events) * [Project events](#project-events) * [Index events](#index-events) * [User and API key events](#user-and-api-key-events) * [Security and governance events](#security-and-governance-events) #### Organization events | Action | Query parameters | | ----------------- | -------------------------------------------------------------------------------------------------------------- | | Rename org | `event.action: update`, `event.resource_type: organization`, `event.resource_id: NEW_ORG_NAME` | | Delete org | `event.action: delete`, `event.resource_type: organization`, `event.resource_id: DELETED_ORG_NAME` | | Create org member | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]` | | Update org member | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }` | | Delete org member | `event.action: delete`, `event.resource_type: user`, `event.resource_id: USER_EMAIL` | #### Project events | Action | Query parameters | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Create project | `event.action: create`, `event.resource_type: project`, `event.resouce_id: PROJ_NAME` | | Update project | `event.action: update`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME` | | Delete project | `event.action: delete`, `event.resource_type: project`, `event.resource_id: PROJECT_NAME` | | Invite project member | `event.action: create`, `event.resource_type: user`, `event.resource_id: [ARRAY_OF_USER_EMAILS]` | | Update project member role | `event.action: update`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, role: NEW_ROLE }` | | Delete project member | `event.action: delete`, `event.resource_type: user`, `event.resource_id: { user: USER_EMAIL, project: PROJ_NAME }` | #### Index events | Action | Query parameters | | ------------- | --------------------------------------------------------------------------------------- | | Create index | `event.action: create`, `event.resource_type: index`, `event.resouce_id: INDEX_NAME` | | Update index | `event.action: update`, `event.resource_type: index`, `event.resource_id: INDEX_NAME` | | Delete index | `event.action: delete`, `event.resource_type: index`, `event.resource_id: INDEX_NAME` | | Create backup | `event.action: create`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` | | Delete backup | `event.action: delete`, `event.resource_type: backup`, `event.resource_id: BACKUP_NAME` | #### User and API key events | Action | Query parameters | | -------------- | --------------------------------------------------------------------------------------- | | User login | `event.action: login`, `event.resource_type: user`, `event.resouce_id: USERNAME` | | Create API key | `event.action: create`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` | | Delete API key | `event.action: delete`, `event.resource_type: api-key`, `event.resource_id: API_KEY_ID` | #### Security and governance events | Action | Query parameters | | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | Create Private Endpoint | `event.action: create`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` | | Delete Private Endpoint | `event.action: delete`, `event.resource_type: private-endpoints`, `event.resource_id: PRIVATE_ENDPOINT_ID` | ## Data protection ### Customer-managed encryption keys (CMEK) This feature is in [public preview](/release-notes/feature-availability). Data within a Pinecone project can be encrypted using [customer-managed encryption keys (CMEK)](/guides/production/configure-cmek). This 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. ### Backup and recovery This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). A backup is a static copy of your index that only consumes storage. It is a non-queryable representation of a set of records. You can [create a backup](/guides/manage-data/back-up-an-index) of an index, and you can [create a new index from a backup](/guides/manage-data/restore-an-index). This allows you to restore the index with the same or different configurations. For more information, see [Understanding backups](/guides/manage-data/backups-overview). ### Encryption at rest Pinecone encrypts stored data using the 256-bit Advanced Encryption Standard (AES-256) encryption algorithm. ### Encryption in transit Pinecone uses standard protocols to encrypt user data in transit. Clients open HTTPS or gRPC connections to the Pinecone API; the Pinecone API gateway uses gRPC connections to user deployments in the cloud. These HTTPS and gRPC connections use the TLS 1.2 protocol with 256-bit Advanced Encryption Standard (AES-256) encryption. Diagram showing encryption protocols for user data in transit Traffic is also encrypted in transit between the Pinecone backend and cloud infrastructure services, such as S3 and GCS. For more information, see [Google Cloud Platform](https://cloud.google.com/docs/security/encryption-in-transit) and [AWS security documentation](https://docs.aws.amazon.com/AmazonS3/userguide/UsingEncryption.html). ## Network security ### Private Endpoints for AWS PrivateLink Use [Private Endpoints to connect to Amazon Web Services (AWS) PrivateLink](/guides/production/connect-to-aws-privatelink). This establishes private connectivity between your Pinecone serverless indexes and supported AWS services while keeping your VPC private from the public internet. PrivateLink diagram Private Endpoints are additive to other Pinecone security features: data is also [encrypted in transit](#encryption-in-transit), [encrypted at rest](#encryption-at-rest), and an [API key](#api-keys) is required to authenticate. ### Proxies The following Pinecone SDKs support the use of proxies: * [Python SDK](/reference/python-sdk#proxy-configuration) * [Node.js SDK](/reference/node-sdk#proxy-configuration) # Create a project Source: https://docs.pinecone.io/guides/projects/create-a-project Create a new Pinecone project in your organization. This page shows you how to create a project. If you are an [organization owner or user](/guides/organizations/understanding-organizations#organization-roles), you can create a project in your organization: 1. In the Pinecone console, go to [**your profile > Organization settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click **+ Create Project**. 3. Enter a **Name**. A project name can contain up to 512 characters. For more information, see [Object identifiers](/reference/api/database-limits#identifier-limits). 4. (Optional) Tags are key-value pairs that you can use to categorize and identify the project. To add a tag, click **+ Add tag** and enter a tag key and value. 5. (Optional) Select **Encrypt with Customer Managed Encryption Key**. For more information, see [Configure CMEK](/guides/production/configure-cmek). 6. Click **Create project**. To load an index with a [sample dataset](/guides/data/use-sample-datasets), click **Load sample data** and follow the prompts. Organizations on the Starter plan are limited to one project. To create additional projects, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/projects" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name":"example-project" }' ``` ```bash CLI theme={null} # Target the organization for which you want to # create a project. pc target -o "example-org" # Create the project and set it as the target # project for the CLI. pc project create -n "example-project" --target ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-03-16T22:46:45.030Z" } ``` ```text CLI theme={null} [SUCCESS] Project example-cli-project created successfully. ATTRIBUTE VALUE Name example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 [SUCCESS] Target project set to example-cli-project ``` ## Next steps * [Add users to your project](/guides/projects/manage-project-members#add-members-to-a-project) * [Create an index](/guides/index-data/create-an-index) # Manage API keys Source: https://docs.pinecone.io/guides/projects/manage-api-keys Create and manage API keys with custom permissions. Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. This page shows you how to [create](#create-an-api-key), [view](#view-api-keys), [change permissions for](#change-api-key-permissions), and [delete](#delete-an-api-key) API keys. If you use custom API key permissions, ensure that you [target your index by host](/guides/manage-data/target-an-index#target-by-index-host-recommended) when performing data operations such as `upsert` and `query`. ## Create an API key You can create a new API key for your project, as follows: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to **API keys**. 4. Click **Create API key**. 5. Enter an **API key name**. 6. Select the **Permissions** to grant to the API key. For a description of the permission roles, see [API key permissions](/guides/production/security-overview#api-keys). Users on the Starter plan can set the permissions to **All** only. To customize the permissions further, [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). 7. Click **Create key**. 8. Copy and save the generated API key in a secure place for future use. You will not be able to see the API key again after you close the dialog. 9. Click **Close**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_PROJECT_ID="YOUR_PROJECT_ID" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X POST "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "example-api-key", "roles": ["ProjectEditor"] }' ``` ```bash CLI theme={null} # Target the project for which you want to create an API key. pc target -o "example-org" -p "example-project" # Create the API key pc api-key create -n "example-api-key" --roles ProjectEditor ``` The example returns a response like the following: ```json curl theme={null} { "key": { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:40:27.069075Z" }, "value": "..." } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-api-key ID 62b0dbfe-3489-4b79-b850-34d911527c88 Value ... Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## View project API keys You can [view the API keys](/reference/api/latest/admin/list_api_keys) for your project: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. You will see a list of all API keys for the project, including their names, IDs, and permissions. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```bash CLI theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" pc api-key list -i $PINECONE_PROJECT_ID ``` The example returns a response like the following: ```json curl theme={null} { "data": [ { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:39:43.665754Z" }, { "id": "0d0d3678-81b4-4e0d-a4f0-70ba488acfb7", "name": "example-api-key-2", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-20T23:43:13.176422Z" } ] } ``` ```text CLI theme={null} Organization: example-organization (ID: -NM7af6f234168c4e44a) Project: example-project (ID: 32c8235a-5220-4a80-a9f1-69c24109e6f2) API Keys NAME ID PROJECT ID ROLES example-api-key 62b0dbfe-3489-4b79-b850-34d911527c88 32c8235a-5220-4a80-a9f1-69c24109e6f2 ProjectEditor example-api-key-2 0d0d3678-81b4-4e0d-a4f0-70ba488acfb7 32c8235a-5220-4a80-a9f1-69c24109e6f2 ProjectEditor ``` ## View API key details You can [view the details of an API key](/reference/api/latest/admin/fetch_api_key): 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**. You will see the API key's name, ID, and permissions. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" pc api-key describe -i $PINECONE_API_KEY_ID ``` The example returns a response like the following: ```json curl theme={null} { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "example-api-key", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-22T19:27:21.202955Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-api-key ID 62b0dbfe-3489-4b79-b850-34d911527c88 Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## Update an API key Users on the Starter plan cannot change API key permissions once they are set. Instead, [create a new API key](#create-an-api-key) or [upgrade to the Standard or Enterprise plan](/guides/organizations/manage-billing/upgrade-billing-plan). If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can update the name and roles of an API key: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Settings**. 5. Change the name and/or permissions for the API key as needed. For information about the different API key permissions, refer to [Understanding security - API keys](/guides/production/security-overview#api-keys). 6. Click **Update**. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "new-api-key-name", "roles": ["ProjectEditor"] }' ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" # Target the organization that contains the API key. pc target -o "example-org" # Update the API key name. pc api-key update -i $PINECONE_API_KEY_ID -n "new-api-key-name" ``` The example returns a response like the following: ```json curl theme={null} { "id": "62b0dbfe-3489-4b79-b850-34d911527c88", "name": "new-api-key-name", "project_id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "roles": [ "ProjectEditor" ], "created_at": "2025-10-22T19:27:21.202955Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name new-api-key-name ID 62b0dbfe-3489-4b79-b850-34d911527c88 Project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Roles ProjectEditor ``` ## Delete an API key If you are a [project owner](/guides/projects/understanding-projects#project-roles), you can delete your API key: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select your project. 3. Go to the **API keys** tab. 4. In the row of the API key you want to change, in the **Actions** column, click **ellipsis (...) menu > Delete**. 5. Enter the **API key name**. 6. Click **Confirm deletion**. Deleting an API key is irreversible and will immediately disable any applications using the API key. An [access token](/guides/organizations/manage-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/release-notes/feature-availability). ```bash curl theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```bash CLI theme={null} PINECONE_API_KEY_ID="62b0dbfe-3489-4b79-b850-34d911527c88" # Delete the API key. Use --skip-confirmation to skip # the confirmation prompt. pc api-key delete -i $PINECONE_API_KEY_ID ``` The example returns a response like the following: ```text curl theme={null} No response payload ``` ```text CLI theme={null} [WARN] This operation will delete API key example-api-key from project example-project. [WARN] Any integrations that authenticate with this API key will immediately stop working. [WARN] This action cannot be undone. Do you want to continue? (y/N): y [INFO] You chose to continue delete. [SUCCESS] API key example-api-key deleted ``` # Manage project members Source: https://docs.pinecone.io/guides/projects/manage-project-members Add and manage project members with role-based access control. [Organization owners](/guides/organizations/understanding-organizations#organization-roles) or [project owners](#project-roles) can manage members in a project. Members can be added to a project with different [roles](/guides/projects/understanding-projects#project-roles), which determine their permissions within the project. For information about managing members at the **organization-level**, see [Manage organization members](/guides/organizations/manage-organization-members). ## Add members to a project You can add members to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. Enter the member's email address or name. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. The role determines the member's permissions within Pinecone. 5. Click **Invite**. When you invite a member to join your project, Pinecone sends them an email containing a link that enables them to gain access to the project. If they already have a Pinecone account, they still receive an email, but they can also immediately view the project. ## Change a member's role You can change a member's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. In the row of the member you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the member. 5. Click **Edit role**. ## Remove a member You can remove a member from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Members** tab](https://app.pinecone.io/organizations/-/projects/-/access/members). 3. In the row of the member you want to remove, click **ellipsis (...) menu > Remove member**. 4. Click **Remove member**. To remove yourself from a project, click the **Leave project** button in your user's row and confirm. # Manage projects Source: https://docs.pinecone.io/guides/projects/manage-projects View, rename, and delete projects in your organization. This page shows you how to view project details, rename a project, and delete a project. You must be an [organization owner](/guides/assistant/admin/organizations-overview#organization-roles) or [project owner](/guides/assistant/admin/projects-overview#project-roles) to edit project details or delete a project. ## View project details You can view the details of a project, as in the following example: An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability). ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```bash CLI theme={null} PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" # Target the organization that contains the project. pc target -o "example-org" # Fetch the project details. pc project describe -i $PROJECT_ID ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-10-27T23:27:46.370088Z" } ``` ```text CLI theme={null} ATTRIBUTE VALUE Name example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 ``` You can view project details using the [Pinecone console](https://app.pinecone.io/organizations/-/settings/projects/-/indexes). ## Rename a project You can change the name of your project: 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update. 3. Enter a new **Project Name**. A project name can contain up to 512 characters. 4. Click **Save Changes**. An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability). ```bash curl theme={null} PROJECT_ID="YOUR_PROJECT_ID" PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl -X PATCH "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "accept: application/json" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "updated-example-project" }' ``` ```bash CLI theme={null} PROJECT_ID="YOUR_PROJECT_ID" # Target the project to update. pc target -o "example-org" "example-project" # Update the project name. pc project update -i $PROJECT_ID -n "updated-example-project" ``` The example returns a response like the following: ```json curl theme={null} { "id": "32c8235a-5220-4a80-a9f1-69c24109e6f2", "name": "updated-example-project", "max_pods": 5, "force_encryption_with_cmek": false, "organization_id": "-NM7af6f234168c4e44a", "created_at": "2025-10-27T23:27:46.370088Z" } ``` ```text CLI theme={null} [SUCCESS] Project 32c8235a-5220-4a80-a9f1-69c24109e6f2 updated successfully. ATTRIBUTE VALUE Name updated-example-project ID 32c8235a-5220-4a80-a9f1-69c24109e6f2 Organization ID -NM7af6f234168c4e44a Created At 2025-10-27 23:27:46.370088 +0000 UTC Force Encryption false Max Pods 5 ``` ## Add project tags Project tags are key-value pairs that you can use to categorize and identify a project. To add project tags, use the Pinecone console. 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. Click the **ellipsis (...) menu > Configure** icon next to the project you want to update. 3. Click **+ Add tag** and enter a tag key and value. Repeat for each tag you want to add. 4. Click **Save Changes**. You can also [add tags to indexes](/guides/manage-data/manage-indexes#configure-index-tags). ## Delete a project To delete a project, you must first [delete all data](/guides/manage-data/delete-data), [indexes](/guides/manage-data/manage-indexes#delete-an-index), [collections](/guides/indexes/pods/back-up-a-pod-based-index#delete-a-collection), [backups](/guides/manage-data/back-up-an-index#delete-a-backup) and [assistants](/guides/assistant/manage-assistants#delete-an-assistant) associated with the project. Then, you can delete the project itself: 1. In the Pinecone console, go to [**Settings > Projects**](https://app.pinecone.io/organizations/-/settings/projects). 2. For the project you want to delete, click the **ellipsis (...) menu > Delete**. 3. Enter the project name to confirm the deletion. 4. Click **Delete Project**. An [access token](/guides/assistant/admin/manage-organization-service-accounts#retrieve-an-access-token) must be provided to complete this action through the Admin API. The Admin API is in [public preview](/assistant-release-notes/feature-availability). ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` ```bash CLI theme={null} PINECONE_PROJECT_ID="32c8235a-5220-4a80-a9f1-69c24109e6f2" # Target the organization that contains the project. pc target -o "example-org" # Delete the project. Use --skip-confirmation to skip # the confirmation prompt. pc project delete -i $PINECONE_PROJECT_ID ``` # Manage service accounts at the project-level Source: https://docs.pinecone.io/guides/projects/manage-service-accounts Enable service accounts for programmatic API access. This feature is in [public preview](/release-notes/feature-availability) and available only on [Enterprise plans](https://www.pinecone.io/pricing/). This page shows how [organization owners](/guides/organizations/understanding-organizations#organization-roles) and [project owners](/guides/projects/understanding-projects#project-roles) can add and manage service accounts at the project-level. Service accounts enable programmatic access to Pinecone's Admin API, which can be used to create and manage projects and API keys. ## Add a service account to a project After a service account has been [added to an organization](/guides/organizations/manage-service-accounts#create-a-service-account), it can be added to a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. Select the service account to add. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account. The role determines its permissions within Pinecone. 5. Click **Connect**. ## Change project role To change a service account's role in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. In the row of the service account you want to edit, click **ellipsis (...) menu > Edit role**. 4. Select a [**Project role**](/guides/projects/understanding-projects#project-roles) for the service account. 5. Click **Edit role**. ## Remove a service account from a project To remove a service account from a project in the [Pinecone console](https://app.pinecone.io/organizations/-/projects): 1. Select your project. 2. Go to the [**Manage > Access > Service accounts** tab](https://app.pinecone.io/organizations/-/projects/-/access/service-accounts). 3. In the row of the service account you want to remove, click **ellipsis (...) menu > Disconnect**. 4. Enter the service account name to confirm. 5. Click **Disconnect**. # Understanding projects Source: https://docs.pinecone.io/guides/projects/understanding-projects Learn about projects, environments, and member roles. A Pinecone project belongs to an [organization](/guides/organizations/understanding-organizations) and contains a number of [indexes](/guides/index-data/indexing-overview) and users. Only a user who belongs to the project can access the indexes in that project. Each project also has at least one project owner. ## Project environments You choose a cloud environment for each index in a project. This makes it easy to manage related resources across environments and use the same API key to access them. ## Project roles If you are an [organization owner](/guides/organizations/understanding-organizations#organization-roles) or project owner, you can manage members in your project. Project members are assigned a role, which determines their permissions within the project. The project roles are as follows: * **Project owner**: Project owners have global permissions across projects they own. * **Project user**: Project users have restricted permissions for the specific projects they are invited to. The following table summarizes the permissions for each project role: | Permission | Owner | User | | :-------------------------- | ----- | ---- | | Update project names | ✓ | | | Delete projects | ✓ | | | View project members | ✓ | ✓ | | Update project member roles | ✓ | | | Delete project members | ✓ | | | View API keys | ✓ | ✓ | | Create API keys | ✓ | | | Delete API keys | ✓ | | | View indexes | ✓ | ✓ | | Create indexes | ✓ | ✓ | | Delete indexes | ✓ | ✓ | | Upsert vectors | ✓ | ✓ | | Query vectors | ✓ | ✓ | | Fetch vectors | ✓ | ✓ | | Update a vector | ✓ | ✓ | | Delete a vector | ✓ | ✓ | | List vector IDs | ✓ | ✓ | | Get index stats | ✓ | ✓ | Specific to pod-based indexes: Customers who sign up for a Standard or Enterprise plan on or after August 18, 2025 cannot create pod-based indexes. Instead, create [serverless indexes](/guides/index-data/create-an-index), and consider using [dedicated read nodes](/guides/index-data/dedicated-read-nodes) for large workloads (millions of records or more, and moderate or high query rates). | Permission | Owner | User | | :------------------------ | ----- | ---- | | Update project pod limits | ✓ | | | View project pod limits | ✓ | ✓ | | Update index size | ✓ | ✓ | ## API keys Each Pinecone [project](/guides/projects/understanding-projects) has one or more API keys. In order to [make calls to the Pinecone API](/guides/get-started/quickstart), you must provide a valid API key for the relevant Pinecone project. For more information, see [Manage API keys](/guides/projects/manage-api-keys). ## Project IDs Each Pinecone project has a unique product ID. To find the ID of a project, go to the project list in the [Pinecone console](https://app.pinecone.io/organizations/-/projects). ## See also * [Understanding organizations](guides/organizations/understanding-organizations) * [Manage organization members](guides/organizations/manage-organization-members) # Filter by metadata Source: https://docs.pinecone.io/guides/search/filter-by-metadata Narrow search results with metadata filtering. export const word_0 = "vectors" Every [record](/guides/get-started/concepts#record) in an index must contain an ID and a dense or sparse vector. In addition, you can include [metadata key-value pairs](/guides/index-data/indexing-overview#metadata) to store related information or context. When you search the index, you can then include a metadata filter to limit the search to records matching the filter expression. ## Search with a metadata filter The following code searches for the 3 records that are most semantically similar to a query and that have a `category` metadata field with the value `digestive system`. Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") filtered_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 3, "filter": {"category": "digestive system"}, }, fields=["category", "chunk_text"] ) print(filtered_results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 3, inputs: { text: "Disease prevention" }, filter: { category: "digestive system" } }, fields: ['chunk_text', 'category'] }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); Map filter = new HashMap<>(); filter.put("category", "digestive system"); // Search the dense index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 3, filter, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } metadataMap := map[string]interface{}{ "category": map[string]interface{}{ "$eq": "digestive system", }, } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, Filter: &metadataMap, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 4, Inputs = new Dictionary { { "text", "Disease prevention" } }, Filter = new Dictionary { ["category"] = new Dictionary { ["$eq"] = "digestive system" } } }, Fields = ["category", "chunk_text"], } ); Console.WriteLine(response); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 3, "filter": {"category": "digestive system"} }, "fields": ["category", "chunk_text"] }' ``` ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, filter={ "category": {"$eq": "digestive system"} }, include_metadata=True, include_values=False ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], topK: 3, filter: { "category": { "$eq": "digestive system" } } includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import com.google.protobuf.Struct; import com.google.protobuf.Value; import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f); Struct filter = Struct.newBuilder() .putFields("category", Value.newBuilder() .setStructValue(Struct.newBuilder() .putFields("$eq", Value.newBuilder() .setStringValue("digestive system") .build())) .build()) .build(); QueryResponseWithUnsignedIndices queryResponse = index.query(1, query, null, null, null, "example-namespace", filter, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875} metadataMap := map[string]interface{}{ "category": map[string]interface{}{ "$eq": "digestive system", } } metadataFilter, err := structpb.NewStruct(metadataMap) if err != nil { log.Fatalf("Failed to create metadata map: %v", err) } res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, MetadataFilter: metadataFilter, IncludeValues: false, includeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var queryResponse = await index.QueryAsync(new QueryRequest { Vector = new[] { 0.0236663818359375f ,-0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f }, Namespace = "example-namespace", TopK = 3, Filter = new Metadata { ["category"] = new Metadata { ["$eq"] = "digestive system", } }, IncludeMetadata = true, }); Console.WriteLine(queryResponse); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], "namespace": "example-namespace", "topK": 3, "filter": {"category": {"$eq": "digestive system"}}, "includeMetadata": true, "includeValues": false }' ``` ## Metadata filter expressions Pinecone's filtering language supports the following operators: | Operator | Function | Supported types | | :-------- | :--------------------------------------------------------------------------------------------------------------------------------- | :---------------------- | | `$eq` | Matches {word_0} with metadata values that are equal to a specified value. Example: `{"genre": {"$eq": "documentary"}}` | Number, string, boolean | | `$ne` | Matches {word_0} with metadata values that are not equal to a specified value. Example: `{"genre": {"$ne": "drama"}}` | Number, string, boolean | | `$gt` | Matches {word_0} with metadata values that are greater than a specified value. Example: `{"year": {"$gt": 2019}}` | Number | | `$gte` | Matches {word_0} with metadata values that are greater than or equal to a specified value. Example:`{"year": {"$gte": 2020}}` | Number | | `$lt` | Matches {word_0} with metadata values that are less than a specified value. Example: `{"year": {"$lt": 2020}}` | Number | | `$lte` | Matches {word_0} with metadata values that are less than or equal to a specified value. Example: `{"year": {"$lte": 2020}}` | Number | | `$in` | Matches {word_0} with metadata values that are in a specified array. Example: `{"genre": {"$in": ["comedy", "documentary"]}}` | String, number | | `$nin` | Matches {word_0} with metadata values that are not in a specified array. Example: `{"genre": {"$nin": ["comedy", "documentary"]}}` | String, number | | `$exists` | Matches {word_0} with the specified metadata field. Example: `{"genre": {"$exists": true}}` | Number, string, boolean | | `$and` | Joins query clauses with a logical `AND`. Example: `{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | | `$or` | Joins query clauses with a logical `OR`. Example: `{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}` | - | Only `$and` and `$or` are allowed at the top level of the query expression. For example, the following has a `"genre"` metadata field with a list of strings: ```JSON JSON theme={null} { "genre": ["comedy", "documentary"] } ``` This means `"genre"` takes on both values, and requests with the following filters will match: ```JSON JSON theme={null} {"genre":"comedy"} {"genre": {"$in":["documentary","action"]}} {"$and": [{"genre": "comedy"}, {"genre":"documentary"}]} ``` However, requests with the following filter will **not** match: ```JSON JSON theme={null} { "$and": [{ "genre": "comedy" }, { "genre": "drama" }] } ``` Additionally, requests with the following filters will **not** match because they are invalid. They will result in a compilation error: ```json JSON theme={null} # INVALID QUERY: {"genre": ["comedy", "documentary"]} ``` ```json JSON theme={null} # INVALID QUERY: {"genre": {"$eq": ["comedy", "documentary"]}} ``` # Hybrid search Source: https://docs.pinecone.io/guides/search/hybrid-search Combine semantic and lexical search for better results. [Semantic search](/guides/search/semantic-search) and [lexical search](/guides/search/lexical-search) are powerful information retrieval techniques, but each has notable limitations. For example, semantic search can miss results based on exact keyword matches, especially in scenarios involving domain-specific terminology, while lexical search can miss results based on relationships, such as synonyms and paraphrases. This page shows you how to lift these limitations by combining semantic and lexical search. This is often called hybrid search. ## Hybrid search approaches There are two ways to perform hybrid search in Pinecone: * [Use separate dense and sparse indexes](#use-separate-dense-and-sparse-indexes). This is the **recommended** approach because it provides the most flexibility. * [Use a single hybrid index](#use-a-single-hybrid-index). This approach is simpler to implement but doesn't support a few useful features. The following table summarizes the pros and cons between the two approaches: | Approach | Pros | Cons | | :-------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Separate dense and sparse indexes |
  • You can start with dense for semantic search and add sparse for lexical search later.
  • You can do sparse-only queries.
  • You can rerank at multiple levels (for each index and for merged results).
  • You can use integrated embedding and reranking.
|
  • You need to manage and make requests to two separate indexes.
  • You need to maintain the linkage between sparse and dense vectors in different indexes.
| | Single hybrid index |
  • You make requests to only a single index.
  • The linkage between dense and sparse vectors is implicit.
|
  • You can't do sparse-only queries.
  • You can't use integrated embedding and reranking.
| ## Use separate dense and sparse indexes This is the recommended way to perform hybrid search in Pinecone. You create separate dense and sparse indexes, upsert dense vectors into the dense index and sparse vectors into the sparse index, and search each index separately. Then you combine and deduplicate the results, use one of Pinecone's [hosted reranking models](/guides/search/rerank-results#reranking-models) to rerank them based on a unified relevance score, and return the most relevant matches. [Create a dense index](/guides/index-data/create-an-index#create-a-dense-index) and [create a sparse index](/guides/index-data/create-an-index#create-a-sparse-index), either with integrated embedding or for vectors created with external models. For example, the following code creates indexes with integrated embedding models. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") dense_index_name = "dense-for-hybrid-py" sparse_index_name = "sparse-for-hybrid-py" if not pc.has_index(dense_index_name): pc.create_index_for_model( name=dense_index_name, cloud="aws", region="us-east-1", embed={ "model":"llama-text-embed-v2", "field_map":{"text": "chunk_text"} } ) if not pc.has_index(sparse_index_name): pc.create_index_for_model( name=sparse_index_name, cloud="aws", region="us-east-1", embed={ "model":"pinecone-sparse-english-v0", "field_map":{"text": "chunk_text"} } ) ``` [Upsert dense vectors](/guides/index-data/upsert-data#upsert-dense-vectors) into the dense index and [upsert sparse vectors](/guides/index-data/upsert-data#upsert-sparse-vectors) into the sparse index. 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 the dense and sparse indexes # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index dense_index = pc.Index(host="INDEX_HOST") sparse_index = pc.Index(host="INDEX_HOST") # Upsert the records # The `chunk_text` fields are converted to dense and sparse vectors dense_index.upsert_records("example-namespace", records) sparse_index.upsert_records("example-namespace", records) ``` Perform a [semantic search](/guides/search/semantic-search) on the dense index. For example, the following code searches the dense index for 40 records most semantically related to the query "Q3 2024 us economic data". Because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a dense vector automatically. ```python Python theme={null} query = "Q3 2024 us economic data" dense_results = dense_index.search( namespace="example-namespace", query={ "top_k": 40, "inputs": { "text": query } } ) print(dense_results) ``` ```python Response [expandable] theme={null} {'result': {'hits': [{'_id': 'vec35', '_score': 0.8629686832427979, 'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 ' 'of 2024.'}}, {'_id': 'vec36', '_score': 0.8573639988899231, 'fields': {'chunk_text': 'Unemployment is expected to ' 'hit 2.5% in Q3 of 2024.'}}, {'_id': 'vec6', '_score': 0.8535352945327759, 'fields': {'chunk_text': 'Unemployment hit a record low ' 'of 3.7% in Q4 of 2024.'}}, {'_id': 'vec42', '_score': 0.8336166739463806, 'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 ' 'have reshaped hiring trends ' 'across high-growth ' 'industries.'}}, {'_id': 'vec48', '_score': 0.8328524827957153, 'fields': {'chunk_text': 'Wage growth outpaced inflation ' 'for the first time in years, ' 'signaling improved purchasing ' 'power in 2024.'}}, {'_id': 'vec55', '_score': 0.8322604298591614, 'fields': {'chunk_text': 'Trade tensions between the ' 'U.S. and China escalated in ' '2024, impacting global supply ' 'chains and investment flows.'}}, {'_id': 'vec45', '_score': 0.8309446573257446, 'fields': {'chunk_text': 'Corporate earnings in Q4 2024 ' 'were largely impacted by ' 'rising raw material costs and ' 'currency fluctuations.'}}, {'_id': 'vec72', '_score': 0.8275909423828125, 'fields': {'chunk_text': 'In early 2024, global GDP ' 'growth slowed, driven by ' 'weaker exports in Asia and ' 'Europe.'}}, {'_id': 'vec29', '_score': 0.8270887136459351, 'fields': {'chunk_text': 'Growth vs. value investing ' 'strategies in 2024.'}}, {'_id': 'vec46', '_score': 0.8263787627220154, 'fields': {'chunk_text': 'Economic recovery in Q2 2024 ' 'relied heavily on government ' 'spending in infrastructure and ' 'green energy projects.'}}, {'_id': 'vec79', '_score': 0.8258304595947266, 'fields': {'chunk_text': 'The resurgence of industrial ' 'policy in Q1 2024 focused on ' 'decoupling critical supply ' 'chains.'}}, {'_id': 'vec87', '_score': 0.8257324695587158, 'fields': {'chunk_text': "The U.S. labor market's " 'resilience in 2024 defied ' 'predictions of a severe ' 'recession.'}}, {'_id': 'vec40', '_score': 0.8253997564315796, 'fields': {'chunk_text': 'Labor market trends show a ' 'declining participation rate ' 'despite record low ' 'unemployment in 2024.'}}, {'_id': 'vec37', '_score': 0.8235862255096436, 'fields': {'chunk_text': 'In Q3 2025 unemployment for ' 'the prior year was revised to ' '2.2%'}}, {'_id': 'vec58', '_score': 0.8233317136764526, 'fields': {'chunk_text': 'Oil production cuts in Q1 2024 ' 'by OPEC nations drove prices ' 'higher, influencing global ' 'energy policies.'}}, {'_id': 'vec47', '_score': 0.8231339454650879, 'fields': {'chunk_text': 'The housing market saw a ' 'rebound in late 2024, driven ' 'by falling mortgage rates and ' 'pent-up demand.'}}, {'_id': 'vec41', '_score': 0.8187897801399231, 'fields': {'chunk_text': 'Forecasts of global supply ' 'chain disruptions eased in ' 'late 2024, but consumer prices ' 'remained elevated due to ' 'persistent demand.'}}, {'_id': 'vec56', '_score': 0.8155254125595093, 'fields': {'chunk_text': 'Consumer confidence indices ' 'remained resilient in Q2 2024 ' 'despite fears of an impending ' 'recession.'}}, {'_id': 'vec63', '_score': 0.8136948347091675, 'fields': {'chunk_text': 'Population aging emerged as a ' 'critical economic issue in ' '2024, especially in advanced ' 'economies.'}}, {'_id': 'vec52', '_score': 0.8129132390022278, 'fields': {'chunk_text': 'Record-breaking weather events ' 'in early 2024 have highlighted ' 'the growing economic impact of ' 'climate change.'}}, {'_id': 'vec23', '_score': 0.8126378655433655, 'fields': {'chunk_text': 'Top SPAC mergers in the ' 'technology sector for 2024.'}}, {'_id': 'vec62', '_score': 0.8116977214813232, 'fields': {'chunk_text': 'Private equity activity in ' '2024 focused on renewable ' 'energy and technology sectors ' 'amid shifting investor ' 'priorities.'}}, {'_id': 'vec64', '_score': 0.8109902739524841, 'fields': {'chunk_text': 'Rising commodity prices in ' '2024 strained emerging markets ' 'dependent on imports of raw ' 'materials.'}}, {'_id': 'vec54', '_score': 0.8092231154441833, 'fields': {'chunk_text': 'The global tourism sector ' 'showed signs of recovery in ' 'late 2024 after years of ' 'pandemic-related setbacks.'}}, {'_id': 'vec96', '_score': 0.8075559735298157, 'fields': {'chunk_text': 'New trade agreements signed ' '2022 will make an impact in ' '2024'}}, {'_id': 'vec49', '_score': 0.8062589764595032, 'fields': {'chunk_text': "China's economic growth in " '2024 slowed to its lowest ' 'level in decades due to ' 'structural reforms and weak ' 'exports.'}}, {'_id': 'vec7', '_score': 0.8034461140632629, 'fields': {'chunk_text': 'The CPI index rose by 6% in ' 'July 2024, raising concerns ' 'about purchasing power.'}}, {'_id': 'vec84', '_score': 0.8027160167694092, 'fields': {'chunk_text': "The IMF's 2024 global outlook " 'highlighted risks of ' 'stagflation in emerging ' 'markets.'}}, {'_id': 'vec13', '_score': 0.8010239601135254, 'fields': {'chunk_text': 'Credit card APRs reached an ' 'all-time high of 22.8% in ' '2024.'}}, {'_id': 'vec53', '_score': 0.8007135391235352, 'fields': {'chunk_text': 'Cryptocurrencies faced ' 'regulatory scrutiny in 2024, ' 'leading to volatility and ' 'reduced market ' 'capitalization.'}}, {'_id': 'vec60', '_score': 0.7980866432189941, 'fields': {'chunk_text': 'Healthcare spending in 2024 ' 'surged as governments expanded ' 'access to preventive care and ' 'pandemic preparedness.'}}, {'_id': 'vec91', '_score': 0.7980680465698242, 'fields': {'chunk_text': 'The impact of ESG investing on ' 'corporate strategies has been ' 'a major focus in 2024.'}}, {'_id': 'vec68', '_score': 0.797269880771637, 'fields': {'chunk_text': 'Cybersecurity spending reached ' 'new highs in 2024, reflecting ' 'the growing threat of digital ' 'attacks on infrastructure.'}}, {'_id': 'vec59', '_score': 0.795337438583374, 'fields': {'chunk_text': 'The adoption of digital ' 'currencies by central banks ' 'increased in 2024, reshaping ' 'monetary policy frameworks.'}}, {'_id': 'vec39', '_score': 0.793889045715332, 'fields': {'chunk_text': 'The rise in energy prices ' 'significantly impacted ' 'inflation trends during the ' 'first half of 2024.'}}, {'_id': 'vec66', '_score': 0.7919396162033081, 'fields': {'chunk_text': 'Bank lending to small and ' 'medium-sized enterprises ' 'surged in 2024 as governments ' 'incentivized ' 'entrepreneurship.'}}, {'_id': 'vec57', '_score': 0.7917722463607788, 'fields': {'chunk_text': 'Startups in 2024 faced tighter ' 'funding conditions as venture ' 'capitalists focused on ' 'profitability over growth.'}}, {'_id': 'vec75', '_score': 0.7907494306564331, 'fields': {'chunk_text': 'The collapse of Silicon Valley ' 'Bank raised questions about ' 'regulatory oversight in ' '2024.'}}, {'_id': 'vec51', '_score': 0.790622889995575, 'fields': {'chunk_text': 'The European Union introduced ' 'new fiscal policies in 2024 ' 'aimed at reducing public debt ' 'without stifling growth.'}}, {'_id': 'vec89', '_score': 0.7899052500724792, 'fields': {'chunk_text': 'Venture capital investments in ' '2024 leaned heavily toward AI ' 'and automation startups.'}}]}, 'usage': {'embed_total_tokens': 12, 'read_units': 1}} ``` Perform a [lexical search](/guides/search/lexical-search). For example, the following code searches the sparse index for 40 records that most exactly match the words in the query. Again, because the index is integrated with an embedding model, you provide the query as text and Pinecone converts the text to a sparse vector automatically. ```python Python theme={null} sparse_results = sparse_index.search( namespace="example-namespace", query={ "top_k": 40, "inputs": { "text": query } } ) print(sparse_results) ``` ```python Response [expandable] theme={null} {'result': {'hits': [{'_id': 'vec35', '_score': 7.0625, 'fields': {'chunk_text': 'Unemployment hit at 2.4% in Q3 ' 'of 2024.'}}, {'_id': 'vec46', '_score': 7.041015625, 'fields': {'chunk_text': 'Economic recovery in Q2 2024 ' 'relied heavily on government ' 'spending in infrastructure and ' 'green energy projects.'}}, {'_id': 'vec36', '_score': 6.96875, 'fields': {'chunk_text': 'Unemployment is expected to ' 'hit 2.5% in Q3 of 2024.'}}, {'_id': 'vec42', '_score': 6.9609375, 'fields': {'chunk_text': 'Tech sector layoffs in Q3 2024 ' 'have reshaped hiring trends ' 'across high-growth ' 'industries.'}}, {'_id': 'vec49', '_score': 6.65625, 'fields': {'chunk_text': "China's economic growth in " '2024 slowed to its lowest ' 'level in decades due to ' 'structural reforms and weak ' 'exports.'}}, {'_id': 'vec63', '_score': 6.4765625, 'fields': {'chunk_text': 'Population aging emerged as a ' 'critical economic issue in ' '2024, especially in advanced ' 'economies.'}}, {'_id': 'vec92', '_score': 5.72265625, 'fields': {'chunk_text': 'Income inequality widened in ' '2024 despite strong economic ' 'growth in developed nations.'}}, {'_id': 'vec52', '_score': 5.599609375, 'fields': {'chunk_text': 'Record-breaking weather events ' 'in early 2024 have highlighted ' 'the growing economic impact of ' 'climate change.'}}, {'_id': 'vec89', '_score': 4.0078125, 'fields': {'chunk_text': 'Venture capital investments in ' '2024 leaned heavily toward AI ' 'and automation startups.'}}, {'_id': 'vec62', '_score': 3.99609375, 'fields': {'chunk_text': 'Private equity activity in ' '2024 focused on renewable ' 'energy and technology sectors ' 'amid shifting investor ' 'priorities.'}}, {'_id': 'vec57', '_score': 3.93359375, 'fields': {'chunk_text': 'Startups in 2024 faced tighter ' 'funding conditions as venture ' 'capitalists focused on ' 'profitability over growth.'}}, {'_id': 'vec69', '_score': 3.8984375, 'fields': {'chunk_text': 'The agricultural sector faced ' 'challenges in 2024 due to ' 'extreme weather and rising ' 'input costs.'}}, {'_id': 'vec37', '_score': 3.89453125, 'fields': {'chunk_text': 'In Q3 2025 unemployment for ' 'the prior year was revised to ' '2.2%'}}, {'_id': 'vec60', '_score': 3.822265625, 'fields': {'chunk_text': 'Healthcare spending in 2024 ' 'surged as governments expanded ' 'access to preventive care and ' 'pandemic preparedness.'}}, {'_id': 'vec51', '_score': 3.783203125, 'fields': {'chunk_text': 'The European Union introduced ' 'new fiscal policies in 2024 ' 'aimed at reducing public debt ' 'without stifling growth.'}}, {'_id': 'vec55', '_score': 3.765625, 'fields': {'chunk_text': 'Trade tensions between the ' 'U.S. and China escalated in ' '2024, impacting global supply ' 'chains and investment flows.'}}, {'_id': 'vec70', '_score': 3.76171875, 'fields': {'chunk_text': 'Consumer spending patterns ' 'shifted in 2024, with a ' 'greater focus on experiences ' 'over goods.'}}, {'_id': 'vec90', '_score': 3.70703125, 'fields': {'chunk_text': 'The surge in e-commerce in ' '2024 was facilitated by ' 'advancements in logistics ' 'technology.'}}, {'_id': 'vec87', '_score': 3.69140625, 'fields': {'chunk_text': "The U.S. labor market's " 'resilience in 2024 defied ' 'predictions of a severe ' 'recession.'}}, {'_id': 'vec78', '_score': 3.673828125, 'fields': {'chunk_text': 'Consumer sentiment surveys in ' '2024 reflected optimism ' 'despite high interest rates.'}}, {'_id': 'vec82', '_score': 3.66015625, 'fields': {'chunk_text': 'Renewable energy subsidies in ' '2024 reduced the global ' 'reliance on fossil fuels.'}}, {'_id': 'vec53', '_score': 3.642578125, 'fields': {'chunk_text': 'Cryptocurrencies faced ' 'regulatory scrutiny in 2024, ' 'leading to volatility and ' 'reduced market ' 'capitalization.'}}, {'_id': 'vec94', '_score': 3.625, 'fields': {'chunk_text': 'Cyberattacks targeting ' 'financial institutions in 2024 ' 'led to record cybersecurity ' 'spending.'}}, {'_id': 'vec45', '_score': 3.607421875, 'fields': {'chunk_text': 'Corporate earnings in Q4 2024 ' 'were largely impacted by ' 'rising raw material costs and ' 'currency fluctuations.'}}, {'_id': 'vec47', '_score': 3.576171875, 'fields': {'chunk_text': 'The housing market saw a ' 'rebound in late 2024, driven ' 'by falling mortgage rates and ' 'pent-up demand.'}}, {'_id': 'vec84', '_score': 3.5703125, 'fields': {'chunk_text': "The IMF's 2024 global outlook " 'highlighted risks of ' 'stagflation in emerging ' 'markets.'}}, {'_id': 'vec41', '_score': 3.5546875, 'fields': {'chunk_text': 'Forecasts of global supply ' 'chain disruptions eased in ' 'late 2024, but consumer prices ' 'remained elevated due to ' 'persistent demand.'}}, {'_id': 'vec65', '_score': 3.537109375, 'fields': {'chunk_text': 'The global shipping industry ' 'experienced declining freight ' 'rates in 2024 due to ' 'overcapacity and reduced ' 'demand.'}}, {'_id': 'vec96', '_score': 3.53125, 'fields': {'chunk_text': 'New trade agreements signed ' '2022 will make an impact in ' '2024'}}, {'_id': 'vec86', '_score': 3.52734375, 'fields': {'chunk_text': 'Digital transformation ' 'initiatives in 2024 drove ' 'productivity gains in the ' 'services sector.'}}, {'_id': 'vec95', '_score': 3.5234375, 'fields': {'chunk_text': 'Automation in agriculture in ' '2024 increased yields but ' 'displaced rural workers.'}}, {'_id': 'vec64', '_score': 3.51171875, 'fields': {'chunk_text': 'Rising commodity prices in ' '2024 strained emerging markets ' 'dependent on imports of raw ' 'materials.'}}, {'_id': 'vec79', '_score': 3.51171875, 'fields': {'chunk_text': 'The resurgence of industrial ' 'policy in Q1 2024 focused on ' 'decoupling critical supply ' 'chains.'}}, {'_id': 'vec66', '_score': 3.48046875, 'fields': {'chunk_text': 'Bank lending to small and ' 'medium-sized enterprises ' 'surged in 2024 as governments ' 'incentivized ' 'entrepreneurship.'}}, {'_id': 'vec6', '_score': 3.4765625, 'fields': {'chunk_text': 'Unemployment hit a record low ' 'of 3.7% in Q4 of 2024.'}}, {'_id': 'vec58', '_score': 3.39453125, 'fields': {'chunk_text': 'Oil production cuts in Q1 2024 ' 'by OPEC nations drove prices ' 'higher, influencing global ' 'energy policies.'}}, {'_id': 'vec80', '_score': 3.390625, 'fields': {'chunk_text': 'Technological innovation in ' 'the fintech sector disrupted ' 'traditional banking in 2024.'}}, {'_id': 'vec75', '_score': 3.37109375, 'fields': {'chunk_text': 'The collapse of Silicon Valley ' 'Bank raised questions about ' 'regulatory oversight in ' '2024.'}}, {'_id': 'vec67', '_score': 3.357421875, 'fields': {'chunk_text': 'Renewable energy projects ' 'accounted for a record share ' 'of global infrastructure ' 'investment in 2024.'}}, {'_id': 'vec56', '_score': 3.341796875, 'fields': {'chunk_text': 'Consumer confidence indices ' 'remained resilient in Q2 2024 ' 'despite fears of an impending ' 'recession.'}}]}, 'usage': {'embed_total_tokens': 9, 'read_units': 1}} ``` Merge the 40 dense and 40 sparse results and deduplicated them based on the field you used to link sparse and dense vectors. For example, the following code merges and deduplicates the results based on the `_id` field, resulting in 52 unique results. ```python Python theme={null} def merge_chunks(h1, h2): """Get the unique hits from two search results and return them as single array of {'_id', 'chunk_text'} dicts, printing each dict on a new line.""" # Deduplicate by _id deduped_hits = {hit['_id']: hit for hit in h1['result']['hits'] + h2['result']['hits']}.values() # Sort by _score descending sorted_hits = sorted(deduped_hits, key=lambda x: x['_score'], reverse=True) # Transform to format for reranking result = [{'_id': hit['_id'], 'chunk_text': hit['fields']['chunk_text']} for hit in sorted_hits] return result merged_results = merge_chunks(sparse_results, dense_results) print('[\n ' + ',\n '.join(str(obj) for obj in merged_results) + '\n]') ``` ```console Response [expandable] theme={null} [ {'_id': 'vec92', 'chunk_text': 'Income inequality widened in 2024 despite strong economic growth in developed nations.'}, {'_id': 'vec69', 'chunk_text': 'The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs.'}, {'_id': 'vec70', 'chunk_text': 'Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods.'}, {'_id': 'vec90', 'chunk_text': 'The surge in e-commerce in 2024 was facilitated by advancements in logistics technology.'}, {'_id': 'vec78', 'chunk_text': 'Consumer sentiment surveys in 2024 reflected optimism despite high interest rates.'}, {'_id': 'vec82', 'chunk_text': 'Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels.'}, {'_id': 'vec94', 'chunk_text': 'Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending.'}, {'_id': 'vec65', 'chunk_text': 'The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand.'}, {'_id': 'vec86', 'chunk_text': 'Digital transformation initiatives in 2024 drove productivity gains in the services sector.'}, {'_id': 'vec95', 'chunk_text': 'Automation in agriculture in 2024 increased yields but displaced rural workers.'}, {'_id': 'vec80', 'chunk_text': 'Technological innovation in the fintech sector disrupted traditional banking in 2024.'}, {'_id': 'vec67', 'chunk_text': 'Renewable energy projects accounted for a record share of global infrastructure investment in 2024.'}, {'_id': 'vec35', 'chunk_text': 'Unemployment hit at 2.4% in Q3 of 2024.'}, {'_id': 'vec36', 'chunk_text': 'Unemployment is expected to hit 2.5% in Q3 of 2024.'}, {'_id': 'vec6', 'chunk_text': 'Unemployment hit a record low of 3.7% in Q4 of 2024.'}, {'_id': 'vec42', 'chunk_text': 'Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries.'}, {'_id': 'vec48', 'chunk_text': 'Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024.'}, {'_id': 'vec55', 'chunk_text': 'Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows.'}, {'_id': 'vec45', 'chunk_text': 'Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations.'}, {'_id': 'vec72', 'chunk_text': 'In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe.'}, {'_id': 'vec29', 'chunk_text': 'Growth vs. value investing strategies in 2024.'}, {'_id': 'vec46', 'chunk_text': 'Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects.'}, {'_id': 'vec79', 'chunk_text': 'The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains.'}, {'_id': 'vec87', 'chunk_text': "The U.S. labor market's resilience in 2024 defied predictions of a severe recession."}, {'_id': 'vec40', 'chunk_text': 'Labor market trends show a declining participation rate despite record low unemployment in 2024.'}, {'_id': 'vec37', 'chunk_text': 'In Q3 2025 unemployment for the prior year was revised to 2.2%'}, {'_id': 'vec58', 'chunk_text': 'Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies.'}, {'_id': 'vec47', 'chunk_text': 'The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand.'}, {'_id': 'vec41', 'chunk_text': 'Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand.'}, {'_id': 'vec56', 'chunk_text': 'Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession.'}, {'_id': 'vec63', 'chunk_text': 'Population aging emerged as a critical economic issue in 2024, especially in advanced economies.'}, {'_id': 'vec52', 'chunk_text': 'Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change.'}, {'_id': 'vec23', 'chunk_text': 'Top SPAC mergers in the technology sector for 2024.'}, {'_id': 'vec62', 'chunk_text': 'Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities.'}, {'_id': 'vec64', 'chunk_text': 'Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials.'}, {'_id': 'vec54', 'chunk_text': 'The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks.'}, {'_id': 'vec96', 'chunk_text': 'New trade agreements signed 2022 will make an impact in 2024'}, {'_id': 'vec49', 'chunk_text': "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports."}, {'_id': 'vec7', 'chunk_text': 'The CPI index rose by 6% in July 2024, raising concerns about purchasing power.'}, {'_id': 'vec84', 'chunk_text': "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets."}, {'_id': 'vec13', 'chunk_text': 'Credit card APRs reached an all-time high of 22.8% in 2024.'}, {'_id': 'vec53', 'chunk_text': 'Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization.'}, {'_id': 'vec60', 'chunk_text': 'Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness.'}, {'_id': 'vec91', 'chunk_text': 'The impact of ESG investing on corporate strategies has been a major focus in 2024.'}, {'_id': 'vec68', 'chunk_text': 'Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure.'}, {'_id': 'vec59', 'chunk_text': 'The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks.'}, {'_id': 'vec39', 'chunk_text': 'The rise in energy prices significantly impacted inflation trends during the first half of 2024.'}, {'_id': 'vec66', 'chunk_text': 'Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship.'}, {'_id': 'vec57', 'chunk_text': 'Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth.'}, {'_id': 'vec75', 'chunk_text': 'The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024.'}, {'_id': 'vec51', 'chunk_text': 'The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth.'}, {'_id': 'vec89', 'chunk_text': 'Venture capital investments in 2024 leaned heavily toward AI and automation startups.'} ] ``` Use one of Pinecone's [hosted reranking models](/guides/search/rerank-results#reranking-models) to rerank the merged and deduplicated results based on a unified relevance score and then return a smaller set of the most highly relevant results. For example, the following code sends the 52 unique results from the last step to the `bge-reranker-v2-m3` reranking model and returns the top 10 most relevant results. ```python Python theme={null} result = pc.inference.rerank( model="bge-reranker-v2-m3", query=query, documents=merged_results, rank_fields=["chunk_text"], top_n=10, return_documents=True, parameters={ "truncate": "END" } ) print("Query", query) print('-----') for row in result.data: print(f"{row['document']['_id']} - {round(row['score'], 2)} - {row['document']['chunk_text']}") ``` ```console Response [expandable] theme={null} Query Q3 2024 us economic data ----- vec36 - 0.84 - Unemployment is expected to hit 2.5% in Q3 of 2024. vec35 - 0.76 - Unemployment hit at 2.4% in Q3 of 2024. vec48 - 0.33 - Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024. vec37 - 0.25 - In Q3 2025 unemployment for the prior year was revised to 2.2% vec42 - 0.21 - Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries. vec87 - 0.2 - The U.S. labor market's resilience in 2024 defied predictions of a severe recession. vec63 - 0.08 - Population aging emerged as a critical economic issue in 2024, especially in advanced economies. vec92 - 0.08 - Income inequality widened in 2024 despite strong economic growth in developed nations. vec72 - 0.07 - In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe. vec46 - 0.06 - Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects. ``` ## Use a single hybrid index You can perform hybrid search with a single hybrid index as follows: To store both dense and sparse vectors in a single index, use the [`create_index`](/reference/api/latest/control-plane/create_index) operation, setting the `vector_type` to `dense` and the `metric` to `dotproduct`. This is the only combination that supports dense/sparse search on a single index. ```python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") index_name = "hybrid-index" if not pc.has_index(index_name): pc.create_index( name=index_name, vector_type="dense", dimension=1024, metric="dotproduct", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` Use Pinecone's [hosted embedding models](/guides/index-data/create-an-index#embedding-models) to [convert data into dense and sparse vectors](/reference/api/latest/inference/generate-embeddings). ```python Python [expandable] theme={null} # Define the records data = [ { "_id": "vec1", "chunk_text": "Apple Inc. issued a $10 billion corporate bond in 2023." }, { "_id": "vec2", "chunk_text": "ETFs tracking the S&P 500 outperformed active funds last year." }, { "_id": "vec3", "chunk_text": "Tesla's options volume surged after the latest earnings report." }, { "_id": "vec4", "chunk_text": "Dividend aristocrats are known for consistently raising payouts." }, { "_id": "vec5", "chunk_text": "The Federal Reserve raised interest rates by 0.25% to curb inflation." }, { "_id": "vec6", "chunk_text": "Unemployment hit a record low of 3.7% in Q4 of 2024." }, { "_id": "vec7", "chunk_text": "The CPI index rose by 6% in July 2024, raising concerns about purchasing power." }, { "_id": "vec8", "chunk_text": "GDP growth in emerging markets outpaced developed economies." }, { "_id": "vec9", "chunk_text": "Amazon's acquisition of MGM Studios was valued at $8.45 billion." }, { "_id": "vec10", "chunk_text": "Alphabet reported a 20% increase in advertising revenue." }, { "_id": "vec11", "chunk_text": "ExxonMobil announced a special dividend after record profits." }, { "_id": "vec12", "chunk_text": "Tesla plans a 3-for-1 stock split to attract retail investors." }, { "_id": "vec13", "chunk_text": "Credit card APRs reached an all-time high of 22.8% in 2024." }, { "_id": "vec14", "chunk_text": "A 529 college savings plan offers tax advantages for education." }, { "_id": "vec15", "chunk_text": "Emergency savings should ideally cover 6 months of expenses." }, { "_id": "vec16", "chunk_text": "The average mortgage rate rose to 7.1% in December." }, { "_id": "vec17", "chunk_text": "The SEC fined a hedge fund $50 million for insider trading." }, { "_id": "vec18", "chunk_text": "New ESG regulations require companies to disclose climate risks." }, { "_id": "vec19", "chunk_text": "The IRS introduced a new tax bracket for high earners." }, { "_id": "vec20", "chunk_text": "Compliance with GDPR is mandatory for companies operating in Europe." }, { "_id": "vec21", "chunk_text": "What are the best-performing green bonds in a rising rate environment?" }, { "_id": "vec22", "chunk_text": "How does inflation impact the real yield of Treasury bonds?" }, { "_id": "vec23", "chunk_text": "Top SPAC mergers in the technology sector for 2024." }, { "_id": "vec24", "chunk_text": "Are stablecoins a viable hedge against currency devaluation?" }, { "_id": "vec25", "chunk_text": "Comparison of Roth IRA vs 401(k) for high-income earners." }, { "_id": "vec26", "chunk_text": "Stock splits and their effect on investor sentiment." }, { "_id": "vec27", "chunk_text": "Tech IPOs that disappointed in their first year." }, { "_id": "vec28", "chunk_text": "Impact of interest rate hikes on bank stocks." }, { "_id": "vec29", "chunk_text": "Growth vs. value investing strategies in 2024." }, { "_id": "vec30", "chunk_text": "The role of artificial intelligence in quantitative trading." }, { "_id": "vec31", "chunk_text": "What are the implications of quantitative tightening on equities?" }, { "_id": "vec32", "chunk_text": "How does compounding interest affect long-term investments?" }, { "_id": "vec33", "chunk_text": "What are the best assets to hedge against inflation?" }, { "_id": "vec34", "chunk_text": "Can ETFs provide better diversification than mutual funds?" }, { "_id": "vec35", "chunk_text": "Unemployment hit at 2.4% in Q3 of 2024." }, { "_id": "vec36", "chunk_text": "Unemployment is expected to hit 2.5% in Q3 of 2024." }, { "_id": "vec37", "chunk_text": "In Q3 2025 unemployment for the prior year was revised to 2.2%"}, { "_id": "vec38", "chunk_text": "Emerging markets witnessed increased foreign direct investment as global interest rates stabilized." }, { "_id": "vec39", "chunk_text": "The rise in energy prices significantly impacted inflation trends during the first half of 2024." }, { "_id": "vec40", "chunk_text": "Labor market trends show a declining participation rate despite record low unemployment in 2024." }, { "_id": "vec41", "chunk_text": "Forecasts of global supply chain disruptions eased in late 2024, but consumer prices remained elevated due to persistent demand." }, { "_id": "vec42", "chunk_text": "Tech sector layoffs in Q3 2024 have reshaped hiring trends across high-growth industries." }, { "_id": "vec43", "chunk_text": "The U.S. dollar weakened against a basket of currencies as the global economy adjusted to shifting trade balances." }, { "_id": "vec44", "chunk_text": "Central banks worldwide increased gold reserves to hedge against geopolitical and economic instability." }, { "_id": "vec45", "chunk_text": "Corporate earnings in Q4 2024 were largely impacted by rising raw material costs and currency fluctuations." }, { "_id": "vec46", "chunk_text": "Economic recovery in Q2 2024 relied heavily on government spending in infrastructure and green energy projects." }, { "_id": "vec47", "chunk_text": "The housing market saw a rebound in late 2024, driven by falling mortgage rates and pent-up demand." }, { "_id": "vec48", "chunk_text": "Wage growth outpaced inflation for the first time in years, signaling improved purchasing power in 2024." }, { "_id": "vec49", "chunk_text": "China's economic growth in 2024 slowed to its lowest level in decades due to structural reforms and weak exports." }, { "_id": "vec50", "chunk_text": "AI-driven automation in the manufacturing sector boosted productivity but raised concerns about job displacement." }, { "_id": "vec51", "chunk_text": "The European Union introduced new fiscal policies in 2024 aimed at reducing public debt without stifling growth." }, { "_id": "vec52", "chunk_text": "Record-breaking weather events in early 2024 have highlighted the growing economic impact of climate change." }, { "_id": "vec53", "chunk_text": "Cryptocurrencies faced regulatory scrutiny in 2024, leading to volatility and reduced market capitalization." }, { "_id": "vec54", "chunk_text": "The global tourism sector showed signs of recovery in late 2024 after years of pandemic-related setbacks." }, { "_id": "vec55", "chunk_text": "Trade tensions between the U.S. and China escalated in 2024, impacting global supply chains and investment flows." }, { "_id": "vec56", "chunk_text": "Consumer confidence indices remained resilient in Q2 2024 despite fears of an impending recession." }, { "_id": "vec57", "chunk_text": "Startups in 2024 faced tighter funding conditions as venture capitalists focused on profitability over growth." }, { "_id": "vec58", "chunk_text": "Oil production cuts in Q1 2024 by OPEC nations drove prices higher, influencing global energy policies." }, { "_id": "vec59", "chunk_text": "The adoption of digital currencies by central banks increased in 2024, reshaping monetary policy frameworks." }, { "_id": "vec60", "chunk_text": "Healthcare spending in 2024 surged as governments expanded access to preventive care and pandemic preparedness." }, { "_id": "vec61", "chunk_text": "The World Bank reported declining poverty rates globally, but regional disparities persisted." }, { "_id": "vec62", "chunk_text": "Private equity activity in 2024 focused on renewable energy and technology sectors amid shifting investor priorities." }, { "_id": "vec63", "chunk_text": "Population aging emerged as a critical economic issue in 2024, especially in advanced economies." }, { "_id": "vec64", "chunk_text": "Rising commodity prices in 2024 strained emerging markets dependent on imports of raw materials." }, { "_id": "vec65", "chunk_text": "The global shipping industry experienced declining freight rates in 2024 due to overcapacity and reduced demand." }, { "_id": "vec66", "chunk_text": "Bank lending to small and medium-sized enterprises surged in 2024 as governments incentivized entrepreneurship." }, { "_id": "vec67", "chunk_text": "Renewable energy projects accounted for a record share of global infrastructure investment in 2024." }, { "_id": "vec68", "chunk_text": "Cybersecurity spending reached new highs in 2024, reflecting the growing threat of digital attacks on infrastructure." }, { "_id": "vec69", "chunk_text": "The agricultural sector faced challenges in 2024 due to extreme weather and rising input costs." }, { "_id": "vec70", "chunk_text": "Consumer spending patterns shifted in 2024, with a greater focus on experiences over goods." }, { "_id": "vec71", "chunk_text": "The economic impact of the 2008 financial crisis was mitigated by quantitative easing policies." }, { "_id": "vec72", "chunk_text": "In early 2024, global GDP growth slowed, driven by weaker exports in Asia and Europe." }, { "_id": "vec73", "chunk_text": "The historical relationship between inflation and unemployment is explained by the Phillips Curve." }, { "_id": "vec74", "chunk_text": "The World Trade Organization's role in resolving disputes was tested in 2024." }, { "_id": "vec75", "chunk_text": "The collapse of Silicon Valley Bank raised questions about regulatory oversight in 2024." }, { "_id": "vec76", "chunk_text": "The cost of living crisis has been exacerbated by stagnant wage growth and rising inflation." }, { "_id": "vec77", "chunk_text": "Supply chain resilience became a top priority for multinational corporations in 2024." }, { "_id": "vec78", "chunk_text": "Consumer sentiment surveys in 2024 reflected optimism despite high interest rates." }, { "_id": "vec79", "chunk_text": "The resurgence of industrial policy in Q1 2024 focused on decoupling critical supply chains." }, { "_id": "vec80", "chunk_text": "Technological innovation in the fintech sector disrupted traditional banking in 2024." }, { "_id": "vec81", "chunk_text": "The link between climate change and migration patterns is increasingly recognized." }, { "_id": "vec82", "chunk_text": "Renewable energy subsidies in 2024 reduced the global reliance on fossil fuels." }, { "_id": "vec83", "chunk_text": "The economic fallout of geopolitical tensions was evident in rising defense budgets worldwide." }, { "_id": "vec84", "chunk_text": "The IMF's 2024 global outlook highlighted risks of stagflation in emerging markets." }, { "_id": "vec85", "chunk_text": "Declining birth rates in advanced economies pose long-term challenges for labor markets." }, { "_id": "vec86", "chunk_text": "Digital transformation initiatives in 2024 drove productivity gains in the services sector." }, { "_id": "vec87", "chunk_text": "The U.S. labor market's resilience in 2024 defied predictions of a severe recession." }, { "_id": "vec88", "chunk_text": "New fiscal measures in the European Union aimed to stabilize debt levels post-pandemic." }, { "_id": "vec89", "chunk_text": "Venture capital investments in 2024 leaned heavily toward AI and automation startups." }, { "_id": "vec90", "chunk_text": "The surge in e-commerce in 2024 was facilitated by advancements in logistics technology." }, { "_id": "vec91", "chunk_text": "The impact of ESG investing on corporate strategies has been a major focus in 2024." }, { "_id": "vec92", "chunk_text": "Income inequality widened in 2024 despite strong economic growth in developed nations." }, { "_id": "vec93", "chunk_text": "The collapse of FTX highlighted the volatility and risks associated with cryptocurrencies." }, { "_id": "vec94", "chunk_text": "Cyberattacks targeting financial institutions in 2024 led to record cybersecurity spending." }, { "_id": "vec95", "chunk_text": "Automation in agriculture in 2024 increased yields but displaced rural workers." }, { "_id": "vec96", "chunk_text": "New trade agreements signed 2022 will make an impact in 2024"}, ] ``` ```python Python theme={null} # Convert the chunk_text into dense vectors dense_embeddings = pc.inference.embed( model="llama-text-embed-v2", inputs=[d['chunk_text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) # Convert the chunk_text into sparse vectors sparse_embeddings = pc.inference.embed( model="pinecone-sparse-english-v0", inputs=[d['chunk_text'] for d in data], parameters={"input_type": "passage", "truncate": "END"} ) ``` Use the [`upsert`](/reference/api/latest/data-plane/upsert) operation, specifying dense values in the `value` parameter and sparse values in the `sparse_values` parameter. Only dense indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support dense and sparse vectors. Upserting records with dense and sparse vectors into dense indexes with a different distance metric will succeed, but querying will return an error. ```Python Python theme={null} # Target the hybrid index # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") # Each record contains an ID, a dense vector, a sparse vector, and the original text as metadata records = [] for d, de, se in zip(data, dense_embeddings, sparse_embeddings): records.append({ "id": d['_id'], "values": de['values'], "sparse_values": {'indices': se['sparse_indices'], 'values': se['sparse_values']}, "metadata": {'text': d['chunk_text']} }) # Upsert the records into the hybrid index index.upsert( vectors=records, namespace="example-namespace" ) ``` Use the [`embed`](/reference/api/latest/inference/generate-embeddings) operation to convert your query into a dense vector and a sparse vector, and then use the [`query`](/reference/api/latest/data-plane/query) operation to search the hybrid 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}} ``` Because Pinecone views your sparse-dense vector as a single vector, it does not offer a built-in parameter to adjust the weight of a query's dense part against its sparse part; the index is agnostic to density or sparsity of coordinates in your vectors. You may, however, incorporate a linear weighting scheme by customizing your query vector, as we demonstrate 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 ) ``` # Lexical search Source: https://docs.pinecone.io/guides/search/lexical-search Perform keyword-based search on sparse indexes This page shows you how to search a [sparse index](/guides/index-data/indexing-overview#sparse-indexes) for records that most exactly match the words or phrases in a query. This is often called lexical search or keyword search. Lexical search uses [sparse vectors](https://www.pinecone.io/learn/sparse-retrieval/), which have a very large number of dimensions, where only a small proportion of values are non-zero. The dimensions represent words from a dictionary, and the values represent the importance of these words in the document. Words are scored independently and then summed, with the most similar records scored highest. ## Search with text Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To search a sparse index with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `query.inputs.text`: The query text. Pinecone uses the [embedding model](/guides/index-data/create-an-index#embedding-models) integrated with the index to convert the text to a sparse vector automatically. * `query.top_k`: The number of records to return. * `query.match_terms`: (Optional) A list of terms that must be present in each search result. For more details, see [Filter by required terms](#filter-by-required-terms). * `fields`: (Optional) The fields to return in the response. If not specified, the response includes all fields. For example, the following code converts the query “What is AAPL's outlook, considering both product launches and market conditions?” to a sparse vector and then searches for the 3 most similar vectors in the `example-namespace` namespace: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.search( namespace="example-namespace", query={ "inputs": {"text": "What is AAPL's outlook, considering both product launches and market conditions?"}, "top_k": 3 }, fields=["chunk_text", "quarter"] ) print(results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 3, inputs: { text: "What is AAPL's outlook, considering both product launches and market conditions?" }, }, fields: ['chunk_text', 'quarter'] }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-sparse-java"); String query = "What is AAPL's outlook, considering both product launches and market conditions?"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the sparse index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 3, null, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "What is AAPL's outlook, considering both product launches and market conditions?", }, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 3, Inputs = new Dictionary { { "text", "What is AAPL's outlook, considering both product launches and market conditions?" } }, }, Fields = ["category", "chunk_text"], } ); Console.WriteLine(response); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "query": { "inputs": { "text": "What is AAPL'\''s outlook, considering both product launches and market conditions?" }, "top_k": 3 }, "fields": ["chunk_text", "quarter"] }' ``` The results will look as follows. The most similar records are scored highest. ```python Python theme={null} {'result': {'hits': [{'_id': 'vec2', '_score': 10.77734375, 'fields': {'chunk_text': "Analysts suggest that AAPL'''s " 'upcoming Q4 product launch ' 'event might solidify its ' 'position in the premium ' 'smartphone market.', 'quarter': 'Q4'}}, {'_id': 'vec3', '_score': 6.49066162109375, 'fields': {'chunk_text': "AAPL'''s strategic Q3 " 'partnerships with ' 'semiconductor suppliers could ' 'mitigate component risks and ' 'stabilize iPhone production.', 'quarter': 'Q3'}}, {'_id': 'vec1', '_score': 5.3671875, 'fields': {'chunk_text': 'AAPL reported a year-over-year ' 'revenue increase, expecting ' 'stronger Q3 demand for its ' 'flagship phones.', 'quarter': 'Q3'}}]}, 'usage': {'embed_total_tokens': 18, 'read_units': 1}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: "vec2", _score: 10.82421875, fields: { chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", quarter: "Q4" } }, { _id: "vec3", _score: 6.49066162109375, fields: { chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", quarter: "Q3" } }, { _id: "vec1", _score: 5.3671875, fields: { chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", quarter: "Q3" } } ] }, usage: { readUnits: 1, embedTotalTokens: 18 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: vec2 score: 10.82421875 fields: {chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market., quarter=Q4} additionalProperties: null }, class Hit { id: vec3 score: 6.49066162109375 fields: {chunk_text=AAAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production., quarter=Q3} additionalProperties: null }, class Hit { id: vec1 score: 5.3671875 fields: {chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones., quarter=Q3} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 1 embedTotalTokens: 18 } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "vec2", "_score": 10.833984, "fields": { "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "_id": "vec3", "_score": 6.473572, "fields": { "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "quarter": "Q3" } }, { "_id": "vec1", "_score": 5.3710938, "fields": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 18 } } ``` ```csharp C# theme={null} { "result": { "hits": [ { "_id": "vec2", "_score": 10.833984, "fields": { "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "_id": "vec3", "_score": 6.473572, "fields": { "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "quarter": "Q3" } }, { "_id": "vec1", "_score": 5.3710938, "fields": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 18 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "vec2", "_score": 10.82421875, "fields": { "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "_id": "vec3", "_score": 6.49066162109375, "fields": { "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "quarter": "Q3" } }, { "_id": "vec1", "_score": 5.3671875, "fields": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ] }, "usage": { "embed_total_tokens": 18, "read_units": 1 } } ``` ## Search with a sparse vector To search a sparse index with a sparse vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `sparse_vector`: The sparse vector values and indices. * `top_k`: The number of results to return. * `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`. * `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`. When querying with `top_k` over 1000, avoid returning vector data or metadata for optimal performance. For example, the following code uses a sparse vector representation of the query "What is AAPL's outlook, considering both product launches and market conditions?" to search for the 3 most similar vectors in the `example-namespace` namespace: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.query( namespace="example-namespace", sparse_vector={ "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, top_k=3, include_metadata=True, include_values=False ) print(results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ sparseVector: { indices: [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], values: [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] }, topK: 3, includeValues: false, includeMetadata: true }); console.log(queryResponse); ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import io.pinecone.clients.Index; import java.util.*; public class SearchSparseIndex { public static void main(String[] args) throws InterruptedException { // Instantiate Pinecone class Pinecone pinecone = new Pinecone.Builder("YOUR_API_KEY").build(); String indexName = "docs-example"; Index index = pinecone.getIndexConnection(indexName); List sparseIndices = Arrays.asList( 767227209L, 1640781426L, 1690623792L, 2021799277L, 2152645940L, 2295025838L, 2443437770L, 2779594451L, 2956155693L, 3476647774L, 3818127854L, 428309169L); List sparseValues = Arrays.asList( 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, null, sparseIndices, sparseValues, null, "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } sparseValues := pinecone.SparseValues{ Indices: []uint32{767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697}, Values: []float32{1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0}, } res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ SparseValues: &sparseValues, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); var index = pinecone.Index("docs-example"); var queryResponse = await index.QueryAsync(new QueryRequest { Namespace = "example-namespace", TopK = 4, SparseVector = new SparseValues { Indices = [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697], Values = new[] { 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f, 1.0f }, }, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine(queryResponse); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "sparseVector": { "values": [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0], "indices": [767227209, 1640781426, 1690623792, 2021799277, 2152645940, 2295025838, 2443437770, 2779594451, 2956155693, 3476647774, 3818127854, 4283091697] }, "namespace": "example-namespace", "topK": 4, "includeMetadata": true, "includeValues": false }' ``` The results will look as follows. The most similar records are scored highest. ```python Python theme={null} {'matches': [{'id': 'vec2', 'metadata': {'category': 'technology', 'quarter': 'Q4', 'chunk_text': "Analysts suggest that AAPL'''s " 'upcoming Q4 product launch event ' 'might solidify its position in the ' 'premium smartphone market.'}, 'score': 10.9042969, 'values': []}, {'id': 'vec3', 'metadata': {'category': 'technology', 'quarter': 'Q3', 'chunk_text': "AAPL'''s strategic Q3 partnerships " 'with semiconductor suppliers could ' 'mitigate component risks and ' 'stabilize iPhone production'}, 'score': 6.48010254, 'values': []}, {'id': 'vec1', 'metadata': {'category': 'technology', 'quarter': 'Q3', 'chunk_text': 'AAPL reported a year-over-year ' 'revenue increase, expecting ' 'stronger Q3 demand for its flagship ' 'phones.'}, 'score': 5.3671875, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 1}} ``` ```javascript JavaScript theme={null} { matches: [ { id: 'vec2', score: 10.9042969, values: [], metadata: { chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", category: 'technology', quarter: 'Q4' } }, { id: 'vec3', score: 6.48010254, values: [], metadata: { chunk_text: "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", category: 'technology', quarter: 'Q3' } }, { id: 'vec1', score: 5.3671875, values: [], metadata: { chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.', category: 'technology', quarter: 'Q3' } } ], namespace: 'example-namespace', usage: {readUnits: 1} } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 10.34375 id: vec2 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "Analysts suggest that AAPL\'\\\'\'s upcoming Q4 product launch event might solidify its position in the premium smartphone market." } } fields { key: "quarter" value { string_value: "Q4" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 5.8638916 id: vec3 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "AAPL\'\\\'\'s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production" } } fields { key: "quarter" value { string_value: "Q3" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 5.3671875 id: vec1 values: [] metadata: fields { key: "category" value { string_value: "technology" } } fields { key: "chunk_text" value { string_value: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." } } fields { key: "quarter" value { string_value: "Q3" } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-namespace usage: read_units: 1 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "vec2", "metadata": { "category": "technology", "quarter": "Q4", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." } }, "score": 10.904296 }, { "vector": { "id": "vec3", "metadata": { "category": "technology", "quarter": "Q3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production" } }, "score": 6.4801025 }, { "vector": { "id": "vec1", "metadata": { "category": "technology", "quarter": "Q3", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones" } }, "score": 5.3671875 } ], "usage": { "read_units": 1 }, "namespace": "example-namespace" } ``` ```csharp C# theme={null} { "results": [], "matches": [ { "id": "vec2", "score": 10.904297, "values": [], "metadata": { "category": "technology", "chunk_text": "Analysts suggest that AAPL\u0027\u0027\u0027s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "quarter": "Q4" } }, { "id": "vec3", "score": 6.4801025, "values": [], "metadata": { "category": "technology", "chunk_text": "AAPL\u0027\u0027\u0027s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production", "quarter": "Q3" } }, { "id": "vec1", "score": 5.3671875, "values": [], "metadata": { "category": "technology", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "quarter": "Q3" } } ], "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` ```json curl theme={null} { "results": [], "matches": [ { "id": "vec2", "score": 10.9042969, "values": [], "metadata": { "chunk_text": "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "category": "technology", "quarter": "Q4" } }, { "id": "vec3", "score": 6.48010254, "values": [], "metadata": { "chunk_text": "AAPL'''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production.", "category": "technology", "quarter": "Q3" } }, { "id": "vec1", "score": 5.3671875, "values": [], "metadata": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "category": "technology", "quarter": "Q3" } } ], "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` ## Search with a record ID When you search with a record ID, Pinecone uses the sparse vector associated with the record as the query. To search a sparse index with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * `namespace`: The [namespace](/guides/index-data/indexing-overview#namespaces) to query. To use the default namespace, set to `"__default__"`. * `id`: The unique record ID containing the sparse vector to use as the query. * `top_k`: The number of results to return. * `include_values`: Whether to include the vector values of the matching records in the response. Defaults to `false`. * `include_metadata`: Whether to include the metadata of the matching records in the response. Defaults to `false`. When querying with `top_k` over 1000, avoid returning vector data or metadata for optimal performance. For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that best match the sparse vector in the record: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", id="rec2", top_k=3, include_metadata=True, include_values=False ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ id: 'rec2', topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } vectorId := "rec2" res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{ VectorId: vectorId, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err) } else { fmt.Printf(prettifyStruct(res.Matches)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var queryResponse = await index.QueryAsync(new QueryRequest { Id = "rec2", Namespace = "example-namespace", TopK = 3, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine(queryResponse); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Filter by required terms This feature is in [public preview](/release-notes/feature-availability) and is available only on the `2025-10` version of the API. See [limitations](#limitations) for details. When [searching with text](#search-with-text), you can specify a list of terms that must be present in each lexical search result. This is especially useful for: * **Precision filtering**: Ensuring specific entities or concepts appear in results * **Quality control**: Filtering out results that don't contain essential keywords * **Domain-specific searches**: Requiring domain-specific terminology in results * **Entity-based filtering**: Ensuring specific people, places, or things are mentioned To filter by required terms, add `match_terms` to your query, specifying the `terms` to require and the `strategy` to use. Currently, `all` is the only strategy supported (all terms must be present). For example, the following request searches for records about Tesla's stock performance while ensuring both "Tesla" and "stock" appear in each result: ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/records/namespaces/example-namespace/search" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": { "text": "What is the current outlook for Tesla stock performance?" }, "top_k": 3, "match_terms": { "terms": ["Tesla", "stock"], "strategy": "all" } }, "fields": ["chunk_text"] }' ``` The response includes only records that contain both "Tesla" and "stock": ```json theme={null} { "result": { "hits": [ { "_id": "tesla_q4_earnings", "_score": 9.82421875, "fields": { "chunk_text": "Tesla stock surged 8% in after-hours trading following strong Q4 earnings that exceeded analyst expectations. The company reported record vehicle deliveries and improved profit margins." } }, { "_id": "tesla_competition_analysis", "_score": 7.49066162109375, "fields": { "chunk_text": "Tesla stock faces increasing competition from traditional automakers entering the electric vehicle market. However, analysts maintain that Tesla's technological lead and brand recognition provide significant advantages." } }, { "_id": "tesla_production_update", "_score": 6.3671875, "fields": { "chunk_text": "Tesla stock performance is closely tied to production capacity at its Gigafactories. Recent expansion announcements suggest the company is positioning for continued growth in global markets." } } ] }, "usage": { "embed_total_tokens": 18, "read_units": 1 } } ``` Without the `match_terms` filter, you might get results like: * "Tesla cars are popular in California" (mentions Tesla but not stock) * "Stock market volatility affects tech companies" (mentions stock but not Tesla) * "Electric vehicle sales are growing" (neither Tesla nor stock) ### Limitations * **Integrated indexes only**: Filtering by required terms is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). * **Post-processing filter**: The filtering happens after the initial query, so potential matches that weren't included in the initial `top_k` results won't appear in the final results * **No phrase matching**: Terms are matched individually in any order and location. * **No case-sensitivity**: Terms are normalized during processing. # Rerank results Source: https://docs.pinecone.io/guides/search/rerank-results Improve the quality of results with reranking. 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. ## Integrated reranking To rerank initial results as an integrated part of a query, without any extra steps, use the [`search`](/reference/api/latest/data-plane/search_records) operation with the `rerank` parameter, including the [hosted reranking model](#reranking-models) you want to use, the number of reranked results to return, and the fields to use for reranking, if different than the main query. For example, the following code searches for the 3 records most semantically related to a query text and uses the `hosted bge-reranker-v2-m3` model to rerank the results and return only the 2 most relevant documents: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") ranked_results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 4 }, rerank={ "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] }, fields=["category", "chunk_text"] ) print(ranked_results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 2, inputs: { text: 'Disease prevention' }, }, fields: ['chunk_text', 'category'], rerank: { model: 'bge-reranker-v2-m3', rankFields: ['chunk_text'], topN: 2, }, }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsRequestRerank; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); ListrankFields = new ArrayList<>(); rankFields.add("chunk_text"); SearchRecordsRequestRerank rerank = new SearchRecordsRequestRerank() .query(query) .model("bge-reranker-v2-m3") .topN(2) .rankFields(rankFields); SearchRecordsResponse recordsResponseReranked = index.searchRecordsByText(query, "example-namespace", fields,4, null, rerank); System.out.println(recordsResponseReranked); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } topN := int32(2) res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 3, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, }, Rerank: &pinecone.SearchRecordsRerank{ Model: "bge-reranker-v2-m3", TopN: &topN, RankFields: []string{"chunk_text"}, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 4, Inputs = new Dictionary { { "text", "Disease prevention" } }, }, Fields = ["category", "chunk_text"], Rerank = new SearchRecordsRequestRerank { Model = "bge-reranker-v2-m3", TopN = 2, RankFields = ["chunk_text"], } } ); Console.WriteLine(response); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 4 }, "rerank": { "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] }, "fields": ["category", "chunk_text"] }' ``` The response looks as follows. For each hit, the `_score` represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance. ```python Python theme={null} {'result': {'hits': [{'_id': 'rec3', '_score': 0.004399413242936134, 'fields': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples ' 'contribute to immune health ' 'and may reduce the risk of ' 'chronic diseases.'}}, {'_id': 'rec4', '_score': 0.0029235430993139744, 'fields': {'category': 'endocrine system', 'chunk_text': 'The high fiber content in ' 'apples can also help regulate ' 'blood sugar levels, making ' 'them a favorable snack for ' 'people with diabetes.'}}]}, 'usage': {'embed_total_tokens': 8, 'read_units': 6, 'rerank_units': 1}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: 'rec3', _score: 0.004399413242936134, fields: { category: 'immune system', chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.' } }, { _id: 'rec4', _score: 0.0029235430993139744, fields: { category: 'endocrine system', chunk_text: 'The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.' } } ] }, usage: { readUnits: 6, embedTotalTokens: 8, rerankUnits: 1 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec3 score: 0.004399413242936134 fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.} additionalProperties: null }, class Hit { id: rec4 score: 0.0029235430993139744 fields: {category=endocrine system, chunk_text=The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 rerankUnits: 1 additionalProperties: null } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.13683891, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029235430993139744, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8, "rerank_units": 1 } } ``` ```csharp C# 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.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": { "read_units": 6, "embed_total_tokens": 8, "rerank_units": 1 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.004433765076100826, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029121784027665854, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6, "rerank_units": 1 } } ``` ## Standalone reranking To rerank initial results as a standalone operation, use the [`rerank`](/reference/api/latest/inference/rerank) operation with the [hosted reranking model](#reranking-models) you want to use, the query results and the query, the number of ranked results to return, the field to use for reranking, and any other model-specific parameters. For example, the following code uses the hosted `bge-reranker-v2-m3` model to rerank the values of the `documents.chunk_text` fields based on their relevance to the query and return only the 2 most relevant documents, along with their score: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ranked_results = pc.inference.rerank( model="bge-reranker-v2-m3", query="What is AAPL's outlook, considering both product launches and market conditions?", documents=[ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."}, ], top_n=2, rank_fields=["chunk_text"], return_documents=True, parameters={ "truncate": "END" } ) print(ranked_results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); const rerankingModel = 'bge-reranker-v2-m3'; const query = "What is AAPL's outlook, considering both product launches and market conditions?"; const documents = [ { id: 'vec2', chunk_text: "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." }, { id: 'vec3', chunk_text: "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production." }, { id: 'vec1', chunk_text: "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." }, ]; const rerankOptions = { topN: 2, rankFields: ['chunk_text'], returnDocuments: true, parameters: { truncate: 'END' }, }; const rankedResults = await pc.inference.rerank( rerankingModel, query, documents, rerankOptions ); console.log(rankedResults); ``` ```java Java theme={null} import io.pinecone.clients.Inference; import io.pinecone.clients.Pinecone; import org.openapitools.inference.client.model.RerankResult; import org.openapitools.inference.client.ApiException; import java.util.*; public class RerankExample { public static void main(String[] args) throws ApiException { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); Inference inference = pc.getInferenceClient(); // The model to use for reranking String model = "bge-reranker-v2-m3"; // The query to rerank documents against String query = "What is AAPL's outlook, considering both product launches and market conditions?"; // Add the documents to rerank List> documents = new ArrayList<>(); Map doc1 = new HashMap<>(); doc1.put("id", "vec2"); doc1.put("chunk_text", "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."); documents.add(doc1); Map doc2 = new HashMap<>(); doc2.put("id", "vec3"); doc2.put("chunk_text", "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production"); documents.add(doc2); Map doc3 = new HashMap<>(); doc3.put("id", "vec1"); doc3.put("chunk_text", "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."); documents.add(doc3); // The fields to rank the documents by. If not provided, the default is "text" List rankFields = Arrays.asList("chunk_text"); // The number of results to return sorted by relevance. Defaults to the number of inputs int topN = 2; // Whether to return the documents in the response boolean returnDocuments = true; // Additional model-specific parameters for the reranker Map parameters = new HashMap<>(); parameters.put("truncate", "END"); // Send ranking request RerankResult result = inference.rerank(model, query, documents, rankFields, topN, returnDocuments, parameters); // Get ranked data System.out.println(result.getData()); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } rerankModel := "bge-reranker-v2-m3" topN := 2 returnDocuments := true documents := []pinecone.Document{ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."}, } ranking, err := pc.Inference.Rerank(ctx, &pinecone.RerankRequest{ Model: rerankModel, Query: "What is AAPL's outlook, considering both product launches and market conditions?", ReturnDocuments: &returnDocuments, TopN: &topN, RankFields: &[]string{"chunk_text"}, Documents: documents, }) if err != nil { log.Fatalf("Failed to rerank: %v", err) } fmt.Printf(prettifyStruct(ranking)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // Add the documents to rerank var documents = new List> { new() { ["id"] = "vec2", ["chunk_text"] = "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." }, new() { ["id"] = "vec3", ["chunk_text"] = "AAPL's strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production." }, new() { ["id"] = "vec1", ["chunk_text"] = "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." } }; // The fields to rank the documents by. If not provided, the default is "text" var rankFields = new List { "chunk_text" }; // Additional model-specific parameters for the reranker var parameters = new Dictionary { ["truncate"] = "END" }; // Send ranking request var result = await pinecone.Inference.RerankAsync( new RerankRequest { Model = "bge-reranker-v2-m3", Query = "What is AAPL's outlook, considering both product launches and market conditions?", Documents = documents, RankFields = rankFields, TopN = 2, ReturnDocuments = true, Parameters = parameters }); Console.WriteLine(result); ``` ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "What is AAPL'\''s outlook, considering both product launches and market conditions?", "documents": [ {"id": "vec2", "chunk_text": "Analysts suggest that AAPL'\''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."}, {"id": "vec3", "chunk_text": "AAPL'\''s strategic Q3 partnerships with semiconductor suppliers could mitigate component risks and stabilize iPhone production."}, {"id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones."} ], "top_n": 2, "rank_fields": ["chunk_text"], "return_documents": true, "parameters": { "truncate": "END" } }' ``` The response looks as follows. For each hit, the \_score represents the relevance of a document to the query, normalized between 0 and 1, with scores closer to 1 indicating higher relevance. ```python Python theme={null} RerankResult( model='bge-reranker-v2-m3', data=[{ index=0, score=0.004166256, document={ id='vec2', chunk_text="Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market." } },{ index=2, score=0.0011513996, document={ id='vec1', chunk_text='AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.' } }], usage={'rerank_units': 1} ) ``` ```javascript JavaScript theme={null} { model: 'bge-reranker-v2-m3', data: [ { index: 0, score: 0.004166256, document: [id: 'vec2', chunk_text: "Analysts suggest that AAPL'''s upcoming Q4 product launch event might solidify its position in the premium smartphone market."] }, { index: 2, score: 0.0011513996, document: [id: 'vec1', chunk_text: 'AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.'] } ], usage: { rerankUnits: 1 } } ``` ```java Java theme={null} [class RankedDocument { index: 0 score: 0.0063143647 document: {id=vec2, chunk_text=Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market.} additionalProperties: null }, class RankedDocument { index: 2 score: 0.0011513996 document: {id=vec1, chunk_text=AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.} additionalProperties: null }] ``` ```go Go theme={null} { "data": [ { "document": { "id": "vec2", "chunk_text": "Analysts suggest that AAPL's upcoming Q4 product launch event might solidify its position in the premium smartphone market." }, "index": 0, "score": 0.0063143647 }, { "document": { "id": "vec1", "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones." }, "index": 2, "score": 0.0011513996 } ], "model": "bge-reranker-v2-m3", "usage": { "rerank_units": 1 } } ``` ```csharp C# theme={null} { "model": "bge-reranker-v2-m3", "data": [ { "index": 0, "score": 0.006289902, "document": { "chunk_text": "Analysts suggest that AAPL\u0027s upcoming Q4 product launch event might solidify its position in the premium smartphone market.", "id": "vec2" } }, { "index": 3, "score": 0.0011513996, "document": { "chunk_text": "AAPL reported a year-over-year revenue increase, expecting stronger Q3 demand for its flagship phones.", "id": "vec1" } } ], "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 } } ``` ## Reranking models Pinecone hosts several reranking models so it's easy to manage two-stage vector retrieval on a single platform. You can use a hosted model to rerank results as an integrated part of a query, or you can use a hosted model to rerank results as a standalone operation. The following reranking models are hosted by Pinecone. To understand how cost is calculated for reranking, see [Reranking cost](/guides/manage-cost/understanding-cost#reranking). To get model details via the API, see [List models](/reference/api/latest/inference/list_models) and [Describe a model](/reference/api/latest/inference/describe_model). [`cohere-rerank-3.5`](/models/cohere-rerank-3.5) is Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications. **Details** * Modality: Text * Max tokens per query and document pair: 40,000 * Max documents: 200 For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `cohere-rerank-3.5` model supports the following parameters: | Parameter | Type | Required/Optional | Description | | | :------------------- | :--------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `max_chunks_per_doc` | integer | Optional | Long documents will be automatically truncated to the specified number of chunks. Accepted range: `1 - 3072`. | | | `rank_fields` | array of strings | Optional | The fields to use for reranking. The model reranks based on the order of the fields specified (e.g., `["field1", "field2", "field3"]`). | `["text"]` | [`bge-reranker-v2-m3`](/models/bge-reranker-v2-m3) is a high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs). **Details** * Modality: Text * Max tokens per query and document pair: 1024 * Max documents: 100 For rate limits, see [Rerank requests per minute](/reference/api/database-limits#rerank-requests-per-minute-per-model) and [Rerank request per month](/reference/api/database-limits#rerank-requests-per-month-per-model). **Parameters** The `bge-reranker-v2-m3` model supports the following parameters: | Parameter | Type | Required/Optional | Description | Default | | :------------ | :--------------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------- | | `truncate` | string | Optional | How to handle inputs longer than those supported by the model. Accepted values: `END` or `NONE`.

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

`END` truncates the input sequence at the input token limit. `NONE` returns an error when the input exceeds the input token limit. | `END` | | `rank_fields` | array of strings | Optional | The field to use for reranking. The model supports only a single rerank field. | `["text"]` | # Search overview Source: https://docs.pinecone.io/guides/search/search-overview Explore semantic, lexical, and hybrid search options. ## Search types * [Semantic search](/guides/search/semantic-search) * [Lexical search](/guides/search/lexical-search) * [Hybrid search](/guides/search/hybrid-search) ## Optimization * [Filter by metadata](/guides/search/filter-by-metadata) * [Rerank results](/guides/search/rerank-results) * [Parallel queries](/guides/search/semantic-search#parallel-queries) ## Limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. ## Cost * To understand how cost is calculated for queries, see [Understanding cost](/guides/manage-cost/understanding-cost#query). * For up-to-date pricing information, see [Pricing](https://www.pinecone.io/pricing/). ## Data freshness Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. You can view index stats to [check data freshness](/guides/index-data/check-data-freshness). # Semantic search Source: https://docs.pinecone.io/guides/search/semantic-search Find semantically similar records using dense vectors. This page shows you how to search a [dense index](/guides/index-data/indexing-overview#dense-indexes) for records that are most similar in meaning and context to a query. This is often called semantic search, nearest neighbor search, similarity search, or just vector search. Semantic search uses [dense vectors](https://www.pinecone.io/learn/vector-embeddings/). Each number in a dense vector corresponds to a point in a multidimensional space. Vectors that are closer together in that space are semantically similar. ## Search with text Searching with text is supported only for [indexes with integrated embedding](/guides/index-data/indexing-overview#integrated-embedding). To search a dense index with a query text, use the [`search_records`](/reference/api/latest/data-plane/search_records) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `query.inputs.text` parameter with the query text. Pinecone uses the embedding model integrated with the index to convert the text to a dense vector automatically. * The `query.top_k` parameter with the number of similar records to return. * Optionally, you can specify the `fields` to return in the response. If not specified, the response will include all fields. For example, the following code searches for the 2 records most semantically related to a query text: ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") results = index.search( namespace="example-namespace", query={ "inputs": {"text": "Disease prevention"}, "top_k": 2 }, fields=["category", "chunk_text"] ) print(results) ``` ```javascript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const namespace = pc.index("INDEX_NAME", "INDEX_HOST").namespace("example-namespace"); const response = await namespace.searchRecords({ query: { topK: 2, inputs: { text: 'Disease prevention' }, }, fields: ['chunk_text', 'category'], }); console.log(response); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import org.openapitools.db_data.client.ApiException; import org.openapitools.db_data.client.model.SearchRecordsResponse; import java.util.*; public class SearchText { public static void main(String[] args) throws ApiException { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(config, connection, "integrated-dense-java"); String query = "Disease prevention"; List fields = new ArrayList<>(); fields.add("category"); fields.add("chunk_text"); // Search the dense index SearchRecordsResponse recordsResponse = index.searchRecordsByText(query, "example-namespace", fields, 2, null, null); // Print the results System.out.println(recordsResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } res, err := idxConnection.SearchRecords(ctx, &pinecone.SearchRecordsRequest{ Query: pinecone.SearchRecordsQuery{ TopK: 2, Inputs: &map[string]interface{}{ "text": "Disease prevention", }, }, Fields: &[]string{"chunk_text", "category"}, }) if err != nil { log.Fatalf("Failed to search records: %v", err) } fmt.Printf(prettifyStruct(res)) } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var response = await index.SearchRecordsAsync( "example-namespace", new SearchRecordsRequest { Query = new SearchRecordsRequestQuery { TopK = 4, Inputs = new Dictionary { { "text", "Disease prevention" } }, }, Fields = ["category", "chunk_text"], } ); Console.WriteLine(response); ``` ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: unstable" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 2 }, "fields": ["category", "chunk_text"] }' ``` The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index. ```python Python theme={null} {'result': {'hits': [{'_id': 'rec3', '_score': 0.8204272389411926, 'fields': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples ' 'contribute to immune health ' 'and may reduce the risk of ' 'chronic diseases.'}}, {'_id': 'rec1', '_score': 0.7931625843048096, 'fields': {'category': 'digestive system', 'chunk_text': 'Apples are a great source of ' 'dietary fiber, which supports ' 'digestion and helps maintain a ' 'healthy gut.'}}]}, 'usage': {'embed_total_tokens': 8, 'read_units': 6}} ``` ```javascript JavaScript theme={null} { result: { hits: [ { _id: 'rec3', _score: 0.82042724, fields: { category: 'immune system', chunk_text: 'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.' } }, { _id: 'rec1', _score: 0.7931626, fields: { category: 'digestive system', chunk_text: 'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.' } } ] }, usage: { readUnits: 6, embedTotalTokens: 8 } } ``` ```java Java theme={null} class SearchRecordsResponse { result: class SearchRecordsResponseResult { hits: [class Hit { id: rec3 score: 0.8204272389411926 fields: {category=immune system, chunk_text=Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.} additionalProperties: null }, class Hit { id: rec1 score: 0.7931625843048096 fields: {category=endocrine system, chunk_text=Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.} additionalProperties: null }] additionalProperties: null } usage: class SearchUsage { readUnits: 6 embedTotalTokens: 13 } additionalProperties: null } ``` ```go Go theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.82042724, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec1", "_score": 0.7931626, "fields": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } ] }, "usage": { "read_units": 6, "embed_total_tokens": 8 } } ``` ```csharp C# theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.13741668, "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.0023413408, "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": 5, "rerank_units": 1 } } ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.82042724, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec1", "_score": 0.7931626, "fields": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6 } } ``` ## Search with a dense vector To search a dense index with a dense vector representation of a query, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `vector` parameter with the dense vector values representing your query. * The `top_k` parameter with the number of results to return. * Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. However, when querying with `top_k` over 1000, avoid returning vector data or metadata for optimal performance. For example, the following code uses a dense vector representation of the query “Disease prevention” to search for the 3 most semantically similar records in the `example-namespaces` namespace: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", vector=[0.0236663818359375,-0.032989501953125, ..., -0.01041412353515625,0.0086669921875], top_k=3, include_metadata=True, include_values=False ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ vector: [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; import java.util.Arrays; import java.util.List; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); List query = Arrays.asList(0.0236663818359375f, -0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f); QueryResponseWithUnsignedIndices queryResponse = index.query(3, query, null, null, null, "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } queryVector := []float32{0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875} res, err := idxConnection.QueryByVectorValues(ctx, &pinecone.QueryByVectorValuesRequest{ Vector: queryVector, TopK: 3, IncludeValues: false, includeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector: %v", err) } else { fmt.Printf(prettifyStruct(res)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var queryResponse = await index.QueryAsync(new QueryRequest { Vector = new[] { 0.0236663818359375f ,-0.032989501953125f, ..., -0.01041412353515625f, 0.0086669921875f }, Namespace = "example-namespace", TopK = 3, IncludeMetadata = true, }); Console.WriteLine(queryResponse); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vector": [0.0236663818359375,-0.032989501953125,...,-0.01041412353515625,0.0086669921875], "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` The response will look as follows. Each record is returned with a similarity score that represents its distance to the query vector, calculated according to the [similarity metric](/guides/index-data/create-an-index#similarity-metrics) for the index. ```python Python theme={null} {'matches': [{'id': 'rec3', 'metadata': {'category': 'immune system', 'chunk_text': 'Rich in vitamin C and other ' 'antioxidants, apples contribute to ' 'immune health and may reduce the ' 'risk of chronic diseases.'}, 'score': 0.82026422, 'values': []}, {'id': 'rec1', 'metadata': {'category': 'digestive system', 'chunk_text': 'Apples are a great source of ' 'dietary fiber, which supports ' 'digestion and helps maintain a ' 'healthy gut.'}, 'score': 0.793068111, 'values': []}, {'id': 'rec4', 'metadata': {'category': 'endocrine system', 'chunk_text': 'The high fiber content in apples ' 'can also help regulate blood sugar ' 'levels, making them a favorable ' 'snack for people with diabetes.'}, 'score': 0.780169606, 'values': []}], 'namespace': 'example-namespace', 'usage': {'read_units': 6}} ``` ```JavaScript JavaScript theme={null} { matches: [ { id: 'rec3', score: 0.819709897, values: [], sparseValues: undefined, metadata: [Object] }, { id: 'rec1', score: 0.792900264, values: [], sparseValues: undefined, metadata: [Object] }, { id: 'rec4', score: 0.780068815, values: [], sparseValues: undefined, metadata: [Object] } ], namespace: 'example-namespace', usage: { readUnits: 6 } } ``` ```java Java theme={null} class QueryResponseWithUnsignedIndices { matches: [ScoredVectorWithUnsignedIndices { score: 0.8197099 id: rec3 values: [] metadata: fields { key: "category" value { string_value: "immune system" } } fields { key: "chunk_text" value { string_value: "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.79290026 id: rec1 values: [] metadata: fields { key: "category" value { string_value: "digestive system" } } fields { key: "chunk_text" value { string_value: "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }, ScoredVectorWithUnsignedIndices { score: 0.7800688 id: rec4 values: [] metadata: fields { key: "category" value { string_value: "endocrine system" } } fields { key: "chunk_text" value { string_value: "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } sparseValuesWithUnsignedIndices: SparseValuesWithUnsignedIndices { indicesWithUnsigned32Int: [] values: [] } }] namespace: example-namespace usage: read_units: 6 } ``` ```go Go theme={null} { "matches": [ { "vector": { "id": "rec3", "metadata": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, "score": 0.8197099 }, { "vector": { "id": "rec1", "metadata": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } }, "score": 0.79290026 }, { "vector": { "id": "rec4", "metadata": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } }, "score": 0.7800688 } ], "usage": { "read_units": 6 }, "namespace": "example-namespace" } ``` ```csharp C# theme={null} { "results": [], "matches": [ { "id": "rec3", "score": 0.8197099, "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.79290026, "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.7800688, "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 } } ``` ```json curl theme={null} { "results": [], "matches": [ { "id": "rec3", "score": 0.820593238, "values": [], "metadata": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "id": "rec1", "score": 0.792266726, "values": [], "metadata": { "category": "digestive system", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut." } }, { "id": "rec4", "score": 0.780045748, "values": [], "metadata": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ], "namespace": "example-namespace", "usage": { "readUnits": 6 } } ``` ## Search with a record ID When you search with a record ID, Pinecone uses the dense vector associated with the record as the query. To search a dense index with a record ID, use the [`query`](/reference/api/latest/data-plane/query) operation with the following parameters: * The `namespace` to query. To use the default namespace, set the namespace to `"__default__"`. * The `id` parameter with the unique record ID containing the vector to use as the query. * The `top_k` parameter with the number of results to return. * Optionally, you can set `include_values` and/or `include_metadata` to `true` to include the vector values and/or metadata of the matching records in the response. However, when querying with `top_k` over 1000, avoid returning vector data or metadata for optimal performance. For example, the following code uses an ID to search for the 3 records in the `example-namespace` namespace that are most semantically similar to the dense vector in the record: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.query( namespace="example-namespace", id="rec2", top_k=3, include_metadata=True, include_values=False ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone' const pc = new Pinecone({ apiKey: "YOUR_API_KEY" }) // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index const index = pc.index("INDEX_NAME", "INDEX_HOST") const queryResponse = await index.namespace('example-namespace').query({ id: 'rec2', topK: 3, includeValues: false, includeMetadata: true, }); ``` ```java Java theme={null} import io.pinecone.clients.Index; import io.pinecone.configs.PineconeConfig; import io.pinecone.configs.PineconeConnection; import io.pinecone.unsigned_indices_model.QueryResponseWithUnsignedIndices; public class QueryExample { public static void main(String[] args) { PineconeConfig config = new PineconeConfig("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index config.setHost("INDEX_HOST"); PineconeConnection connection = new PineconeConnection(config); Index index = new Index(connection, "INDEX_NAME"); QueryResponseWithUnsignedIndices queryRespone = index.queryByVectorId(3, "rec2", "example-namespace", null, false, true); System.out.println(queryResponse); } } ``` ```go Go theme={null} package main import ( "context" "encoding/json" "fmt" "log" "github.com/pinecone-io/go-pinecone/v4/pinecone" ) func prettifyStruct(obj interface{}) string { bytes, _ := json.MarshalIndent(obj, "", " ") return string(bytes) } func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index idxConnection, err := pc.Index(pinecone.NewIndexConnParams{Host: "INDEX_HOST", Namespace: "example-namespace"}) if err != nil { log.Fatalf("Failed to create IndexConnection for Host: %v", err) } vectorId := "rec2" res, err := idxConnection.QueryByVectorId(ctx, &pinecone.QueryByVectorIdRequest{ VectorId: vectorId, TopK: 3, IncludeValues: false, IncludeMetadata: true, }) if err != nil { log.Fatalf("Error encountered when querying by vector ID `%v`: %v", vectorId, err) } else { fmt.Printf(prettifyStruct(res.Matches)) } } ``` ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); // To get the unique host for an index, // see https://docs.pinecone.io/guides/manage-data/target-an-index var index = pinecone.Index(host: "INDEX_HOST"); var queryResponse = await index.QueryAsync(new QueryRequest { Id = "rec2", Namespace = "example-namespace", TopK = 3, IncludeValues = false, IncludeMetadata = true }); Console.WriteLine(queryResponse); ``` ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "rec2", "namespace": "example-namespace", "topK": 3, "includeMetadata": true, "includeValues": false }' ``` ## Parallel queries Python SDK v6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Async support makes it possible to use Pinecone with modern async web frameworks such as FastAPI, Quart, and Sanic, and can significantly increase the efficiency of running queries in parallel. For more details, see the [Async requests](/reference/python-sdk#async-requests). # Configure an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/configure_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml patch /indexes/{index_name} Configure an existing index. For serverless indexes, you can configure index deletion protection, tags, and integrated inference embedding settings for the index. For pod-based indexes, you can configure the pod size, number of replicas, tags, and index deletion protection. It is not possible to change the pod type of a pod-based index. However, you can create a collection from a pod-based index and then [create a new pod-based index with a different pod type](http://docs.pinecone.io/guides/indexes/pods/create-a-pod-based-index#create-a-pod-index-from-a-collection) from the collection. For guidance and examples, see [Configure an index](http://docs.pinecone.io/guides/indexes/pods/manage-pod-based-indexes). ```shell curl theme={null} # EXAMPLE REQUEST 1: Serverless index (on-demand) # Enable deletion protection and add tags to an # existing on-demand index. PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" } }' # EXAMPLE REQUEST 2: Serverless index (dedicated) # Add a replica to an existing dedicated index. PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl -X PATCH "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "spec": { "serverless": { "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 2 } } } } } }' ``` ```json curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) // Enable deletion protection and add tags to an // existing on-demand index. { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) // Add a replica to an existing dedicated index. { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 <-- desired state } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 <-- current state } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } ``` # Create an index with integrated embedding Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/create_for_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml post /indexes/create-for-model Create an index with integrated embedding. With this type of index, you provide source text, and Pinecone uses a [hosted embedding model](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models) to convert the text automatically during [upsert](https://docs.pinecone.io/reference/api/2025-10/data-plane/upsert_records) and [search](https://docs.pinecone.io/reference/api/2025-10/data-plane/search_records). For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index#integrated-embedding). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/indexes/create-for-model \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "integrated-dense-curl", "cloud": "aws", "region": "us-east-1", "embed": { "model": "llama-text-embed-v2", "metric": "cosine", "field_map": { "text": "chunk_text" }, "write_parameters": { "input_type": "passage", "truncate": "END" }, "read_parameters": { "input_type": "query", "truncate": "END" } } }' ``` ```json curl theme={null} { "id": "9dabb7cb-ec0a-4e2e-b79e-c7c997e592ce", "name": "integrated-dense-curl", "metric": "cosine", "dimension": 1024, "status": { "ready": false, "state": "Initializing" }, "host": "integrated-dense-curl-govk0nt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws" } }, "deletion_protection": "disabled", "tags": null, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "chunk_text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "input_type": "passage", "truncate": "END" }, "read_parameters": { "input_type": "query", "truncate": "END" } } } ``` # Create an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/create_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml post /indexes Create a Pinecone index. This is where you specify the measure of similarity, the dimension of vectors to be stored in the index, which cloud provider you would like to deploy with, and more. For guidance and examples, see [Create an index](https://docs.pinecone.io/guides/index-data/create-an-index). ```shell curl theme={null} # EXAMPLE REQUEST 1: Serverless index (on-demand) PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-serverless-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1" } }, "tags": { "tag0": "value0" }, "deletion_protection": "disabled" }' # EXAMPLE REQUEST 2: Serverless index (dedicated) PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-serverless-dedicated-index", "dimension": 1536, "metric": "cosine", "deletion_protection": "enabled", "tags": { "tag0": "value0" }, "vector_type": "dense", "spec": { "serverless": { "cloud": "aws", "region": "us-east-1", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } } } } } }' # EXAMPLE REQUEST 3: BYOC index PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/indexes" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-byoc-index", "vector_type": "dense", "dimension": 1536, "metric": "cosine", "spec": { "byoc": { "environment": "aws-us-east-1-b921" } }, "tags": { "tag0": "value0" }, "deletion_protection": "disabled" }' ``` ```json curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "disabled", "tags": { "tag0": "value0" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": false, "state": "Initializing" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 2, "replicas": 1 } }, "status": { "state": "Migrating", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0" } } // EXAMPLE RESPONSE 3: BYOC index { "name": "example-byoc-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-byoc-index-govk0nt.svc.private.aped-4627-b74a.pinecone.io", "spec": { "byoc": { "environment": "aws-us-east-1-b921" } }, "deletion_protection": "disabled", "tags": { "tag0": "value0" } } ``` # Delete an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/delete_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml delete /indexes/{index_name} Delete an existing index. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/indexes/docs-example" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` # Describe an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/describe_index https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /indexes/{index_name} Get a description of an index. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="YOUR_INDEX_NAME" curl "https://api.pinecone.io/indexes/$INDEX_NAME" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } } // EXAMPLE RESPONSE 2: Serverless index (dedicated) { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0", "tag1": "value1" } } ``` # List indexes Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/list_indexes https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /indexes List all indexes in a project. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/indexes" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "indexes": [ { "name": "example-serverless-dedicated-index", "vector_type": "dense", "metric": "cosine", "dimension": 1536, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-dedicated-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "Dedicated", "dedicated": { "node_type": "b1", "scaling": "Manual", "manual": { "shards": 1, "replicas": 2 } }, "status": { "state": "Scaling", "current_shards": 1, "current_replicas": 1 } } } }, "deletion_protection": "enabled", "tags": { "tag0": "value0", "tag1": "value1" } }, { "name": "example-serverless-ondemand-index", "vector_type": "dense", "metric": "cosine", "dimension": 1024, "status": { "ready": true, "state": "Ready" }, "host": "example-serverless-ondemand-index-bhnyigt.svc.aped-4627-b74a.pinecone.io", "spec": { "serverless": { "region": "us-east-1", "cloud": "aws", "read_capacity": { "mode": "OnDemand", "status": { "state": "Ready", "current_shards": null, "current_replicas": null } } } }, "deletion_protection": "enabled", "tags": { "tag1": "value1", "tag2": "value2" }, "embed": { "model": "llama-text-embed-v2", "field_map": { "text": "text" }, "dimension": 1024, "metric": "cosine", "write_parameters": { "dimension": 1024, "input_type": "passage", "truncate": "END" }, "read_parameters": { "dimension": 1024, "input_type": "query", "truncate": "END" }, "vector_type": "dense" } }, { "name": "example-pod-index", "vector_type": "dense", "metric": "cosine", "dimension": 768, "status": { "ready": true, "state": "Ready" }, "host": "example-pod-index-bhnyigt.svc.us-east-1-aws.pinecone.io", "spec": { "pod": { "replicas": 1, "shards": 1, "pods": 1, "pod_type": "s1.x1", "environment": "us-east-1-aws" } }, "deletion_protection": "disabled", "tags": null } ] } ``` # Create a namespace Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/createnamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /namespaces Create a namespace in a serverless index. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-namespace", "schema": { "fields": { "document_id": {"filterable": true}, "document_title": {"filterable": true}, "chunk_number": {"filterable": true}, "document_url": {"filterable": true}, "created_at": {"filterable": true} } } }' ``` ```json curl theme={null} { "name": "example-namespace", "record_count": "0", "schema": { "fields": { "document_title": { "filterable": true }, "document_url": { "filterable": true }, "chunk_number": { "filterable": true }, "document_id": { "filterable": true }, "created_at": { "filterable": true } } } } ``` # Delete vectors Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/delete https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /vectors/delete Delete vectors by id from a single namespace. For guidance and examples, see [Delete data](https://docs.pinecone.io/guides/manage-data/delete-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/delete" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "ids": [ "id-1", "id-2" ], "namespace": "example-namespace" } ' ``` ```json curl theme={null} {} ``` # Delete a namespace Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/deletenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml delete /namespaces/{namespace} Delete a namespace from a serverless index. Deleting a namespace is irreversible; all data in the namespace is permanently deleted. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__". curl -X DELETE "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` # Get index stats Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/describeindexstats https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.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. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" curl -X POST "https://$INDEX_HOST/describe_index_stats" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} // EXAMPLE RESPONSE 1: Serverless index (on-demand) { "namespaces": { "example-namespace": { "vectorCount": 10000 } }, "indexFullness": 0, "totalVectorCount": 10000, "dimension": 1024, "metric": "cosine", "vectorType": "dense" } // EXAMPLE RESPONSE 2: Serverless index (dedicated) { "namespaces": { "example-namespace": { "vectorCount": 10000 } }, "indexFullness": 0.000309539, "totalVectorCount": 10000, "dimension": 1536, "metric": "cosine", "vectorType": "dense" } ``` # Describe a namespace Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/describenamespace https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /namespaces/{namespace} Describe a namespace in a serverless index, including the total number of vectors in the namespace. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="YOUR_INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" # To target the default namespace, use "__default__". curl "https://$INDEX_HOST/namespaces/$NAMESPACE" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "name": "example-namespace", "record_count": 20000 } ``` # Fetch vectors Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/fetch https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /vectors/fetch Look up and return vectors by ID from a single namespace. The returned vectors include the vector data and/or metadata. For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/fetch?ids=id-1&ids=id-2&namespace=example-namespace" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```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 vectors by metadata Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/fetch_by_metadata https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /vectors/fetch_by_metadata Look up and return vectors by metadata filter from a single namespace. The returned vectors include the vector data and/or metadata. For guidance and examples, see [Fetch data](https://docs.pinecone.io/guides/manage-data/fetch-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/vectors/fetch_by_metadata" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "filter": {"rating": {"$lt": 5}}, "limit": 2 }' ``` ```json curl theme={null} { "vectors": { "id-1": { "id": "id-1", "values": [ -0.0273742676, -0.000517368317, ... ], "metadata": { "main_category": "Books", "rating": 4, "review": "Identical twins have only one purpose in movies and plays: to cause mass confusion...", "title": "A comedy of twin-switching" } }, "id-2": { "id": "id-2", "values": [ -0.00305938721, 0.0234375, ... ], "metadata": { "main_category": "Automotive", "rating": 1, "review": "If I could rate this 1/2 a star I would! These both broke within 10 minutes of using it. The only upside is the cloth is removable so it can be used with good old fashioned elbow grease. Epic waste!", "title": "Dont waste your money!" } } }, "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` # List vector IDs Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/list https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /vectors/list List the IDs of vectors in a single namespace of a serverless index. An optional prefix can be passed to limit the results to IDs with a common prefix. Returns up to 100 IDs at a time by default in sorted order (bitwise "C" collation). If the `limit` parameter is set, `list` returns up to that number of IDs instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of IDs. When the response does not include a `pagination_token`, there are no more IDs to return. For guidance and examples, see [List record IDs](https://docs.pinecone.io/guides/manage-data/list-record-ids). **Note:** `list` is supported only for serverless indexes. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/vectors/list?namespace=example-namespace&prefix=doc1#&limit=3" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "vectors": [ { "id": "doc1#chunk1" }, { "id": "doc1#chunk2" }, { "id": "doc1#chunk3" } ], "pagination": { "next": "c2Vjb25kY2FsbA==" }, "namespace": "example-namespace", "usage": { "readUnits": 1 } } ``` # List namespaces Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/listnamespaces https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /namespaces List all namespaces in a serverless index. Up to 100 namespaces are returned at a time by default, in sorted order (bitwise “C” collation). If the `limit` parameter is set, up to that number of namespaces are returned instead. Whenever there are additional namespaces to return, the response also includes a `pagination_token` that you can use to get the next batch of namespaces. When the response does not include a `pagination_token`, there are no more namespaces to return. For guidance and examples, see [Manage namespaces](https://docs.pinecone.io/guides/manage-data/manage-namespaces). **Note:** This operation is not supported for pod-based indexes. ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/namespaces" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "namespaces": [ { "name": "example-namespace", "record_count": 20000 }, { "name": "example-namespace2", "record_count": 10500 }, ... ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` # Update a vector Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/update https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /vectors/update Update a vector in a namespace. If a value is included, it will overwrite the previous value. If a `set_metadata` is included, the values of the fields specified in it will be added or overwrite the previous value. For guidance and examples, see [Update data](https://docs.pinecone.io/guides/manage-data/update-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/update" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "id": "id-3", "values": [4.0, 2.0], "setMetadata": {"type": "comedy"}, "namespace": "example-namespace" }' ``` ```json curl theme={null} {} ``` # Upsert vectors Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/upsert https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /vectors/upsert Upsert vectors into a namespace. If a new value is upserted for an existing vector ID, it will overwrite the previous value. For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data). To control costs when ingesting large datasets (10,000,000+ records), use [import](/guides/index-data/import-data) instead of upsert. ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "vectors": [ { "id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1], "metadata": {"genre": "comedy", "year": 2020} }, { "id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2], "metadata": {"genre": "documentary", "year": 2019} } ], "namespace": "example-namespace" }' ``` ``` ``` # Upsert text Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/upsert_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /records/namespaces/{namespace}/upsert Upsert text into a namespace. Pinecone converts the text to vectors automatically using the hosted embedding model associated with the index. Upserting text is supported only for [indexes with integrated embedding](https://docs.pinecone.io/reference/api/2025-01/control-plane/create_for_model). For guidance, examples, and limits, see [Upsert data](https://docs.pinecone.io/guides/index-data/upsert-data). ```shell curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Upsert records into a namespace # `chunk_text` fields are converted to dense vectors # `category` fields are stored as metadata curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/upsert" \ -H "Content-Type: application/x-ndjson" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{"_id": "rec1", "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.", "category": "digestive system"} {"_id": "rec2", "chunk_text": "Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.", "category": "cultivation"} {"_id": "rec3", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.", "category": "immune system"} {"_id": "rec4", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.", "category": "endocrine system"}' ``` # Authentication Source: https://docs.pinecone.io/reference/api/authentication All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits This page describes different types of limits for Pinecone Database. ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. | Metric | Starter plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :------------- | :------------- | :-------------- | | [Read units per month per project](#read-units-per-month-per-project) | 1,000,000 | Unlimited | Unlimited | | [Write units per month per project](#write-units-per-month-per-project) | 2,000,000 | Unlimited | Unlimited | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | Unlimited | Unlimited | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | 500 | Model-specific | Model-specific | ### Read units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for a project, fetch, query, and list requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for a project, upsert, update, and delete requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. ### Upsert size per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 20 | 100 | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 20 | 200 | | [Serverless index storage per project](#serverless-index-storage-per-project) | 2 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 100,000 | 100,000 | | [Serverless backups per project](#serveless-backups-per-project) | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | 1 On the Starter plan, all serverless must be in the `us-east-1` region of AWS.
### Projects per organization | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless indexes per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per project This limit applies to organizations on the Starter plan only. | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2 GB | N/A | N/A | When you've reached this quota for a project, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for project . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your project under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). While the Standard and Enterprise plans support up to [100,000 namespaces per index](/reference/api/database-limits#namespaces-per-serverless-index), Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | N/A | 500 | 1000 | When you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max metadata size per record | 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 | ### Import limits If your import exceeds these limits, you'll get an `Exceeds system limit` error. Pinecone can help unblock these imports quickly. [Contact Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance. | Metric | Limit | | :------------------------ | :------ | | Max namespaces per import | 10,000 | | Max size per namespace | 500 GB | | Max files per import | 100,000 | | Max size per file | 10 GB | ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. ### Fetch limits | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment. ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/connect-to-aws-privatelink) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, based on the version support diagram above, if it is currently October 2025 and you want to use the latest stable version to describe an index, you would set `"X-Pinecone-Api-Version: 2025-10"`: ```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: 2025-10" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # Create an API key Source: https://docs.pinecone.io/reference/api/2025-10/admin/create_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml post /admin/projects/{project_id}/api-keys Create a new API key for a project. Developers can use the API key to authenticate requests to Pinecone's Data Plane and Control Plane APIs. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_PROJECT_ID="YOUR_PROJECT_ID" curl "https://api.pinecone.io/admin/projects/$PINECONE_PROJECT_ID/api-keys" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "Example API Key", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Example API key", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Create a new project Source: https://docs.pinecone.io/reference/api/2025-10/admin/create_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml post /admin/projects Creates a new project. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" curl "https://api.pinecone.io/admin/projects" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name":"example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-16T22:46:45.030Z" } ``` # Delete an API key Source: https://docs.pinecone.io/reference/api/2025-10/admin/delete_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml delete /admin/api-keys/{api_key_id} Delete an API key from a project. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_KEY_ID" curl -X DELETE "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Delete a project Source: https://docs.pinecone.io/reference/api/2025-10/admin/delete_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml delete /admin/projects/{project_id} Delete a project and all its associated configuration. Before deleting a project, you must delete all indexes, assistants, backups, and collections associated with the project. Other project resources, such as API keys, are automatically deleted when the project is deleted. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="YOUR_PROJECT_ID" curl -X DELETE "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" ``` # Get API key details Source: https://docs.pinecone.io/reference/api/2025-10/admin/fetch_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml get /admin/api-keys/{api_key_id} Get the details of an API key, excluding the API key secret. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ``` # Get project details Source: https://docs.pinecone.io/reference/api/2025-10/admin/fetch_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml get /admin/projects/{project_id} Get details about a project. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PROJECT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6" curl -X GET "https://api.pinecone.io/admin/projects/$PROJECT_ID" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:30:23.262Z" } ``` # Create an access token Source: https://docs.pinecone.io/reference/api/2025-10/admin/get_token https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/oauth_2025-10.oas.yaml post /oauth/token Obtain an access token for a service account using the OAuth2 client credentials flow. An access token is needed to authorize requests to the Pinecone Admin API. The host domain for OAuth endpoints is `login.pinecone.io`. ```bash curl theme={null} curl "https://login.pinecone.io/oauth/token" \ # Note: Base URL is login.pinecone.io -H "X-Pinecone-Api-Version: 2025-10" \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "audience": "https://api.pinecone.io/" }' ``` ```json curl theme={null} { "access_token":"YOUR_ACCESS_TOKEN", "expires_in":86400, "token_type":"Bearer" } ``` # List API keys Source: https://docs.pinecone.io/reference/api/2025-10/admin/list_api_keys https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml get /admin/projects/{project_id}/api-keys List all API keys in a project. ```bash curl theme={null} curl -X GET "https://api.pinecone.io/admin/projects" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] } ] } ``` # List projects Source: https://docs.pinecone.io/reference/api/2025-10/admin/list_projects https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml get /admin/projects List all projects in an organization. ```bash curl theme={null} curl -X GET "https://api.pinecone.io/admin/projects" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "data": [ { "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "name": "example-project", "max_pods": 0, "force_encryption_with_cmek": true, "organization_id": "", "created_at": "2023-11-07T05:31:56Z" } ] } ``` # Update an API key Source: https://docs.pinecone.io/reference/api/2025-10/admin/update_api_key https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml patch /admin/api-keys/{api_key_id} Update the name and roles of an API key. ```bash curl theme={null} PINECONE_ACCESS_TOKEN="YOUR_ACCESS_TOKEN" PINECONE_API_KEY_ID="YOUR_API_KEY_ID" curl -X PATCH "https://api.pinecone.io/admin/api-keys/$PINECONE_API_KEY_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Authorization: Bearer $PINECONE_ACCESS_TOKEN" \ -d '{ "name": "New API key name", "roles": ["ProjectEditor"] }' ``` ```json curl theme={null} { "key": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "New API key name", "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": [ "ProjectEditor" ] }, "value": "string" } ``` # Update a project Source: https://docs.pinecone.io/reference/api/2025-10/admin/update_project https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/admin_2025-10.oas.yaml patch /admin/projects/{project_id} Update a project's configuration details. You can update the project's name, maximum number of Pods, or enable encryption with a customer-managed encryption key (CMEK). ```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 '{ "name": "updated-example-project" }' ``` ```json curl theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "updated-example-project", "max_pods": 0, "force_encryption_with_cmek": false, "organization_id": "string", "created_at": "2025-03-17T00:42:31.912Z" } ``` # Create a backup of an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/create_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml post /indexes/{index_name}/backups Create a backup of an index. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-backup", "description": "Monthly backup of production index" }' ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":96, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-05-14T16:37:25.625540Z" } ``` # Create a collection Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/create_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml post /collections Create a Pinecone collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -s "https://api.pinecone.io/collections" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "example-collection", "source": "docs-example" }' ``` ```json curl theme={null} { "name": "example-collection", "status": "Initializing", "environment": "us-east-1-aws", "dimension": 1536 } ``` # Create an index from a backup Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/create_index_from_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml post /backups/{backup_id}/create-index Create an index from a backup. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="a65ff585-d987-4da5-a622-72e19a6ed5f4" curl "https://api.pinecone.io/backups/$BACKUP_ID/create-index" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H 'Content-Type: application/json' \ -d '{ "name": "restored-index", "tags": { "tag0": "val0", "tag1": "val1" }, "deletion_protection": "enabled" }' ``` ```json curl theme={null} { "restore_job_id":"e9ba8ff8-7948-4cfa-ba43-34227f6d30d4", "index_id":"025117b3-e683-423c-b2d1-6d30fbe5027f" } ``` # Delete a backup Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/delete_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml delete /backups/{backup_id} Delete a backup. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="9947520e-d5a1-4418-a78d-9f464c9969da" curl -X DELETE "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` # Delete a collection Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/delete_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml delete /collections/{collection_name} Delete an existing collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X DELETE "https://api.pinecone.io/collections/example-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` # Describe a backup Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/describe_backup https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /backups/{backup_id} Get a description of a backup. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" BACKUP_ID="8c85e612-ed1c-4f97-9f8c-8194e07bcf71" curl -X GET "https://api.pinecone.io/backups/$BACKUP_ID" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```json curl theme={null} { "backup_id":"8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id":"f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Ready", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ``` # Describe a collection Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/describe_collection https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /collections/{collection_name} Get a description of a collection. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections/tiny-collection" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "name": "example-collection", "status": "Ready", "environment": "us-east-1-aws", "size": 3075398, "vector_count": 99, "dimension": 1536 } ``` # Describe a restore job Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/describe_restore_job https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /restore-jobs/{job_id} Get a description of a restore job. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" JOB_ID="9857add2-99d4-4399-870e-aa7f15d8d326" curl "https://api.pinecone.io/restore-jobs/$JOB_ID" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'accept: application/json' ``` ```json curl theme={null} { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 } ``` # List collections Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/list_collections https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /collections List all collections in a project. Serverless indexes do not support collections. ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -i -X GET "https://api.pinecone.io/collections" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "collections": [ { "name": "example-collection1", "status": "Ready", "environment": "us-east-1-aws", "size": 3081918, "vector_count": 99, "dimension": 3 }, { "name": "example-collection1", "status": "Ready", "environment": "us-east-1-aws", "size": 160087040000000, "vector_count": 10000000, "dimension": 1536 } ] } ``` # List backups for an index Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/list_index_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /indexes/{index_name}/backups List all backups for an index. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_NAME="docs-example" curl -X GET "https://api.pinecone.io/indexes/$INDEX_NAME/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```json curl theme={null} { "data": [ { "backup_id":"9947520e-d5a1-4418-a78d-9f464c9969da", "source_index_id":"8433941a-dae7-43b5-ac2c-d3dab4a56b2b", "source_index_name":"docs-example", "tags":{}, "name":"example-backup", "description":"Monthly backup of production index", "status":"Pending", "cloud":"aws", "region":"us-east-1", "dimension":1024, "record_count":98, "namespace_count":3, "size_bytes":1069169, "created_at":"2025-03-11T18:29:50.549505Z" } ], "pagination":null } ``` # List backups for all indexes in a project Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/list_project_backups https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /backups List all backups for a project. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl -X GET "https://api.pinecone.io/backups" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "accept: application/json" ``` ```json curl theme={null} { "data": [ { "backup_id": "e12269b0-a29b-4af0-9729-c7771dec03e3", "source_index_id": "bcb5b3c9-903e-4cb6-8b37-a6072aeb874f", "source_index_name": "docs-example", "tags": null, "name": "example-backup", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 0, "record_count": 96, "namespace_count": 1, "size_bytes": 86393, "created_at": "2025-05-14T17:00:45.803146Z" }, { "backup_id": "d686451d-1ede-4004-9f72-7d22cc799b6e", "source_index_id": "b49f27d1-1bf3-49c6-82b5-4ae46f00f0e6", "source_index_name": "docs-example2", "tags": null, "name": "example-backup2", "description": null, "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 50, "namespace_count": 1, "size_bytes": 545171, "created_at": "2025-05-14T17:00:34.814371Z" }, { "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "source_index_id": "f73b36c9-faf5-4a2c-b1d6-4013d8b1cc74", "source_index_name": "docs-example3", "tags": {}, "name": "example-backup3", "description": "Monthly backup of production index", "status": "Ready", "cloud": "aws", "region": "us-east-1", "dimension": 1024, "record_count": 98, "namespace_count": 3, "size_bytes": 1069169, "created_at": "2025-05-14T16:37:25.625540Z" } ], "pagination": null } ``` # List restore jobs Source: https://docs.pinecone.io/reference/api/2025-10/control-plane/list_restore_jobs https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_control_2025-10.oas.yaml get /restore-jobs List all restore jobs for a project. ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/restore-jobs" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" ``` ```json curl theme={null} { "data": [ { "restore_job_id": "9857add2-99d4-4399-870e-aa7f15d8d326", "backup_id": "94a63aeb-efae-4f7a-b059-75d32c27ca57", "target_index_name": "restored-index", "target_index_id": "0d8aed24-adf8-4b77-8e10-fd674309dc85", "status": "Completed", "created_at": "2025-04-25T18:14:05.227526Z", "completed_at": "2025-04-25T18:14:11.074618Z", "percent_complete": 100 }, { "restore_job_id": "69acc1d0-9105-4fcb-b1db-ebf97b285c5e", "backup_id": "8c85e612-ed1c-4f97-9f8c-8194e07bcf71", "target_index_name": "restored-index2", "target_index_id": "e6c0387f-33db-4227-9e91-32181106e56b", "status": "Completed", "created_at": "2025-05-14T17:25:59.378989Z", "completed_at": "2025-05-14T17:26:23.997284Z", "percent_complete": 100 } ], "pagination": null } ``` # Cancel an import Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/cancel_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml delete /bulk/imports/{id} Cancel an import operation if it is not yet finished. It has no effect if the operation is already finished. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X DELETE "https://$INDEX_HOST/bulk/imports/101" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} {} ``` # Describe an import Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/describe_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /bulk/imports/{id} Return details of a specific import operation. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports/101" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` ```json curl theme={null} { "id": "101", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "created_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ``` # List imports Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/list_imports https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml get /bulk/imports List all recent and ongoing import operations. By default, `list_imports` returns up to 100 imports per page. If the `limit` parameter is set, `list` returns up to that number of imports instead. Whenever there are additional IDs to return, the response also includes a `pagination_token` that you can use to get the next batch of imports. When the response does not include a `pagination_token`, there are no more imports to return. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X GET "https://$INDEX_HOST/bulk/imports?paginationToken==Tm90aGluZyB0byBzZWUgaGVyZQo" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'X-Pinecone-Api-Version: 2025-10' ``` ```json curl theme={null} { "data": [ { "id": "1", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "status": "Pending", "started_at": "2024-08-19T20:49:00.754Z", "finished_at": "2024-08-19T20:49:00.754Z", "percent_complete": 42.2, "records_imported": 1000000 } ], "pagination": { "next": "Tm90aGluZyB0byBzZWUgaGVyZQo=" } } ``` # Search with a vector Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/query https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /query Search a namespace using a query vector. It retrieves the ids of the most similar items in a namespace, along with their similarity scores. For guidance, examples, and limits, see [Search](https://docs.pinecone.io/guides/search/search-overview). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/query" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "namespace": "example-namespace", "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3], "filter": {"genre": {"$eq": "documentary"}}, "topK": 3, "includeValues": true }' ``` ```json curl theme={null} { "matches":[ { "id": "vec3", "score": 0, "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3] }, { "id": "vec2", "score": 0.0800000429, "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "vec4", "score": 0.0799999237, "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ], "namespace": "example-namespace", "usage": {"read_units": 6} } ``` # Search with text Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/search_records https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /records/namespaces/{namespace}/search Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query. Searching with text is supported only for indexes with [integrated embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding). Searching with a query vector or record ID is supported for all indexes. For guidance and examples, see [Search](https://docs.pinecone.io/guides/search/search-overview). ```shell curl theme={null} INDEX_HOST="INDEX_HOST" NAMESPACE="YOUR_NAMESPACE" PINECONE_API_KEY="YOUR_API_KEY" # Search with a query text and rerank the results # Supported only for indexes with integrated embedding curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "query": { "inputs": {"text": "Disease prevention"}, "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields' } }' # Search with a query vector and rerank the results curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "query": { "vector": { "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "query": "Disease prevention", "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] # Specified field must also be included in 'fields' } }' # Search with a record ID and rerank the results # Supported only for indexes with integrated embedding curl "https://$INDEX_HOST/records/namespaces/$NAMESPACE/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "query": { "id": "rec1", "top_k": 4, }, "fields": ["category", "chunk_text"] "rerank": { "query": "Disease prevention", "model": "bge-reranker-v2-m3", "top_n": 2, "rank_fields": ["chunk_text"] } }' ``` ```json curl theme={null} { "result": { "hits": [ { "_id": "rec3", "_score": 0.004433765076100826, "fields": { "category": "immune system", "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases." } }, { "_id": "rec4", "_score": 0.0029121784027665854, "fields": { "category": "endocrine system", "chunk_text": "The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes." } } ] }, "usage": { "embed_total_tokens": 8, "read_units": 6, "rerank_units": 1 } } ``` # Start import Source: https://docs.pinecone.io/reference/api/2025-10/data-plane/start_import https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/db_data_2025-10.oas.yaml post /bulk/imports Start an asynchronous import of vectors from object storage into an index. For guidance and examples, see [Import data](https://docs.pinecone.io/guides/index-data/import-data). This feature is in [public preview](/release-notes/feature-availability) and available only on [Standard and Enterprise plans](https://www.pinecone.io/pricing/). ```bash curl theme={null} # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl "https://$INDEX_HOST/bulk/imports" \ -H 'Api-Key: $PINECONE_API_KEY' \ -H 'Content-Type: application/json' \ -H 'X-Pinecone-Api-Version: 2025-10' \ -d '{ "integrationId": "a12b3d4c-47d2-492c-a97a-dd98c8dbefde", "uri": "s3://BUCKET_NAME/PATH/TO/DIR", "errorMode": { "onError": "continue" } }' ``` ```json curl theme={null} { "id": "101" } ``` # Describe a model Source: https://docs.pinecone.io/reference/api/2025-10/inference/describe_model https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/inference_2025-10.oas.yaml get /models/{model_name} Get a description of a model hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models/llama-text-embed-v2" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] } ``` # Generate vectors Source: https://docs.pinecone.io/reference/api/2025-10/inference/generate-embeddings https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/inference_2025-10.oas.yaml post /embed Generate vector embeddings for input data. This endpoint uses Pinecone's [hosted embedding models](https://docs.pinecone.io/guides/index-data/create-an-index#embedding-models). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/embed \ -H "Api-Key: $PINECONE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "model": "llama-text-embed-v2", "parameters": { "input_type": "passage", "truncate": "END" }, "inputs": [ {"text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"text": "The tech company Apple is known for its innovative products like the iPhone."}, {"text": "Many people enjoy eating apples as a healthy snack."}, {"text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"text": "An apple a day keeps the doctor away, as the saying goes."}, {"text": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership."} ] }' ``` ```json curl theme={null} { "data": [ { "values": [ 0.04925537109375, -0.01313018798828125, -0.0112762451171875, ... ] }, ... ], "model": "llama-text-embed-v2", "usage": { "total_tokens": 130 } } ``` # List available models Source: https://docs.pinecone.io/reference/api/2025-10/inference/list_models https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/inference_2025-10.oas.yaml get /models List the embedding and reranking models hosted by Pinecone. You can use hosted models as an integrated part of Pinecone operations or for standalone embedding and reranking. For more details, see [Vector embedding](https://docs.pinecone.io/guides/index-data/indexing-overview#vector-embedding) and [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```bash curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl "https://api.pinecone.io/models" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" ``` ```json curl theme={null} { "models": [ { "model": "llama-text-embed-v2", "short_description": "A high performance dense embedding model optimized for multilingual and cross-lingual text question-answering retrieval with support for long documents (up to 2048 tokens) and dynamic embedding size (Matryoshka Embeddings).", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 2048, "max_batch_size": 96, "provider_name": "NVIDIA", "supported_metrics": [ "Cosine", "DotProduct" ], "supported_dimensions": [ 384, 512, 768, 1024, 2048 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE", "START" ] }, { "parameter": "dimension", "required": false, "default": 1024, "type": "one_of", "value_type": "integer", "allowed_values": [ 384, 512, 768, 1024, 2048 ] } ] }, { "model": "multilingual-e5-large", "short_description": "A high-performance dense embedding model trained on a mixture of multilingual datasets. It works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "embed", "vector_type": "dense", "default_dimension": 1024, "modality": "text", "max_sequence_length": 507, "max_batch_size": 96, "provider_name": "Microsoft", "supported_metrics": [ "Cosine", "Euclidean" ], "supported_dimensions": [ 1024 ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "pinecone-sparse-english-v0", "short_description": "A sparse embedding model for converting text to sparse vectors for keyword or hybrid semantic/keyword search. Built on the innovations of the DeepImpact architecture.", "type": "embed", "vector_type": "sparse", "modality": "text", "max_sequence_length": 512, "max_batch_size": 96, "provider_name": "Pinecone", "supported_metrics": [ "DotProduct" ], "supported_parameters": [ { "parameter": "input_type", "required": true, "type": "one_of", "value_type": "string", "allowed_values": [ "query", "passage" ] }, { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] }, { "parameter": "return_tokens", "required": false, "default": false, "type": "any", "value_type": "boolean" } ] }, { "model": "bge-reranker-v2-m3", "short_description": "A high-performance, multilingual reranking model that works well on messy data and short queries expected to return medium-length passages of text (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 1024, "max_batch_size": 100, "provider_name": "BAAI", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "NONE", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] }, { "model": "cohere-rerank-3.5", "short_description": "Cohere's leading reranking model, balancing performance and latency for a wide range of enterprise search applications.", "type": "rerank", "modality": "text", "max_sequence_length": 40000, "max_batch_size": 200, "provider_name": "Cohere", "supported_parameters": [ { "parameter": "max_chunks_per_doc", "required": false, "default": 3072, "type": "numeric_range", "value_type": "integer", "min": 1, "max": 3072 } ] }, { "model": "pinecone-rerank-v0", "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)", "type": "rerank", "modality": "text", "max_sequence_length": 512, "max_batch_size": 100, "provider_name": "Pinecone", "supported_parameters": [ { "parameter": "truncate", "required": false, "default": "END", "type": "one_of", "value_type": "string", "allowed_values": [ "END", "NONE" ] } ] } ] } ``` # Rerank results Source: https://docs.pinecone.io/reference/api/2025-10/inference/rerank https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2025-10/inference_2025-10.oas.yaml post /rerank Rerank results according to their relevance to a query. For guidance and examples, see [Rerank results](https://docs.pinecone.io/guides/search/rerank-results). ```shell curl theme={null} PINECONE_API_KEY="YOUR_API_KEY" curl https://api.pinecone.io/rerank \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -H "Api-Key: $PINECONE_API_KEY" \ -d '{ "model": "bge-reranker-v2-m3", "query": "The tech company Apple is known for its innovative products like the iPhone.", "return_documents": true, "top_n": 4, "documents": [ {"id": "vec1", "text": "Apple is a popular fruit known for its sweetness and crisp texture."}, {"id": "vec2", "text": "Many people enjoy eating apples as a healthy snack."}, {"id": "vec3", "text": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces."}, {"id": "vec4", "text": "An apple a day keeps the doctor away, as the saying goes."} ], "parameters": { "truncate": "END" } }' ``` ```JSON curl theme={null} { "data":[ { "index":2, "document":{ "id":"vec3", "text":"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces." }, "score":0.47654688 }, { "index":0, "document":{ "id":"vec1", "text":"Apple is a popular fruit known for its sweetness and crisp texture." }, "score":0.047963805 }, { "index":3, "document":{ "id":"vec4", "text":"An apple a day keeps the doctor away, as the saying goes." }, "score":0.007587992 }, { "index":1, "document":{ "id":"vec2", "text":"Many people enjoy eating apples as a healthy snack." }, "score":0.0006491712 } ], "usage":{ "rerank_units":1 } } ``` # Authentication Source: https://docs.pinecone.io/reference/api/authentication All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits This page describes different types of limits for Pinecone Database. ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. | Metric | Starter plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :------------- | :------------- | :-------------- | | [Read units per month per project](#read-units-per-month-per-project) | 1,000,000 | Unlimited | Unlimited | | [Write units per month per project](#write-units-per-month-per-project) | 2,000,000 | Unlimited | Unlimited | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | Unlimited | Unlimited | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | 500 | Model-specific | Model-specific | ### Read units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for a project, fetch, query, and list requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for a project, upsert, update, and delete requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. ### Upsert size per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 20 | 100 | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 20 | 200 | | [Serverless index storage per project](#serverless-index-storage-per-project) | 2 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 100,000 | 100,000 | | [Serverless backups per project](#serveless-backups-per-project) | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | 1 On the Starter plan, all serverless must be in the `us-east-1` region of AWS.
### Projects per organization | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless indexes per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per project This limit applies to organizations on the Starter plan only. | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2 GB | N/A | N/A | When you've reached this quota for a project, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for project . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your project under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). While the Standard and Enterprise plans support up to [100,000 namespaces per index](/reference/api/database-limits#namespaces-per-serverless-index), Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | N/A | 500 | 1000 | When you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max metadata size per record | 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 | ### Import limits If your import exceeds these limits, you'll get an `Exceeds system limit` error. Pinecone can help unblock these imports quickly. [Contact Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance. | Metric | Limit | | :------------------------ | :------ | | Max namespaces per import | 10,000 | | Max size per namespace | 500 GB | | Max files per import | 100,000 | | Max size per file | 10 GB | ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. ### Fetch limits | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment. ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/connect-to-aws-privatelink) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, based on the version support diagram above, if it is currently October 2025 and you want to use the latest stable version to describe an index, you would set `"X-Pinecone-Api-Version: 2025-10"`: ```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: 2025-10" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication This feature is in [public preview](/release-notes/feature-availability). This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authenticating There are three ways to authenticate the Pinecone CLI: through a web browser with [user login](#user-login), using a [service account](#service-account), or with an [API key](#api-key). This table describes the Pinecone operations supported by each authentication method: | Method | Admin API | Control plane | | :-------------- | :-------- | :------------ | | User login | ✅ | ✅ | | Service account | ✅ | ✅ | | API key | ❌ | ✅ | * Admin API–related commands (organization and project management, API key operations): * `pc organization` (`list`, `describe`, `update`, `delete`) * `pc project` (`create`, `list`, `describe`, `update`, `delete`) * `pc api-key` (`create`, `list`, `describe`, `update`, `delete`) * Control plane–related commands (index management): * `pc index` (`create`, `list`, `describe`, `configure`, `delete`) Commands for data plane operations will be added in a future release. ### User login User login requires you to authenticate through a web browser. Subsequent CLI requests use a locally stored auth token that expires after 30 minutes but refreshes automatically. After 24 hours, you must re-authenticate. ```bash theme={null} # Authenticate in a web browser pc auth login ``` When you authenticate with `pc auth login`, the CLI automatically targets: * The default organization returned by the server for your user. * The first project in the list of that organization's projects. However, you can change organization and project as needed: ```bash theme={null} pc auth target -o "my-org" -p "my-project" ``` When you authenticate with user login, the CLI uses [managed API keys](#managed-keys) for control plane operations, unless you've set a default API key. To learn more about targeting organizations and projects, see [CLI target context](/reference/cli/target-context). To understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ### Service account To authenticate with a service account, provide a client ID and secret associated with a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure \ --client-id "YOUR_CLIENT_ID" \ --client-secret "YOUR_CLIENT_SECRET" # Or specify a project directly pc auth configure \ --client-id "YOUR_CLIENT_ID" \ --client-secret "YOUR_CLIENT_SECRET" \ --project-id "YOUR_PROJECT_ID" ``` Or set these environment variables: ```bash theme={null} export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` When you authentiate with a service account: * If your organization has only one project, the CLI automatically targets that project. * If your organization has multiple projects, the CLI prompts you to select a project (or you can use the `--project-id` flag, as shown above). * If your organization has no projects, create one. Then, set it as the target: ```bash theme={null} # Specify a project pc target -p "my-project" # Select a project interactively pc target ``` When you authenticate with a service account, the CLI uses [managed API keys](#managed-keys) for control plane operations, unless you've set a default API key. To learn more about targeting organizations and projects, see [CLI target context](/reference/cli/target-context). To understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ### API key You can also use an API to authenticate the CLI with Pinecone. This is useful for automation or CI/CD scenarios where you can't use interactive user login or a service account. Since each API key is associated with a specific project, the CLI uses that key's project for all operations. A default (manually specified) API key overrides any [target context](/reference/cli/target-context) you've set — you don't need to run `pc target`. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" ``` Or set this environment variable: ```bash theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` Because API keys are associated with a specific organization and project, they do not require [target context](/reference/cli/target-context). Also, to understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ## Auth priority The CLI chooses which authentication method to use based on the type of operation. ### Control plane operations (indexes) Control plane operations prioritize authentication credentials in the following order: 1. Default API key - Uses the project associated with the key. 2. User login token - Creates and uses [managed keys](#managed-keys). 3. Service account - Creates and uses [managed keys](#managed-keys). ### Admin API operations (organizations, projects, API keys) Admin API operations prioritize authentication credentials in the following order: 1. User login token 2. Service account Default API keys do not provide Admin API access. ### Environment variables vs. stored configuration Within each credential type, environment variables always override stored configuration: * `PINECONE_API_KEY` (env var) overrides default API key stored via `pc auth configure --api-key`. * `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` (env vars) override service account credentials stored via `pc auth configure`. * User login tokens have no environment variable equivalent. They're always stored locally. **Example scenarios:** * If `PINECONE_API_KEY` (env var) is set, the CLI uses it for control plane operations, regardless of any stored default API key value. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` set: * Control plane operations: User login token is used (creates managed keys). * Admin API operations: User login token is used. * The service account env vars are ignored. * If you have a default API key stored via `pc auth configure --api-key` and are also logged in through the web browser: * Control plane operations: Default API key is used. * Admin API operations: User login token is used. Environment variables are never persisted to local storage. They only override stored values at runtime. ### Default API keys and target context Default (manually specified) API keys override any [target context](/reference/cli/target-context). Control plane operations always use the project associated with the API key, regardless of what you've set with `pc target`. When you set a default API key (via `pc auth configure --api-key` or `PINECONE_API_KEY`): * The default API key is used for control plane operations. * [Managed keys](#managed-keys) are not created. * If you also have user login or service account credentials, those are still used for Admin API operations. Setting a default API key (via `pc auth configure --api-key` or `PINECONE_API_KEY`) does not clear user login tokens or service account credentials. ### User login and service accounts User login and service accounts are mutually exclusive when configured via CLI commands: * Running `pc auth login` clears any stored service account credentials. * Running `pc auth configure --client-id --client-secret` clears the stored auth token from `pc auth login`. However, if you set service account environment variables (`PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET`) without running `pc auth configure`, the CLI does not clear your stored user login token. User login and service accounts both use [managed keys](#managed-keys) for control plane operations (unless you've set a default API key). ## Clearing credentials (logging out) To clear your authentication credentials: ```bash theme={null} pc auth logout ``` This command clears local data: * 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](/reference/cli/target-context) `pc auth logout` does not delete managed API keys from Pinecone's servers. Those keys remain active and can be used to access your projects. To fully clean up, run `pc auth local-keys prune` before logging out. See [Deleting API keys](#deleting-api-keys) for details. ## Managed keys When authenticated with [user login](#user-login) or a [service account](#service-account), the CLI automatically creates and manages API keys for control plane operations. This happens transparently, the first time you run a control plane command like `pc index list`. You don't need to create or manage these keys yourself. ### When managed keys are created Managed keys are created only when you're authenticated via user login or service account, and there's no default (manually specified) API key set. After authenticating, the first time you run a control plane command like `pc index list`: 1. The CLI checks if a managed key already exists locally for the target project. 2. If not found, the CLI creates a new API key via the Admin API. 3. The key is stored both remotely (in Pinecone) and locally for future use. Subsequent commands targeting the same project reuse the stored key. If you set a default API key, managed keys are not created. The default API key is used instead. ### Where managed keys are stored Managed API keys are stored locally and remotely: * Local: Stored in `~/.config/pinecone/secrets.yaml` under the `project_api_keys` field as plain text, with file permissions set to 0600 (owner read/write only). For more details, see [Local data storage](#local-data-storage). * Remote: Stored in Pinecone as regular API keys, visible in the web console. The CLI will not display managed API keys after they're created. ### Identifying managed keys In the Pinecone web console, CLI-created keys have: * Name: `pinecone-cli-{6-character-alphanumeric}` (for example, `pinecone-cli-a3f9k2`) * Origin: `cli_created` To list all managed keys stored locally: ```bash theme={null} pc auth local-keys list ``` This shows managed keys tracked in your local `secrets.yaml` file, including which projects they belong to. ### Deleting API keys There are a few ways to use the CLI to delete API keys (managed or not), locally and remotely. **Delete locally tracked managed keys (local and remote)**: The `pc auth local-keys prune` command deletes managed keys that are tracked in your local `secrets.yaml` file. It does not affect API keys that were created outside the CLI or aren't tracked locally. ```bash theme={null} # Delete all locally tracked managed keys (CLI-created and user-created) 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 (local and remote)**: ```bash theme={null} pc api-key delete --id "YOUR_API_KEY_ID" ``` This deletes any API key (managed or not) and cleans up the local record if it exists. **Automatic deletion when creating a new key**: 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. This prevents accumulating multiple managed keys per project. `pc auth logout` deletes only the local references to managed keys. The keys remain active remotely in Pinecone. To fully clean up, run `pc auth local-keys prune` before logging out. ## Local data storage Authentication data is stored in `~/.config/pinecone/` with restricted permissions (0600): **`secrets.yaml`** - Sensitive data: * `oauth2_token`: Token associated with a user login (`pc auth login`) * `client_id`, `client_secret`: Service account credentials * `api_key`: Default (manually specified) API key * `project_api_keys`: Managed keys per project **`state.yaml`** - Context: * `target_org`: Current organization (name and ID) * `target_project`: Current project (name and ID) **`config.yaml`** - Settings: * `color`: Enable/disable colored output * `environment`: Production or staging ## Check authentication status ```bash theme={null} pc auth status ``` Shows: * Current authentication method * Target organization and project * Token expiration (for user login) * Environment configuration # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference This feature is in [public preview](/release-notes/feature-availability). This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | | 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 | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | | 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 | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | | 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 | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | | 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 | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens expire after 30 minutes, but they refresh automatically for up to 24 hours. After that point, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :------------------------------------------------------------- | | `--deletion_protection` | `-p` | Enable or disable deletion protection -`enabled` or `disabled` | | `--json` | | Output in JSON format | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Enable deletion protection pc index configure -n my-index -p enabled # Verify changes pc index describe -n my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new serverless index in your Pinecone project, with various configuration optons. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :------------------------------------------------------------------------ | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` (required for serverless) | | `--deletion_protection` | | Deletion protection - `enabled` or `disabled` | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--field_map` | | Field mapping for integrated embedding (JSON map) | | `--json` | | Output in JSON format | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (required) | | `--model` | | Integrated embedding model name | | `--name` | `-n` | Index name (required) | | `--read_parameters` | | Read parameters for embedding model (JSON map) | | `--region` | `-r` | Cloud region | | `--source_collection` | | Name of the source collection from which to create the index | | `--tags` | | Custom user tags (key=value pairs) | | `--vector_type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--write_parameters` | | Write parameters for embedding model (JSON map) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large # 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 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Delete an index pc index delete -n my-index # List before and after pc index list pc index delete -n test-index pc index list ``` **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 | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an index pc index describe -n my-index # JSON output pc index describe -n my-index --json # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -n test-index ``` **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` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all indexes pc index list # JSON output for scripting pc index list --json # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | | 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 | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | 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 | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | 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 | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Displays the currently configured default (manually specified) API key, if set. By default, the full value of the key is not displayed. **Usage** ```bash theme={null} pc config get-api-key ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------- | | `--reveal` | | Show the actual API key value (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Get current API key pc config get-api-key # Verify after setting pc config set-api-key pcsk_abc123 pc config get-api-key ``` **Description** Sets a default API key for the CLI to use for authentication. Provides direct access to control plane operations, but not Admin API operations. **Usage** ```bash theme={null} pc config set-api-key "YOUR_API_KEY" ``` **Flags** None (takes API key as argument) **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Set default API key pc config set-api-key pcsk_abc123 # Use immediately without targeting pc config set-api-key pcsk_abc123 pc index list # Verify it's set pc auth status ``` `pc config set-api-key "YOUR_API_KEY"` does the same thing as `pc auth configure --api-key "YOUR_API_KEY"`. For control plane operations, a default API key implicitly overrides any previously set [target context](/reference/cli/target-context), because Pinecone API keys are scoped to a specific organization and project. **Description** Enables or disables colored output in CLI responses. Useful for terminal compatibility or log file generation. **Usage** ```bash theme={null} pc config set-color true pc config set-color false ``` **Flags** None (takes boolean as argument) **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Enable colored output pc config set-color true # Disable colored output for CI/CD pc config set-color false # Test the change pc config set-color false pc index list ``` # CLI installation Source: https://docs.pinecone.io/reference/cli/installation This feature is in [public preview](/release-notes/feature-availability). This document describes how to install the Pinecone CLI on your local machine. ## Platforms Pinecone's CLI is available for the following platforms: * **macOS**: Intel (x86\_64) and Apple Silicon (ARM64) * **Linux**: x86\_64, ARM64, and i386 architectures * **Windows**: x86\_64 and i386 architectures ## Installation ### Homebrew (macOS) The most convenient way to install the CLI on Mac: ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` To upgrade to the latest version: ```bash theme={null} brew update brew upgrade pinecone ``` ### Direct download (all platforms) Pre-built binaries for all supported platforms are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). ### Build from source To build from source, see the [CONTRIBUTING.md](https://github.com/pinecone-io/cli/blob/main/CONTRIBUTING.md) file for detailed instructions. To build from source, you need Go v1.23+. # CLI overview Source: https://docs.pinecone.io/reference/cli/overview This feature is in [public preview](/release-notes/feature-availability). The Pinecone CLI (`pc`) is a command-line tool for managing Pinecone infrastructure (projects, organizations, indexes, and API keys) directly from your terminal. Use it to: * Automate infrastructure operations * Integrate Pinecone into CI/CD pipelines * Manage resources without using the web console ## Supported The CLI currently supports the following features: * Authentication (user login, service account, API key) * Projects and organizations (create, update, delete, list) * Indexes (create, configure, delete, list) * API key management ## Not yet supported The CLI does not yet support the following features: * Vector and namespace operations * Bulk data imports * Index statistics * Inference (embeddings, reranking) * Assistant operations * Dedicated read nodes For these features, use Pinecone's [REST API](/reference/api) or SDKs: [Python](/reference/python-sdk), [Node.js](/reference/node-sdk), [Java](/reference/java-sdk), [Go](/reference/go-sdk), [.NET](/reference/dotnet-sdk), or [Rust](/reference/rust-sdk) (alpha). # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart This feature is in [public preview](/release-notes/feature-availability). 1. Install the Pinecone CLI: ```shell macOS theme={null} # Using Homebrew (https://brew.sh) brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` ```shell Linux/Windows theme={null} Download pre-build binaries from https://github.com/pinecone-io/cli/releases ``` 2. Authenticate the CLI with Pinecone by [user login](/reference/cli/authentication#user-login): ```bash theme={null} # Authenticate in a web browser pc auth login ``` To authenticate with Pinecone, visit the URL displayed in the terminal. After you sign in, the terminal displays a success message: ``` [SUCCESS] Logged in as user@example.com. Defaulted to organization ID: [INFO] Target org set to [INFO] Target project set to ``` As shown by the `[INFO]` messages, this command automatically sets a [target organization and project](/reference/cli/target-context) for the CLI. 3. If necessary, target a different organization and/or project: ```bash theme={null} pc auth target -o "my-org-name" -p "my-project-name" ``` 4. List the indexes in the project: ```bash theme={null} pc index list ``` ## Next steps See the [command reference](/reference/cli/command-reference) to learn about the various commands offered by the CLI. # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context This feature is in [public preview](/release-notes/feature-availability). Most CLI operations happen within the context of a specific organization and project. The **target context** is the organization and project scope that the CLI uses when running commands. Before setting target context, you must authenticate with the CLI. See [CLI authentication](/reference/cli/authentication) for details on authentication methods. ## Why target context matters By specifying a target organization and/or project, you're telling the CLI which resources to operate on. * **Control plane operations** (creating indexes, listing indexes): Always happen within a specific project. * **Admin API operations**: * Organization operations don't require target context. They operate on organizations you have access to. * Project management operations are scoped to your target organization. For example, running `pc project list` shows projects in the target org. * API key operations are scoped to the target project, unless you specify `--id`. ## How target context works How the CLI sets and uses target context depends on your authentication method and how you configure it. ### User login When you authenticate with `pc auth login`, the CLI automatically [targets](/reference/cli/target-context): * The default organization returned by the server for your user. * The first project in the list of that organization's projects. However, you can change organization and project as needed: ```bash theme={null} pc auth login pc target -o "my-org" -p "my-project" ``` ### Service account **Configured via CLI command** When you configure a service account with `pc auth configure --client-id --client-secret`, the CLI automatically targets the organization associated with the service account (service accounts belong to a single organization). Then, to target a project: * If the selected organization has only one project, the CLI automatically targets it. * If that organization has multiple projects, the CLI prompts you to select one (or you can use the `--project-id` flag). * If it doesn't have any projects, create one and then target it manually. To change to a specific target project: ```bash theme={null} pc target -p "different-project" ``` Or, to select a project interactively: ```bash theme={null} pc target ``` **Configured via environment variables** If you set service account credentials via environment variables (`PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET`) without running `pc auth configure`, the CLI does **not** automatically set any target context. You must explicitly set it with `pc target`. Service accounts are scoped to a single organization. You can only target the organization associated with your service account credentials. To do this, and also target a specific project within that organization: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` Or, to select a project interactively (the CLI discovers the organization automatically): ```bash theme={null} pc target ``` ### API key When you set a default API key (with `pc auth configure --api-key` or the `PINECONE_API_KEY` environment variable), the CLI does **not** change or clear its stored target context. However, in this scenario, control plane operations **do** use the API key's organization and project — not the CLI's saved target context (regardless of any calls you've made to `pc target`, or the output of `pc target --show`). This happens because Pinecone API keys are always scoped to a specific organization and project, and they cannot access resources outside of that scope. Because Pinecone API keys cannot be used to authenticate calls to the Admin API, Admin API operations still authentiate with your user login token or service account credentials (if available). ```bash theme={null} pc auth login pc target -o "my-org" -p "my-project" # Setting an API key doesn't change stored target context pc auth configure --api-key "YOUR_API_KEY" pc target --show # Still shows my-org and my-project, but they're not used for control plane operations ``` ## Viewing and managing target context To view your current target organization and project: ```bash theme={null} # Show current target context pc target --show # Clear target context pc target --clear ``` # .NET SDK Source: https://docs.pinecone.io/reference/dotnet-sdk See the [.NET SDK documentation](https://github.com/pinecone-io/pinecone-dotnet-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-dotnet-client/issues). ## Requirements To use this Python .NET SDK, ensure that your project is targeting one of the following: * .NET Standard 2.0+ * .NET Core 3.0+ * .NET Framework 4.6.2+ * .NET 6.0+ ## 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 .NET SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `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 add the latest version of the [.NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client) to your project, run the following command: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client ``` To add a specific version of the [.NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client) to your project, run the following command: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client --version ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client -Version ``` To check your SDK version, run the following command: ```shell .NET Core CLI theme={null} dotnet list package ``` ```shell NuGet CLI theme={null} nuget list ``` ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-05-14-2). If you are already using `Pinecone.Client` in your project, upgrade to the latest version as follows: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, configure the HTTP client as follows: ```csharp theme={null} using System.Net; using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY", new ClientOptions { HttpClient = new HttpClient(new HttpClientHandler { Proxy = new WebProxy("PROXY_HOST:PROXY_PORT") }) }); ``` If you're building your HTTP client using the [HTTP client factory](https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory#configure-the-httpmessagehandler), use the `ConfigurePrimaryHttpMessageHandler` method to configure the proxy: ```csharp theme={null} .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler { Proxy = new WebProxy("PROXY_HOST:PROXY_PORT") }); ``` # Go SDK Source: https://docs.pinecone.io/reference/go-sdk See the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](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 | | :---------- | :---------- | | `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/v4/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/v4/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). 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/v4/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/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) } } ``` # Java SDK Source: https://docs.pinecone.io/reference/java-sdk See the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` # Node.js SDK Source: https://docs.pinecone.io/reference/node-sdk See the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/) for full installation instructions, usage examples, and reference information. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Introduction Source: https://docs.pinecone.io/reference/pinecone-sdks ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | ----------------------------------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/python-sdk) | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/node-sdk) | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/java-sdk) | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/go-sdk) | v4.x | v3.x | v2.x | v1.x | v0.x | | [.NET SDK](/reference/dotnet-sdk) | 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. SDKs that target API version `2025-10` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Python SDK Source: https://docs.pinecone.io/reference/python-sdk The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Asyncio support](#async-requests). See the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/) for full installation instructions, usage examples, and reference information. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-python-client/issues). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 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 import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/python-sdk), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Rust SDK Source: https://docs.pinecone.io/reference/rust-sdk The Rust SDK is in "alpha" and is under active development. The SDK should be considered unstable and should not be used in production. Before a 1.0 release, there are no guarantees of backward compatibility between minor versions. See the [Rust SDK README](https://github.com/pinecone-io/pinecone-rust-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-rust-client/issues). ## Install To install the latest version of the [Rust SDK](https://github.com/pinecone-io/pinecone-rust-client), add a dependency to the current project: ```shell theme={null} cargo add pinecone-sdk ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```rust Rust theme={null} use pinecone_sdk::pinecone::PineconeClientConfig; use pinecone_sdk::utils::errors::PineconeError; #[tokio::main] async fn main() -> Result<(), PineconeError> { let config = PineconeClientConfig { api_key: Some("YOUR_API_KEY".to_string()), ..Default::default() }; let pinecone = config.client()?; let indexes = pinecone.list_indexes().await?; println!("Indexes: {:?}", indexes); Ok(()) } ``` # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Authentication Source: https://docs.pinecone.io/reference/api/authentication All requests to [Pinecone APIs](/reference/api/introduction) must contain a valid [API key](/guides/production/security-overview#api-keys) for the target project. ## Get an API key [Create a new API key](https://app.pinecone.io/organizations/-/projects/-/keys) in the Pinecone console, or use the connect widget below to generate a key.
Copy your generated key: ``` PINECONE_API_KEY="{{YOUR_API_KEY}}" # This API key has ReadWrite access to all indexes in your project. ``` ## Initialize a client When using a [Pinecone SDK](/reference/pinecone-sdks), initialize a client object with your API key and then reuse the authenicated client in subsquent function calls. For example: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key='YOUR_API_KEY') # Creates an index using the API key stored in the client 'pc'. pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud='aws', region='us-east-1' ) ) ``` ```JavaScript JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); // Creates an index using the API key stored in the client 'pc'. await pc.createIndex({ name: 'docs-example', dimension: 1536, metric: 'cosine', spec: { serverless: { cloud: 'aws', region: 'us-east-1' } } }) ``` ```java Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.IndexModel; import org.openapitools.db_control.client.model.DeletionProtection; public class CreateServerlessIndexExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); // Creates an index using the API key stored in the client 'pc'. pc.createServerlessIndex("docs-example", "cosine", 1536, "aws", "us-east-1"); } } ``` ```go Go theme={null} package main import ( "context" "fmt" "log" "github.com/pinecone-io/go-pinecone/v3/pinecone" ) func main() { ctx := context.Background() pc, err := pinecone.NewClient(pinecone.NewClientParams{ ApiKey: "YOUR_API_KEY", }) if err != nil { log.Fatalf("Failed to create Client: %v", err) } indexName := "docs-example" vectorType := "dense" dimension := int32(1536) metric := pinecone.Cosine deletionProtection := pinecone.DeletionProtectionDisabled idx, err := pc.CreateServerlessIndex(ctx, &pinecone.CreateServerlessIndexRequest{ Name: indexName, VectorType: &vectorType, Dimension: &dimension, Metric: &metric, Cloud: pinecone.Aws, Region: "us-east-1", DeletionProtection: &deletionProtection, }) if err != nil { log.Fatalf("Failed to create serverless index: %v", err) } else { fmt.Printf("Successfully created serverless index: %v", idx.Name) } } ``` ```shell curl theme={null} curl -s "https://api.pinecone.io/indexes" \ -H "Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Add headers to an HTTP request All HTTP requests to Pinecone APIs must contain an `Api-Key` header that specifies a valid [API key](/guides/production/security-overview#api-keys) and must be encoded as JSON with the `Content-Type: application/json` header. For example: ```shell curl theme={null} curl https://api.pinecone.io/indexes \ -H "Content-Type: application/json" \ -H "Api-Key: $PINECONE_API_KEY" \ -H "X-Pinecone-Api-Version: 2025-10" \ -d '{ "name": "docs-example", "dimension": 1536, "metric": "cosine", "spec": { "serverless": { "cloud":"aws", "region": "us-east-1" } } }' ``` ## Troubleshooting Older versions of Pinecone required you to initialize a client with an `init` method that takes both `api_key` and `environment` parameters, for example: ```python Python theme={null} # Legacy initialization import pinecone pc = pinecone.init( api_key="PINECONE_API_KEY", environment="PINECONE_ENVIRONMENT" ) ``` ```javascript JavaScript theme={null} // Legacy initialization import { Pinecone } from '@pinecone-database/pinecone'; const pineconeClient = new PineconeClient(); await pineconeClient.init({ apiKey: 'PINECONE_API_KEY', environment: 'PINECONE_ENVIRONMENT', }); ``` In more recent versions of Pinecone, this has changed. Initialization no longer requires an `init` step, and cloud environment is defined for each index rather than an entire project. Client initialization now only requires an `api_key` parameter, for example: ```python Python theme={null} # New initialization from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```javascript JavaScript theme={null} // New initialization import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` If you are receiving errors about initialization, upgrade your [Pinecone SDK](/reference/pinecone-sdks) to the latest version, for example: ```shell Python theme={null} # Upgrade Pinecone SDK pip install pinecone --upgrade ``` ```shell JavaScript theme={null} # Upgrade Pinecone SDK npm install @pinecone-database/pinecone@latest ``` Also, note that some third-party tutorials and examples still reference the older initialization method. In such cases, follow the example above and the examples throughout the Pinecone documentation instead. # Pinecone Database limits Source: https://docs.pinecone.io/reference/api/database-limits This page describes different types of limits for Pinecone Database. ## Rate limits Rate limits help protect your applications from misuse and maintain the health of our shared serverless infrastructure. These limits are designed to support typical production workloads while ensuring reliable performance for all users. **Most rate limits can be adjusted upon request.** If you need higher limits to scale your application, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket) with details about your use case. Pinecone is committed to supporting your growth and can often accommodate higher throughput requirements. Rate limits vary based on [pricing plan](https://www.pinecone.io/pricing/) and apply to [serverless indexes](/guides/index-data/indexing-overview) only. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. | Metric | Starter plan | Standard plan | Enterprise plan | | :------------------------------------------------------------------------------------------------------------ | :------------- | :------------- | :-------------- | | [Read units per month per project](#read-units-per-month-per-project) | 1,000,000 | Unlimited | Unlimited | | [Write units per month per project](#write-units-per-month-per-project) | 2,000,000 | Unlimited | Unlimited | | [Upsert size per second per namespace](#upsert-size-per-second-per-namespace) | 50 MB | 50 MB | 50 MB | | [Query read units per second per index](#query-read-units-per-second-per-index) | 2,000 | 2,000 | 2,000 | | [Update records per second per namespace](#update-records-per-second-per-namespace) | 100 | 100 | 100 | | [Update by metadata requests per second per namespace](#update-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Update by metadata requests per second per index](#update-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Fetch requests per second per index](#fetch-requests-per-second-per-index) | 100 | 100 | 100 | | [List requests per second per index](#list-requests-per-second-per-index) | 200 | 200 | 200 | | [Describe index stats requests per second per index](#describe-index-stats-requests-per-second-per-index) | 100 | 100 | 100 | | [Delete records per second per namespace](#delete-records-per-second-per-namespace) | 5,000 | 5,000 | 5,000 | | [Delete records per second per index](#delete-records-per-second-per-index) | 5,000 | 5,000 | 5,000 | | [Delete by metadata requests per second per namespace](#delete-by-metadata-requests-per-second-per-namespace) | 5 | 5 | 5 | | [Delete by metadata requests per second per index](#delete-by-metadata-requests-per-second-per-index) | 500 | 500 | 500 | | [Embedding tokens per minute per model](#embedding-tokens-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Embedding tokens per month per model](#embedding-tokens-per-month-per-model) | 5,000,000 | Unlimited | Unlimited | | [Rerank requests per minute per model](#rerank-requests-per-minute-per-model) | Model-specific | Model-specific | Model-specific | | [Rerank requests per month per model](#rerank-requests-per-month-per-model) | 500 | Model-specific | Model-specific | ### Read units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1,000,000 | Unlimited | Unlimited | [Read units](/guides/manage-cost/understanding-cost#read-units) measure the compute, I/O, and network resources used by [fetch](/guides/manage-data/fetch-data), [query](/guides/search/search-overview), and [list](/guides/manage-data/list-record-ids) requests to serverless indexes. When you reach the monthly read unit limit for a project, fetch, query, and list requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your read unit limit for the current month limit. To continue reading data, upgrade your plan. ``` To continue reading from serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Write units per month per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000,000 | Unlimited | Unlimited | [Write units](/guides/manage-cost/understanding-cost#write-units) measure the storage and compute resources used by [upsert](/guides/index-data/upsert-data), [update](/guides/manage-data/update-data), and [delete](/guides/manage-data/delete-data) requests to serverless indexes. When you reach the monthly write unit limit for a project, upsert, update, and delete requests to serverless indexes in the project will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached your write unit limit for the current month. To continue writing data, upgrade your plan. ``` To continue writing data to serverless indexes in the project, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). To check how close you are to the monthly read unit limit for a project, do the following: 1. Open the [Pinecone console](https://app.pinecone.io/organizations/-/projects). 2. Select the project. 3. Select any index in the project. 4. Look under **Starter Usage**. ### Upsert size per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 50 MB | 50 MB | 50 MB | When you reach the per second [upsert](/guides/index-data/upsert-data) size for a namespace in an index, additional upserts will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max upsert size limit per second for index . Pace your upserts or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Query read units per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2,000 | 2,000 | 2,000 | Pinecone measures [query](/guides/search/search-overview) usage in [read units](/guides/manage-cost/understanding-cost#read-units). When you reach the per second limit for queries across all namespaces in an index, additional queries will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max query read units per second for index . Pace your queries or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). To check how many read units a query consumes, [check the query response](/guides/manage-cost/monitor-usage-and-costs#read-units). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Update records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [update](/guides/manage-data/update-data) limit for a namespace in an index, additional updates will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update records per second for namespace . Pace your update requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit for a namespace in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for namespace . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Update by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [update by metadata](/guides/manage-data/update-data#update-metadata-across-multiple-records) request limit across all namespaces in an index, additional update by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max update by metadata requests per second for index . Pace your update by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Fetch requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [fetch](/guides/manage-data/fetch-data) limit across all namespaces in an index, additional fetch requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max fetch requests per second for index . Pace your fetch requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### List requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 200 | 200 | 200 | When you reach the per second [list](/guides/manage-data/list-record-ids) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max list requests per second for index . Pace your list requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). Indexes built on [dedicated read nodes](/guides/index-data/dedicated-read-nodes) are not subject to read unit limits for query, fetch, and list operations. For sizing and capacity planning guidance, see the [Dedicated Read Nodes](/guides/index-data/dedicated-read-nodes) guide. ### Describe index stats requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100 | 100 | When you reach the per second [describe index stats](/reference/api/2024-10/data-plane/describeindexstats) limit across all namespaces in an index, additional list requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max describe_index_stats requests per second for index . Pace your describe_index_stats requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit for a namespace in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for namespace . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete records per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5000 | 5000 | 5000 | When you reach the per second [delete](/guides/manage-data/delete-data) limit across all namespaces in an index, additional deletes will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete records per second for index . Pace your delete requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per namespace | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 5 | 5 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit for a namespace in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for namespace . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Delete by metadata requests per second per index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 500 | 500 | 500 | When you reach the per second [delete by metadata](/guides/manage-data/delete-data#delete-records-by-metadata) request limit across all namespaces in an index, additional delete by metadata requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max delete by metadata requests per second for index . Pace your delete by metadata requests or contact Pinecone Support (https://app.pinecone.io/organizations/-/settings/support/ticket) to request a higher limit. ``` To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). If you need a higher limit for your use case, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Embedding tokens per minute per model | Embedding model | Input type | Starter plan | Standard plan | Enterprise plan | | :--------------------------- | :--------- | :----------- | :------------ | :-------------- | | `llama-text-embed-v2` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `multilingual-e5-large` | Passage | 250,000 | 1,000,000 | 1,000,000 | | | Query | 50,000 | 250,000 | 250,000 | | `pinecone-sparse-english-v0` | Passage | 250,000 | 3,000,000 | 3,000,000 | | | Query | 250,000 | 3,000,000 | 3,000,000 | When you reach the per minute token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max embedding tokens per minute () model ''' and input type '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). Otherwise, you can handle this limit by [implementing retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ### Embedding tokens per month per model | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5,000,000 | Unlimited | Unlimited | When you reach the monthly token limit for an [embedding model](/guides/index-data/create-an-index#embedding-models) hosted by Pinecone, additional embeddings will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the embedding token limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Rerank requests per minute per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | 300 | 300 | | `bge-reranker-v2-m3` | 60 | 60 | 60 | | `pinecone-rerank-v0` | 60 | 60 | 60 | When you reach the per minute request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max rerank requests per minute () for model '' for the current project. To increase this limit, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Rerank requests per month per model | Reranking model | Starter plan | Standard plan | Enterprise plan | | :------------------- | :------------ | :------------ | :-------------- | | `cohere-rerank-3.5` | Not available | Unlimited | Unlimited | | `bge-reranker-v2-m3` | 500 | Unlimited | Unlimited | | `pinecone-rerank-v0` | 500 | Unlimited | Unlimited | When you reach the monthly request limit for a [reranking model](/guides/search/rerank-results#reranking-models) hosted by Pinecone, additional reranking requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the rerank request limit () for model for the current month. To continue using this model, upgrade your plan. ``` To increase this limit, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Inference requests per second or minute, per project | Metric | Starter plan | Standard plan | Enterprise plan | | :---------------------------- | :----------- | :------------ | :-------------- | | Inference requests per second | 100 | 100 | 100 | | Inference requests per minute | 2000 | 2000 | 2000 | When you reach the per second or per minute request limit, inference requests will fail and return a `429 - TOO_MANY_REQUESTS` status with the following error: ``` Request failed. You've reached the max inference requests per second () for the current project. ``` This error indicates per second or per minute, as applicable. To handle this limit, [implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic). ## Object limits Object limits are restrictions on the number or size of objects in Pinecone. Object limits vary based on [pricing plan](https://www.pinecone.io/pricing/). | Metric | Starter plan | Standard plan | Enterprise plan | | :----------------------------------------------------------------------------- | :----------- | :------------ | :-------------- | | [Projects per organization](#projects-per-organization) | 1 | 20 | 100 | | [Serverless indexes per project](#serverless-indexes-per-project) 1 | 5 | 20 | 200 | | [Serverless index storage per project](#serverless-index-storage-per-project) | 2 GB | N/A | N/A | | [Namespaces per serverless index](#namespaces-per-serverless-index) | 100 | 100,000 | 100,000 | | [Serverless backups per project](#serveless-backups-per-project) | N/A | 500 | 1000 | | [Collections per project](#collections-per-project) | 100 | N/A | N/A | 1 On the Starter plan, all serverless must be in the `us-east-1` region of AWS.
### Projects per organization | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 1 | 20 | 100 | When you reach this quota for an organization, trying to [create projects](/guides/projects/create-a-project) will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max projects allowed in organization . To add more projects, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan) or [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless indexes per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 5 | 20 | 200 | When you reach this quota for a project, trying to [create serverless indexes](/guides/index-data/create-an-index#create-a-serverless-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max serverless indexes allowed in project . Use namespaces to partition your data into logical groups, or upgrade your plan to add more serverless indexes. ``` To stay under this quota, consider using [namespaces](/guides/index-data/create-an-index#namespaces) instead of creating multiple indexes. Namespaces let you partition your data into logical groups within a single index. This approach not only helps you stay within index limits, but can also improve query performance and lower costs by limiting searches to relevant data subsets. To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Serverless index storage per project This limit applies to organizations on the Starter plan only. | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 2 GB | N/A | N/A | When you've reached this quota for a project, updates and upserts into serverless indexes will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max storage allowed for project . To update or upsert new data, delete records or upgrade your plan. ``` To continue writing data into your serverless indexes, [delete records](/guides/manage-data/delete-data) to bring your project under the limit or [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ### Namespaces per serverless index | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | 100,000 | 100,000 | When you reach this quota for a serverless index, trying to [upsert records into a new namespace](/guides/index-data/upsert-data) in the index will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max namespaces allowed in serverless index . To add more namespaces, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). While the Standard and Enterprise plans support up to [100,000 namespaces per index](/reference/api/database-limits#namespaces-per-serverless-index), Pinecone can accommodate million-scale namespaces and beyond for specific use cases. If your application requires more than 100,000 namespaces, [contact Support](https://app.pinecone.io/organizations/-/settings/support/ticket). ### Serverless backups per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | N/A | 500 | 1000 | When you reach this quota for a project, trying to [create serverless backups](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Backup failed to create. Quota for number of backups per index exceeded. ``` ### Collections per project | Starter plan | Standard plan | Enterprise plan | | ------------ | ------------- | --------------- | | 100 | N/A | N/A | When you reach this quota for a project, trying to [create collections](/guides/manage-data/back-up-an-index) in the project will fail and return a `403 - QUOTA_EXCEEDED` status with the following error: ``` Request failed. You've reached the max collections allowed in project . To add more collections, upgrade your plan. ``` To increase this quota, [upgrade your plan](/guides/organizations/manage-billing/upgrade-billing-plan). ## Operation limits Operation limits are restrictions on the size, number, or other characteristics of operations in Pinecone. Operation limits are fixed and do not vary based on pricing plan. ### Upsert limits | Metric | Limit | | :----------------------------------------------------------------- | :------------------------------------------------------------ | | Max [batch size](/guides/index-data/upsert-data#upsert-in-batches) | 2 MB or 1000 records with vectors
96 records with text | | Max metadata size per record | 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 | ### Import limits If your import exceeds these limits, you'll get an `Exceeds system limit` error. Pinecone can help unblock these imports quickly. [Contact Pinecone support](https://app.pinecone.io/organizations/-/settings/support/ticket) for assistance. | Metric | Limit | | :------------------------ | :------ | | Max namespaces per import | 10,000 | | Max size per namespace | 500 GB | | Max files per import | 100,000 | | Max size per file | 10 GB | ### Query limits | Metric | Limit | | :---------------- | :----- | | Max `top_k` value | 10,000 | | Max result size | 4MB | The query result size is affected by the dimension of the dense vectors and whether or not dense vector values and metadata are included in the result. If a query fails due to exceeding the 4MB result size limit, choose a lower `top_k` value, or use `include_metadata=False` or `include_values=False` to exclude metadata or values from the result. ### Fetch limits | Metric | Limit | | :------------------------------- | :---- | | Max record IDs per fetch request | 1,000 | ### Delete limits | Metric | Limit | | :-------------------------------- | :---- | | Max record IDs per delete request | 1,000 | ## Identifier limits An identifier is a string of characters used to identify "named" [objects in Pinecone](/guides/get-started/concepts). The following Pinecone objects use strings as identifiers: | Object | Field | Max # characters | Allowed characters | | --------------------------------------------------------- | ----------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Organization](/guides/get-started/concepts#organization) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Project](/guides/get-started/concepts#project) | `name` | 512 |
  • UTF-8 except `\0`
  • Cannot be empty
| | [Index](/guides/get-started/concepts#index) | `name` | 45 |
  • `a-z`, `0-9`, and `-`
  • Must be lowercase
  • Cannot start or end with `-`
  • Cannot be empty
| | [Namespace](/guides/get-started/concepts#namespace) | `namespace` | 512 |
  • ASCII except `\0`
  • For the default namespace, use `""` (or `"__default__"`, in API versions `2025-04` and later)
| | [Record](/guides/get-started/concepts#record) | `id` | 512 |
  • ASCII except `\0`
  • Cannot be empty
| # Errors Source: https://docs.pinecone.io/reference/api/errors Pinecone uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided, and codes in the `5xx` range indicate an error with Pinecone's servers. For guidance on handling errors in production, see [Error handling](/guides/production/error-handling). ## 200 - OK The request succeeded. ## 201 - CREATED The request succeeded and a new resource was created. ## 202 - NO CONTENT The request succeeded, but there is no content to return. ## 400 - INVALID ARGUMENT The request failed due to an invalid argument. ## 401 - UNAUTHENTICATED The request failed due to a missing or invalid [API key](/guides/projects/understanding-projects#api-keys). ## 402 - PAYMENT REQUIRED The request failed due to delinquent payment. ## 403 - FORBIDDEN The request failed due to an exceeded [quota](/reference/api/database-limits#object-limits) or [index deletion protection](/guides/manage-data/manage-indexes#configure-deletion-protection). ## 404 - NOT FOUND The request failed because the resource was not found. ## 409 - ALREADY EXISTS The request failed because the resource already exists. ## 412 - FAILED PRECONDITIONS The request failed due to preconditions not being met. | ## 422 - UNPROCESSABLE ENTITY The request failed because the server was unable to process the contained instructions. ## 429 - TOO MANY REQUESTS The request was [rate-limited](/reference/api/database-limits#rate-limits). [Implement retry logic with exponential backoff](/guides/production/error-handling#handle-rate-limits-429) to handle this error. ## 500 - UNKNOWN An internal server error occurred. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 502 - BAD GATEWAY The API gateway received an invalid response from a backend service. This is typically a temporary error. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 503 - UNAVAILABLE The server is currently unavailable. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. ## 504 - GATEWAY TIMEOUT The API gateway did not receive a timely response from the backend server. This can occur due to slow requests or backend processing delays. [Implement retry logic with exponential backoff](/guides/production/error-handling#implement-retry-logic) to handle transient errors. # API reference Source: https://docs.pinecone.io/reference/api/introduction Pinecone's APIs let you interact programmatically with your Pinecone account. [SDK versions](/reference/pinecone-sdks#sdk-versions) are pinned to specific API versions. ## Database Use the Database API to store and query records in [Pinecone Database](/guides/get-started/quickstart). The following Pinecone SDKs support the Database API: ## Inference Use the Inference API to generate vector embeddings and rerank results using [embedding models](/guides/index-data/create-an-index#embedding-models) and [reranking models](/guides/search/rerank-results#reranking-models) hosted on Pinecone's infrastructure. There are two ways to use the Inference API: * As a standalone service, through the [Rerank documents](/reference/api/latest/inference/rerank) and [Generate vectors](/reference/api/latest/inference/generate-embeddings) endpoints. * As an integrated part of database operations, through the [Create an index with integrated embedding](/reference/api/latest/control-plane/create_for_model), [Upsert text](/reference/api/latest/data-plane/upsert_records), and [Search with text](/reference/api/latest/data-plane/search_records) endpoints. The following Pinecone SDKs support using the Inference API: # Known limitations Source: https://docs.pinecone.io/reference/api/known-limitations This page describes known limitations and feature restrictions in Pinecone. ## General * [Upserts](/guides/index-data/upsert-data) * Pinecone is eventually consistent, so there can be a slight delay before upserted records are available to query. After upserting records, use the [`describe_index_stats`](/reference/api/2024-10/data-plane/describeindexstats) operation to check if the current vector count matches the number of records you expect, although this method may not work for pod-based indexes with multiple replicas. * Only indexes using the [dotproduct distance metric](/guides/index-data/indexing-overview#dotproduct) support querying sparse-dense vectors. Upserting, updating, and fetching sparse-dense vectors in indexes with a different distance metric will succeed, but querying will return an error. * Indexes created before February 22, 2023 do not support sparse vectors. * [Metadata](/guides/index-data/upsert-data#upsert-with-metadata-filters) * Null metadata values aren't supported. Instead of setting a key to `null`, remove the key from the metadata payload. * Nested JSON objects are not supported. ## Serverless indexes Serverless indexes do not support the following features: * [Filtering index statistics by metadata](/reference/api/2024-10/data-plane/describeindexstats) * [Private endpoints](/guides/production/connect-to-aws-privatelink) * This feature is available on AWS only. # API versioning Source: https://docs.pinecone.io/reference/api/versioning Pinecone's APIs are versioned to ensure that your applications continue to work as expected as the platform evolves. Versions are named by release date in the format `YYYY-MM`, for example, `2025-10`. ## Release schedule On a quarterly basis, Pinecone releases a new **stable** API version as well as a **release candidate** of the next stable version. * **Stable:** Each stable version remains unchanged and supported for a minimum of 12 months. Since stable versions are released every 3 months, this means you have at least 9 months to test and migrate your app to the newest stable version before support for the previous version is removed. * **Release candidate:** The release candidate gives you insight into the upcoming changes in the next stable version. It is available for approximately 3 months before the release of the stable version and can include new features, improvements, and [breaking changes](#breaking-changes). Below is an example of Pinecone's release schedule: ## Specify an API version When using the API directly, it is important to specify an API version in your requests. If you don't, requests default to the oldest supported stable version. Once support for that version ends, your requests will default to the next oldest stable version, which could include breaking changes that require you to update your integration. To specify an API version, set the `X-Pinecone-Api-Version` header to the version name. For example, based on the version support diagram above, if it is currently October 2025 and you want to use the latest stable version to describe an index, you would set `"X-Pinecone-Api-Version: 2025-10"`: ```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: 2025-10" ``` To use an older version, specify that version instead. ## SDK versions Official [Pinecone SDKs](/reference/pinecone-sdks) provide convenient access to Pinecone APIs. SDK versions are pinned to specific API versions. When a new API version is released, a new version of the SDK is also released. For the mapping between SDK and API versions, see [SDK versions](/reference/pinecone-sdks#sdk-versions). ## Breaking changes Breaking changes are changes that can potentially break your integration with a Pinecone API. Breaking changes include: * Removing an entire operation * Removing or renaming a parameter * Removing or renaming a response field * Adding a new required parameter * Making a previously optional parameter required * Changing the type of a parameter or response field * Removing enum values * Adding a new validation rule to an existing parameter * Changing authentication or authorization requirements ## Non-breaking changes Non-breaking changes are additive and should not break your integration. Additive changes include: * Adding an operation * Adding an optional parameter * Adding an optional request header * Adding a response field * Adding a response header * Adding enum values ## Get updates To ensure you always know about upcoming API changes, follow the [Release notes](/release-notes/). # CLI authentication Source: https://docs.pinecone.io/reference/cli/authentication This feature is in [public preview](/release-notes/feature-availability). This document describes how to authenticate the Pinecone CLI to manage your Pinecone resources. ## Authenticating There are three ways to authenticate the Pinecone CLI: through a web browser with [user login](#user-login), using a [service account](#service-account), or with an [API key](#api-key). This table describes the Pinecone operations supported by each authentication method: | Method | Admin API | Control plane | | :-------------- | :-------- | :------------ | | User login | ✅ | ✅ | | Service account | ✅ | ✅ | | API key | ❌ | ✅ | * Admin API–related commands (organization and project management, API key operations): * `pc organization` (`list`, `describe`, `update`, `delete`) * `pc project` (`create`, `list`, `describe`, `update`, `delete`) * `pc api-key` (`create`, `list`, `describe`, `update`, `delete`) * Control plane–related commands (index management): * `pc index` (`create`, `list`, `describe`, `configure`, `delete`) Commands for data plane operations will be added in a future release. ### User login User login requires you to authenticate through a web browser. Subsequent CLI requests use a locally stored auth token that expires after 30 minutes but refreshes automatically. After 24 hours, you must re-authenticate. ```bash theme={null} # Authenticate in a web browser pc auth login ``` When you authenticate with `pc auth login`, the CLI automatically targets: * The default organization returned by the server for your user. * The first project in the list of that organization's projects. However, you can change organization and project as needed: ```bash theme={null} pc auth target -o "my-org" -p "my-project" ``` When you authenticate with user login, the CLI uses [managed API keys](#managed-keys) for control plane operations, unless you've set a default API key. To learn more about targeting organizations and projects, see [CLI target context](/reference/cli/target-context). To understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ### Service account To authenticate with a service account, provide a client ID and secret associated with a [service account](/guides/organizations/manage-service-accounts). ```bash theme={null} pc auth configure \ --client-id "YOUR_CLIENT_ID" \ --client-secret "YOUR_CLIENT_SECRET" # Or specify a project directly pc auth configure \ --client-id "YOUR_CLIENT_ID" \ --client-secret "YOUR_CLIENT_SECRET" \ --project-id "YOUR_PROJECT_ID" ``` Or set these environment variables: ```bash theme={null} export PINECONE_CLIENT_ID="your-client-id" export PINECONE_CLIENT_SECRET="your-client-secret" ``` When you authentiate with a service account: * If your organization has only one project, the CLI automatically targets that project. * If your organization has multiple projects, the CLI prompts you to select a project (or you can use the `--project-id` flag, as shown above). * If your organization has no projects, create one. Then, set it as the target: ```bash theme={null} # Specify a project pc target -p "my-project" # Select a project interactively pc target ``` When you authenticate with a service account, the CLI uses [managed API keys](#managed-keys) for control plane operations, unless you've set a default API key. To learn more about targeting organizations and projects, see [CLI target context](/reference/cli/target-context). To understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ### API key You can also use an API to authenticate the CLI with Pinecone. This is useful for automation or CI/CD scenarios where you can't use interactive user login or a service account. Since each API key is associated with a specific project, the CLI uses that key's project for all operations. A default (manually specified) API key overrides any [target context](/reference/cli/target-context) you've set — you don't need to run `pc target`. ```bash theme={null} pc auth configure --api-key "YOUR_API_KEY" ``` Or set this environment variable: ```bash theme={null} export PINECONE_API_KEY="YOUR_API_KEY" ``` Because API keys are associated with a specific organization and project, they do not require [target context](/reference/cli/target-context). Also, to understand how the CLI prioritizes authentication methods, see [Auth priority](#auth-priority). ## Auth priority The CLI chooses which authentication method to use based on the type of operation. ### Control plane operations (indexes) Control plane operations prioritize authentication credentials in the following order: 1. Default API key - Uses the project associated with the key. 2. User login token - Creates and uses [managed keys](#managed-keys). 3. Service account - Creates and uses [managed keys](#managed-keys). ### Admin API operations (organizations, projects, API keys) Admin API operations prioritize authentication credentials in the following order: 1. User login token 2. Service account Default API keys do not provide Admin API access. ### Environment variables vs. stored configuration Within each credential type, environment variables always override stored configuration: * `PINECONE_API_KEY` (env var) overrides default API key stored via `pc auth configure --api-key`. * `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` (env vars) override service account credentials stored via `pc auth configure`. * User login tokens have no environment variable equivalent. They're always stored locally. **Example scenarios:** * If `PINECONE_API_KEY` (env var) is set, the CLI uses it for control plane operations, regardless of any stored default API key value. * If you're logged in via `pc auth login` and also have `PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET` set: * Control plane operations: User login token is used (creates managed keys). * Admin API operations: User login token is used. * The service account env vars are ignored. * If you have a default API key stored via `pc auth configure --api-key` and are also logged in through the web browser: * Control plane operations: Default API key is used. * Admin API operations: User login token is used. Environment variables are never persisted to local storage. They only override stored values at runtime. ### Default API keys and target context Default (manually specified) API keys override any [target context](/reference/cli/target-context). Control plane operations always use the project associated with the API key, regardless of what you've set with `pc target`. When you set a default API key (via `pc auth configure --api-key` or `PINECONE_API_KEY`): * The default API key is used for control plane operations. * [Managed keys](#managed-keys) are not created. * If you also have user login or service account credentials, those are still used for Admin API operations. Setting a default API key (via `pc auth configure --api-key` or `PINECONE_API_KEY`) does not clear user login tokens or service account credentials. ### User login and service accounts User login and service accounts are mutually exclusive when configured via CLI commands: * Running `pc auth login` clears any stored service account credentials. * Running `pc auth configure --client-id --client-secret` clears the stored auth token from `pc auth login`. However, if you set service account environment variables (`PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET`) without running `pc auth configure`, the CLI does not clear your stored user login token. User login and service accounts both use [managed keys](#managed-keys) for control plane operations (unless you've set a default API key). ## Clearing credentials (logging out) To clear your authentication credentials: ```bash theme={null} pc auth logout ``` This command clears local data: * 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](/reference/cli/target-context) `pc auth logout` does not delete managed API keys from Pinecone's servers. Those keys remain active and can be used to access your projects. To fully clean up, run `pc auth local-keys prune` before logging out. See [Deleting API keys](#deleting-api-keys) for details. ## Managed keys When authenticated with [user login](#user-login) or a [service account](#service-account), the CLI automatically creates and manages API keys for control plane operations. This happens transparently, the first time you run a control plane command like `pc index list`. You don't need to create or manage these keys yourself. ### When managed keys are created Managed keys are created only when you're authenticated via user login or service account, and there's no default (manually specified) API key set. After authenticating, the first time you run a control plane command like `pc index list`: 1. The CLI checks if a managed key already exists locally for the target project. 2. If not found, the CLI creates a new API key via the Admin API. 3. The key is stored both remotely (in Pinecone) and locally for future use. Subsequent commands targeting the same project reuse the stored key. If you set a default API key, managed keys are not created. The default API key is used instead. ### Where managed keys are stored Managed API keys are stored locally and remotely: * Local: Stored in `~/.config/pinecone/secrets.yaml` under the `project_api_keys` field as plain text, with file permissions set to 0600 (owner read/write only). For more details, see [Local data storage](#local-data-storage). * Remote: Stored in Pinecone as regular API keys, visible in the web console. The CLI will not display managed API keys after they're created. ### Identifying managed keys In the Pinecone web console, CLI-created keys have: * Name: `pinecone-cli-{6-character-alphanumeric}` (for example, `pinecone-cli-a3f9k2`) * Origin: `cli_created` To list all managed keys stored locally: ```bash theme={null} pc auth local-keys list ``` This shows managed keys tracked in your local `secrets.yaml` file, including which projects they belong to. ### Deleting API keys There are a few ways to use the CLI to delete API keys (managed or not), locally and remotely. **Delete locally tracked managed keys (local and remote)**: The `pc auth local-keys prune` command deletes managed keys that are tracked in your local `secrets.yaml` file. It does not affect API keys that were created outside the CLI or aren't tracked locally. ```bash theme={null} # Delete all locally tracked managed keys (CLI-created and user-created) 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 (local and remote)**: ```bash theme={null} pc api-key delete --id "YOUR_API_KEY_ID" ``` This deletes any API key (managed or not) and cleans up the local record if it exists. **Automatic deletion when creating a new key**: 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. This prevents accumulating multiple managed keys per project. `pc auth logout` deletes only the local references to managed keys. The keys remain active remotely in Pinecone. To fully clean up, run `pc auth local-keys prune` before logging out. ## Local data storage Authentication data is stored in `~/.config/pinecone/` with restricted permissions (0600): **`secrets.yaml`** - Sensitive data: * `oauth2_token`: Token associated with a user login (`pc auth login`) * `client_id`, `client_secret`: Service account credentials * `api_key`: Default (manually specified) API key * `project_api_keys`: Managed keys per project **`state.yaml`** - Context: * `target_org`: Current organization (name and ID) * `target_project`: Current project (name and ID) **`config.yaml`** - Settings: * `color`: Enable/disable colored output * `environment`: Production or staging ## Check authentication status ```bash theme={null} pc auth status ``` Shows: * Current authentication method * Target organization and project * Token expiration (for user login) * Environment configuration # CLI command reference Source: https://docs.pinecone.io/reference/cli/command-reference This feature is in [public preview](/release-notes/feature-availability). This document provides a complete reference for all Pinecone CLI commands. ## Command structure The Pinecone CLI uses a hierarchical command structure. Each command consists of a primary command followed by one or more subcommands and optional flags. ```bash theme={null} pc [flags] pc [flags] ``` For example: ```bash theme={null} # Top-level command with flags pc target -o "organization-name" -p "project-name" # Command (index) and subcommand (list) pc index list # Command (index) and subcommand (create) with flags pc index create \ --name my-index \ --dimension 1536 \ --metric cosine \ --cloud aws \ --region us-east-1 # Command (auth) and nested subcommands (local-keys prune) with flags pc auth local-keys prune --id proj-abc123 --skip-confirmation ``` ## Getting help The CLI provides help for commands at every level: ```bash theme={null} # top-level help pc --help pc -h # command help pc auth --help pc index --help pc project --help # subcommmand help pc index create --help pc project create --help pc auth configure --help # nested subcommand help pc auth local-keys prune --help ``` ## Exit codes All commands return exit code `0` for success and `1` for error. ## Available commands This section describes all commands offered by the Pinecone CLI. ### Top-level commands **Description** Authenticate via a web browser. After login, set a [target org and project](/reference/cli/target-context) with `pc target` before accessing data. This command defaults to an initial organization and project to which you have access (these values display in the terminal), but you can change them with `pc target`. **Usage** ```bash theme={null} pc login ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Log in via browser pc login # Then set target context pc target -o "my-org" -p "my-project" ``` This is an alias for `pc auth login`. Both commands perform the same operation. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear all credentials and context pc logout ``` This is an alias for `pc auth logout`. Both commands perform the same operation. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Set the target organization and project for the CLI. Supports interactive organization and project selection or direct specification via flags. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc target [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :----------------------------- | | `--clear` | | Clear target context | | `--json` | | 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 | **Example** ```bash theme={null} # Interactive targeting after login pc login pc target # Set specific organization and project pc target -o "my-org" -p "my-project" # Show current context pc target --show # Clear all context pc target --clear ``` **Description** Displays version information for the CLI, including the version number, commit SHA, and build date. **Usage** ```bash theme={null} pc version ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Display version information pc version ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} pc whoami ``` This is an alias for `pc auth whoami`. Both commands perform the same operation. ### Authentication **Description** Selectively clears specific authentication data without affecting other credentials. At least one flag is required. **Usage** ```bash theme={null} pc auth clear [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------ | :--------- | :-------------------------------------------------- | | `--api-key` | | Clear only the default (manually specified) API key | | `--service-account` | | Clear only service account credentials | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear only the default (manually specified) API key pc auth clear --api-key pc auth status # Clear service account pc auth clear --service-account ``` More surgical than `pc auth logout`. Does not clear user login token or managed keys. For those, use `pc auth logout` or `pc auth local-keys prune`. **Description** Configures service account credentials or a default (manually specified) API key. Service accounts automatically target the organization and prompt for project selection, unless there is only one project. A default API key overrides any previously specified target organization/project context. When setting a service account, this operation clears the user login token, if one exists. For details, see [CLI target context](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :--------------------------------------------------- | | `--api-key` | | Default API key to use for authentication | | `--client-id` | | Service account client ID | | `--client-secret` | | Service account client secret | | `--client-secret-stdin` | | Read client secret from stdin | | `--json` | | 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 | **Example** ```bash theme={null} # Service account setup (auto-targets org and prompts for project) pc auth configure --client-id my-id --client-secret my-secret # Service account with specific project pc auth configure \ --client-id my-id \ --client-secret my-secret \ -p proj-123 # Default API key (overrides any target context) pc auth configure --api-key pcsk_abc123 ``` `pc auth configure --api-key "YOUR_API_KEY"` does the same thing as `pc config set-api-key "YOUR_API_KEY"`. To learn about targeting a project after authenticating with a service account, see [CLI target context](/reference/cli/target-context). **Description** Displays all [managed API keys](/reference/cli/authentication#managed-keys) stored locally by the CLI, with various details. **Usage** ```bash theme={null} pc auth local-keys list [flags] ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :----------------------------------------- | | `--json` | | 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 | **Example** ```bash theme={null} # List all locally managed keys pc auth local-keys list # Show key values pc auth local-keys list --reveal # After storing a key pc api-key create -n "my-key" --store pc auth local-keys list ``` **Description** Deletes locally stored [managed API keys](/reference/cli/authentication#managed-keys) from local storage and Pinecone's servers. Filters by origin (`cli`/`user`/`all`) or project ID. **Usage** ```bash theme={null} pc auth local-keys prune [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--dry-run` | | Preview deletions without applying | | `--id` | | Prune keys for specific project ID only | | `--json` | | 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 | **Example** ```bash theme={null} # Preview deletions pc auth local-keys prune --dry-run # Delete CLI-created keys only pc auth local-keys prune -o cli --skip-confirmation # Delete for specific project pc auth local-keys prune --id proj-abc123 # Before/after check pc auth local-keys list pc auth local-keys prune -o cli pc auth local-keys list ``` This deletes keys from both local storage and Pinecone servers. Use `--dry-run` to preview before committing. **Description** Authenticate via user login in the web browser. After login, [set a target org and project](/reference/cli/target-context). **Usage** ```bash theme={null} pc auth login pc login # shorthand ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Login and set target pc auth login pc target -o "my-org" -p "my-project" pc index list ``` Tokens expire after 30 minutes, but they refresh automatically for up to 24 hours. After that point, you must re-authenticate. Logging in clears any existing service account credentials. This command does the same thing as `pc login`. **Description** Clears all authentication data from local storage, including: * User login token * Service account credentials (client ID and secret) * Default (manually specified) API key * Locally managed keys (for all projects) * Target organization and project context **Usage** ```bash theme={null} pc auth logout ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Clear all credentials and context pc auth logout ``` This command does the same thing as `pc logout`. Does not delete managed API keys from Pinecone's servers. Run `pc auth local-keys prune` before logging out to fully clean up. **Description** Shows details about all configured authentication methods. **Usage** ```bash theme={null} pc auth status [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Check status after login pc auth login pc auth status # JSON output for scripting pc auth status --json ``` **Description** Displays information about the currently authenticated user. To use this command, you must be authenticated via user login. **Usage** ```bash theme={null} pc auth whoami ``` **Flags** None **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} pc auth whoami ``` This command does the same thing as `pc whoami`. ### Indexes **Description** Modifies the configuration of an existing index. **Usage** ```bash theme={null} pc index configure [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :------------------------------------------------------------- | | `--deletion_protection` | `-p` | Enable or disable deletion protection -`enabled` or `disabled` | | `--json` | | Output in JSON format | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Enable deletion protection pc index configure -n my-index -p enabled # Verify changes pc index describe -n my-index ``` Configuration changes may take some time to take effect. **Description** Creates a new serverless index in your Pinecone project, with various configuration optons. **Usage** ```bash theme={null} pc index create [flags] ``` **Flags** | Long flag | Short flag | Description | | :---------------------- | :--------- | :------------------------------------------------------------------------ | | `--cloud` | `-c` | Cloud provider - `aws`, `gcp`, or `azure` (required for serverless) | | `--deletion_protection` | | Deletion protection - `enabled` or `disabled` | | `--dimension` | `-d` | Vector dimension (required for standard indexes, optional for integrated) | | `--field_map` | | Field mapping for integrated embedding (JSON map) | | `--json` | | Output in JSON format | | `--metric` | `-m` | Similarity metric - `cosine`, `euclidean`, or `dotproduct` (required) | | `--model` | | Integrated embedding model name | | `--name` | `-n` | Index name (required) | | `--read_parameters` | | Read parameters for embedding model (JSON map) | | `--region` | `-r` | Cloud region | | `--source_collection` | | Name of the source collection from which to create the index | | `--tags` | | Custom user tags (key=value pairs) | | `--vector_type` | `-v` | Vector type - `dense` or `sparse` (serverless only) | | `--write_parameters` | | Write parameters for embedding model (JSON map) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Create serverless index pc index create -n my-index -d 1536 -m cosine -c aws -r us-east-1 # With integrated embedding model pc index create \ -n my-index \ -m cosine \ -c aws \ -r us-east-1 \ --model multilingual-e5-large # 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 ``` For a list of valid regions for a serverless index, see [Create a serverless index](/guides/index-data/create-an-index). **Description** Permanently deletes an index and all its data. This operation cannot be undone. **Usage** ```bash theme={null} pc index delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Delete an index pc index delete -n my-index # List before and after pc index list pc index delete -n test-index pc index list ``` **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 | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | | `--name` | `-n` | Index name (required) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an index pc index describe -n my-index # JSON output pc index describe -n my-index --json # Check newly created index pc index create -n test-index -d 1536 -m cosine -c aws -r us-east-1 pc index describe -n test-index ``` **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` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all indexes pc index list # JSON output for scripting pc index list --json # After creating indexes pc index create -n test-1 -d 768 -m cosine -c aws -r us-east-1 pc index list ``` ### Projects **Description** Creates a new project in your [target organization](/reference/cli/target-context), using the specified configuration. **Usage** ```bash theme={null} pc project create [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :------------------------------------------------------------- | | `--force-encryption` | | Enable encryption with CMEK | | `--json` | | 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 | **Example** ```bash theme={null} # Basic project creation pc project create -n "demo-project" ``` **Description** Permanently deletes a project and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc project delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | 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 | **Example** ```bash theme={null} # Delete target project pc project delete # Delete specific project pc project delete -i proj-abc123 # Skip confirmation pc project delete -i proj-abc123 --skip-confirmation ``` Must delete all indexes and collections in the project first. If the deleted project is your current target, set a new target after deleting it. **Description** Displays detailed information about a specific project, including various details. **Usage** ```bash theme={null} pc project describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | Project ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe a project pc project describe -i proj-abc123 # JSON output pc project describe -i proj-abc123 --json # Find ID and describe pc project list pc project describe -i proj-abc123 ``` **Description** Displays all projects in your [target organization](/reference/cli/target-context), including various details. **Usage** ```bash theme={null} pc project list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all projects pc project list # JSON output pc project list --json # List after login pc auth login pc auth target -o "my-org" pc project list ``` **Description** Modifies the configuration of the [target project](/reference/cli/target-context), or a specific project ID. **Usage** ```bash theme={null} pc project update [flags] ``` **Flags** | Long flag | Short flag | Description | | :------------------- | :--------- | :---------------------------------- | | `--force-encryption` | `-f` | Enable/disable encryption with CMEK | | `--id` | `-i` | Project ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Update name pc project update -i proj-abc123 -n "new-name" ``` ### Organizations **Description** Permanently deletes an organization and all its resources. This operation cannot be undone. **Usage** ```bash theme={null} pc organization delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Delete an organization pc organization delete -i org-abc123 # Skip confirmation pc organization delete -i org-abc123 --skip-confirmation ``` This is a highly destructive action. Deletion is permanent. If the deleted organization is your current [target](/reference/cli/target-context), set a new target after deleting. **Description** Displays detailed information about a specific organization, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an organization pc organization describe -i org-abc123 # JSON output pc organization describe -i org-abc123 --json # Find ID and describe pc organization list pc organization describe -i org-abc123 ``` **Description** Displays all organizations that the authenticated user has access to, including name, ID, creation date, payment status, plan, and support tier. **Usage** ```bash theme={null} pc organization list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List all organizations pc organization list # JSON output pc organization list --json # List after login pc auth login pc organization list ``` **Description** Modifies the configuration of the [target organization](/reference/cli/target-context), or a specific organization ID. **Usage** ```bash theme={null} pc organization update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :------------------------- | | `--id` | `-i` | Organization ID (required) | | `--json` | | 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 | **Example** ```bash theme={null} # Update name pc organization update -i org-abc123 -n "new-name" # Verify changes pc organization update -i org-abc123 -n "Acme Corp" pc organization describe -i org-abc123 ``` ### API keys **Description** Creates a new API key for the current [target project](/reference/cli/target-context) or a specific project ID. Optionally stores the key locally for CLI use. **Usage** ```bash theme={null} pc api-key create [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------------------------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | 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 | **Example** ```bash theme={null} # Basic key creation pc api-key create -n "my-key" # Create and store locally pc api-key create -n "my-key" --store # Create with specific role pc api-key create -n "my-key" --store --roles ProjectEditor # Create for specific project pc api-key create -n "my-key" -i proj-abc123 ``` API keys are scoped to a specific organization and project. **Description** Permanently deletes an API key. Applications using this key immediately lose access. **Usage** ```bash theme={null} pc api-key delete [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------------------- | :--------- | :----------------------- | | `--id` | `-i` | API key ID (required) | | `--skip-confirmation` | | Skip confirmation prompt | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Delete an API key pc api-key delete -i key-abc123 # Skip confirmation pc api-key delete -i key-abc123 --skip-confirmation # Delete and clean up local storage pc api-key delete -i key-abc123 pc auth local-keys prune --skip-confirmation ``` Deletion is permanent. Applications using this key immediately lose access to Pinecone. **Description** Displays detailed information about a specific API key, including its name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key describe [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Describe an API key pc api-key describe -i key-abc123 # JSON output pc api-key describe -i key-abc123 --json # Find ID and describe pc api-key list pc api-key describe -i key-abc123 ``` Does not display the actual key value. **Description** Displays a list of all of the [target project's](/reference/cli/target-context) API keys, as found in Pinecone (regardless of whether they are stored locally by the CLI). Displays various details about each key, including name, ID, project ID, and roles. **Usage** ```bash theme={null} pc api-key list [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :---------------------------------------------------------- | | `--id` | `-i` | Project ID (optional, uses target project if not specified) | | `--json` | | Output in JSON format | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # List keys for target project pc api-key list # List for specific project pc api-key list -i proj-abc123 # JSON output pc api-key list --json ``` Does not display key values. **Description** Updates the name and roles of an API key. **Usage** ```bash theme={null} pc api-key update [flags] ``` **Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--id` | `-i` | API key ID (required) | | `--json` | `-j` | Output in JSON format | | `--name` | `-n` | New key name | | `--roles` | `-r` | Roles to assign | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Update name pc api-key update -i key-abc123 -n "new-name" # Update roles pc api-key update -i key-abc123 -r ProjectEditor # Verify changes pc api-key update -i key-abc123 -n "production-key" pc api-key describe -i key-abc123 ``` Cannot change the actual key. If you need a different key, create a new one. ### Config **Description** Displays the currently configured default (manually specified) API key, if set. By default, the full value of the key is not displayed. **Usage** ```bash theme={null} pc config get-api-key ``` **Flags** | Long flag | Short flag | Description | | :--------- | :--------- | :---------------------------------------- | | `--reveal` | | Show the actual API key value (sensitive) | **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Get current API key pc config get-api-key # Verify after setting pc config set-api-key pcsk_abc123 pc config get-api-key ``` **Description** Sets a default API key for the CLI to use for authentication. Provides direct access to control plane operations, but not Admin API operations. **Usage** ```bash theme={null} pc config set-api-key "YOUR_API_KEY" ``` **Flags** None (takes API key as argument) **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Set default API key pc config set-api-key pcsk_abc123 # Use immediately without targeting pc config set-api-key pcsk_abc123 pc index list # Verify it's set pc auth status ``` `pc config set-api-key "YOUR_API_KEY"` does the same thing as `pc auth configure --api-key "YOUR_API_KEY"`. For control plane operations, a default API key implicitly overrides any previously set [target context](/reference/cli/target-context), because Pinecone API keys are scoped to a specific organization and project. **Description** Enables or disables colored output in CLI responses. Useful for terminal compatibility or log file generation. **Usage** ```bash theme={null} pc config set-color true pc config set-color false ``` **Flags** None (takes boolean as argument) **Global Flags** | Long flag | Short flag | Description | | :-------- | :--------- | :-------------------- | | `--help` | `-h` | Show help information | | `--quiet` | `-q` | Suppress output | **Example** ```bash theme={null} # Enable colored output pc config set-color true # Disable colored output for CI/CD pc config set-color false # Test the change pc config set-color false pc index list ``` # CLI installation Source: https://docs.pinecone.io/reference/cli/installation This feature is in [public preview](/release-notes/feature-availability). This document describes how to install the Pinecone CLI on your local machine. ## Platforms Pinecone's CLI is available for the following platforms: * **macOS**: Intel (x86\_64) and Apple Silicon (ARM64) * **Linux**: x86\_64, ARM64, and i386 architectures * **Windows**: x86\_64 and i386 architectures ## Installation ### Homebrew (macOS) The most convenient way to install the CLI on Mac: ```bash theme={null} brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` To upgrade to the latest version: ```bash theme={null} brew update brew upgrade pinecone ``` ### Direct download (all platforms) Pre-built binaries for all supported platforms are available on the [GitHub Releases page](https://github.com/pinecone-io/cli/releases). ### Build from source To build from source, see the [CONTRIBUTING.md](https://github.com/pinecone-io/cli/blob/main/CONTRIBUTING.md) file for detailed instructions. To build from source, you need Go v1.23+. # CLI overview Source: https://docs.pinecone.io/reference/cli/overview This feature is in [public preview](/release-notes/feature-availability). The Pinecone CLI (`pc`) is a command-line tool for managing Pinecone infrastructure (projects, organizations, indexes, and API keys) directly from your terminal. Use it to: * Automate infrastructure operations * Integrate Pinecone into CI/CD pipelines * Manage resources without using the web console ## Supported The CLI currently supports the following features: * Authentication (user login, service account, API key) * Projects and organizations (create, update, delete, list) * Indexes (create, configure, delete, list) * API key management ## Not yet supported The CLI does not yet support the following features: * Vector and namespace operations * Bulk data imports * Index statistics * Inference (embeddings, reranking) * Assistant operations * Dedicated read nodes For these features, use Pinecone's [REST API](/reference/api) or SDKs: [Python](/reference/python-sdk), [Node.js](/reference/node-sdk), [Java](/reference/java-sdk), [Go](/reference/go-sdk), [.NET](/reference/dotnet-sdk), or [Rust](/reference/rust-sdk) (alpha). # CLI quickstart Source: https://docs.pinecone.io/reference/cli/quickstart This feature is in [public preview](/release-notes/feature-availability). 1. Install the Pinecone CLI: ```shell macOS theme={null} # Using Homebrew (https://brew.sh) brew tap pinecone-io/tap brew install pinecone-io/tap/pinecone ``` ```shell Linux/Windows theme={null} Download pre-build binaries from https://github.com/pinecone-io/cli/releases ``` 2. Authenticate the CLI with Pinecone by [user login](/reference/cli/authentication#user-login): ```bash theme={null} # Authenticate in a web browser pc auth login ``` To authenticate with Pinecone, visit the URL displayed in the terminal. After you sign in, the terminal displays a success message: ``` [SUCCESS] Logged in as user@example.com. Defaulted to organization ID: [INFO] Target org set to [INFO] Target project set to ``` As shown by the `[INFO]` messages, this command automatically sets a [target organization and project](/reference/cli/target-context) for the CLI. 3. If necessary, target a different organization and/or project: ```bash theme={null} pc auth target -o "my-org-name" -p "my-project-name" ``` 4. List the indexes in the project: ```bash theme={null} pc index list ``` ## Next steps See the [command reference](/reference/cli/command-reference) to learn about the various commands offered by the CLI. # CLI target context Source: https://docs.pinecone.io/reference/cli/target-context This feature is in [public preview](/release-notes/feature-availability). Most CLI operations happen within the context of a specific organization and project. The **target context** is the organization and project scope that the CLI uses when running commands. Before setting target context, you must authenticate with the CLI. See [CLI authentication](/reference/cli/authentication) for details on authentication methods. ## Why target context matters By specifying a target organization and/or project, you're telling the CLI which resources to operate on. * **Control plane operations** (creating indexes, listing indexes): Always happen within a specific project. * **Admin API operations**: * Organization operations don't require target context. They operate on organizations you have access to. * Project management operations are scoped to your target organization. For example, running `pc project list` shows projects in the target org. * API key operations are scoped to the target project, unless you specify `--id`. ## How target context works How the CLI sets and uses target context depends on your authentication method and how you configure it. ### User login When you authenticate with `pc auth login`, the CLI automatically [targets](/reference/cli/target-context): * The default organization returned by the server for your user. * The first project in the list of that organization's projects. However, you can change organization and project as needed: ```bash theme={null} pc auth login pc target -o "my-org" -p "my-project" ``` ### Service account **Configured via CLI command** When you configure a service account with `pc auth configure --client-id --client-secret`, the CLI automatically targets the organization associated with the service account (service accounts belong to a single organization). Then, to target a project: * If the selected organization has only one project, the CLI automatically targets it. * If that organization has multiple projects, the CLI prompts you to select one (or you can use the `--project-id` flag). * If it doesn't have any projects, create one and then target it manually. To change to a specific target project: ```bash theme={null} pc target -p "different-project" ``` Or, to select a project interactively: ```bash theme={null} pc target ``` **Configured via environment variables** If you set service account credentials via environment variables (`PINECONE_CLIENT_ID` and `PINECONE_CLIENT_SECRET`) without running `pc auth configure`, the CLI does **not** automatically set any target context. You must explicitly set it with `pc target`. Service accounts are scoped to a single organization. You can only target the organization associated with your service account credentials. To do this, and also target a specific project within that organization: ```bash theme={null} pc target -o "my-org" -p "my-project" ``` Or, to select a project interactively (the CLI discovers the organization automatically): ```bash theme={null} pc target ``` ### API key When you set a default API key (with `pc auth configure --api-key` or the `PINECONE_API_KEY` environment variable), the CLI does **not** change or clear its stored target context. However, in this scenario, control plane operations **do** use the API key's organization and project — not the CLI's saved target context (regardless of any calls you've made to `pc target`, or the output of `pc target --show`). This happens because Pinecone API keys are always scoped to a specific organization and project, and they cannot access resources outside of that scope. Because Pinecone API keys cannot be used to authenticate calls to the Admin API, Admin API operations still authentiate with your user login token or service account credentials (if available). ```bash theme={null} pc auth login pc target -o "my-org" -p "my-project" # Setting an API key doesn't change stored target context pc auth configure --api-key "YOUR_API_KEY" pc target --show # Still shows my-org and my-project, but they're not used for control plane operations ``` ## Viewing and managing target context To view your current target organization and project: ```bash theme={null} # Show current target context pc target --show # Clear target context pc target --clear ``` # .NET SDK Source: https://docs.pinecone.io/reference/dotnet-sdk See the [.NET SDK documentation](https://github.com/pinecone-io/pinecone-dotnet-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-dotnet-client/issues). ## Requirements To use this Python .NET SDK, ensure that your project is targeting one of the following: * .NET Standard 2.0+ * .NET Core 3.0+ * .NET Framework 4.6.2+ * .NET 6.0+ ## 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 .NET SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `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 add the latest version of the [.NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client) to your project, run the following command: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client ``` To add a specific version of the [.NET SDK](https://github.com/pinecone-io/pinecone-dotnet-client) to your project, run the following command: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client --version ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client -Version ``` To check your SDK version, run the following command: ```shell .NET Core CLI theme={null} dotnet list package ``` ```shell NuGet CLI theme={null} nuget list ``` ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-05-14-2). If you are already using `Pinecone.Client` in your project, upgrade to the latest version as follows: ```shell .NET Core CLI theme={null} dotnet add package Pinecone.Client ``` ```shell NuGet CLI theme={null} nuget install Pinecone.Client ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```csharp C# theme={null} using Pinecone; var pinecone = new PineconeClient("YOUR_API_KEY"); ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, configure the HTTP client as follows: ```csharp theme={null} using System.Net; using Pinecone; var pinecone = new PineconeClient("PINECONE_API_KEY", new ClientOptions { HttpClient = new HttpClient(new HttpClientHandler { Proxy = new WebProxy("PROXY_HOST:PROXY_PORT") }) }); ``` If you're building your HTTP client using the [HTTP client factory](https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory#configure-the-httpmessagehandler), use the `ConfigurePrimaryHttpMessageHandler` method to configure the proxy: ```csharp theme={null} .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler { Proxy = new WebProxy("PROXY_HOST:PROXY_PORT") }); ``` # Go SDK Source: https://docs.pinecone.io/reference/go-sdk See the [Go SDK documentation](https://github.com/pinecone-io/go-pinecone/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](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 | | :---------- | :---------- | | `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/v4/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/v4/pinecone@ ``` To check your SDK version, run the following command: ```shell theme={null} go list -u -m all | grep go-pinecone ``` ## Upgrade Before upgrading to `v3.0.0` or later, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-4). 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/v4/pinecone@latest ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Go theme={null} package main import ( "context" "log" "github.com/pinecone-io/go-pinecone/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) } } ``` # Java SDK Source: https://docs.pinecone.io/reference/java-sdk See the [Pinecone Java SDK documentation](https://github.com/pinecone-io/pinecone-java-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-java-client/issues). ## Requirements The Pinecone Java SDK Java 1.8 or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Java SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v5.x | | `2025-01` | v4.x | | `2024-10` | v3.x | | `2024-07` | v2.x | | `2024-04` | v1.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Java SDK](https://github.com/pinecone-io/pinecone-java-client), add a dependency to the current module: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` Alternatively, you can download the standalone uberjar [pinecone-client-4.0.0-all.jar](https://repo1.maven.org/maven2/io/pinecone/pinecone-client/4.0.0/pinecone-client-4.0.0-all.jar), which bundles the Pinecone SDK and all dependencies together. You can include this in your classpath like you do with any third-party JAR without having to obtain the `pinecone-client` dependencies separately. ## Upgrade Before upgrading to `v4.0.0`, update all relevant code to account for the breaking changes explained [here](/release-notes/2025#2025-02-07-3). If you are already using the Java SDK, upgrade the dependency in the current module to the latest version: ```shell Java theme={null} # Maven io.pinecone pinecone-client 5.0.0 # Gradle implementation "io.pinecone:pinecone-client:5.0.0" ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```Java theme={null} import io.pinecone.clients.Pinecone; import org.openapitools.db_control.client.model.*; public class InitializeClientExample { public static void main(String[] args) { Pinecone pc = new Pinecone.Builder("YOUR_API_KEY").build(); } } ``` # Node.js SDK Source: https://docs.pinecone.io/reference/node-sdk See the [Pinecone Node.js SDK documentation](https://sdk.pinecone.io/typescript/) for full installation instructions, usage examples, and reference information. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-ts-client/issues). ## Requirements The Pinecone Node SDK requires TypeScript 4.1 or later and Node 18.x or later. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Node.js SDK versions are as follows: | API version | SDK version | | :---------- | :---------- | | `2025-04` | v6.x | | `2025-01` | v5.x | | `2024-10` | v4.x | | `2024-07` | v3.x | | `2024-04` | v2.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Node.js SDK](https://github.com/pinecone-io/pinecone-ts-client), written in TypeScript, run the following command: ```Shell theme={null} npm install @pinecone-database/pinecone ``` To check your SDK version, run the following command: ```Shell theme={null} npm list | grep @pinecone-database/pinecone ``` ## Upgrade If you already have the Node.js SDK, upgrade to the latest version as follows: ```Shell theme={null} npm install @pinecone-database/pinecone@latest ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```JavaScript theme={null} import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' }); ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you can pass a custom `ProxyAgent` from the [`undici` library](https://undici.nodejs.org/#/). Below is an example of how to construct an `undici` `ProxyAgent` that routes network traffic through a [`mitm` proxy server](https://mitmproxy.org/) while hitting Pinecone's `/indexes` endpoint. The following strategy relies on Node's native [`fetch`](https://nodejs.org/docs/latest/api/globals.html#fetch) implementation, released in Node v16 and stabilized in Node v21. If you are running Node versions 18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues related to proxying in Node v18+. ```JavaScript JavaScript theme={null} import { Pinecone, type PineconeConfiguration, } from '@pinecone-database/pinecone'; import { Dispatcher, ProxyAgent } from 'undici'; import * as fs from 'fs'; const cert = fs.readFileSync('path/to/mitmproxy-ca-cert.pem'); const client = new ProxyAgent({ uri: 'https://your-proxy.com', requestTls: { port: 'YOUR_PROXY_SERVER_PORT', ca: cert, host: 'YOUR_PROXY_SERVER_HOST', }, }); const customFetch = ( input: string | URL | Request, init: RequestInit | undefined ) => { return fetch(input, { ...init, dispatcher: client as Dispatcher, keepalive: true, # optional }); }; const config: PineconeConfiguration = { apiKey: 'YOUR_API_KEY', fetchApi: customFetch, }; const pc = new Pinecone(config); const indexes = async () => { return await pc.listIndexes(); }; indexes().then((response) => { console.log('My indexes: ', response); }); ``` # Introduction Source: https://docs.pinecone.io/reference/pinecone-sdks ## Pinecone SDKs Official Pinecone SDKs provide convenient access to the [Pinecone APIs](/reference/api/introduction). ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and SDK versions are as follows: | | `2025-04` | `2025-01` | `2024-10` | `2024-07` | `2024-04` | | ----------------------------------- | :-------- | :-------- | :-------- | :------------ | :-------- | | [Python SDK](/reference/python-sdk) | v7.x | v6.x | v5.3.x | v5.0.x-v5.2.x | v4.x | | [Node.js SDK](/reference/node-sdk) | v6.x | v5.x | v4.x | v3.x | v2.x | | [Java SDK](/reference/java-sdk) | v5.x | v4.x | v3.x | v2.x | v1.x | | [Go SDK](/reference/go-sdk) | v4.x | v3.x | v2.x | v1.x | v0.x | | [.NET SDK](/reference/dotnet-sdk) | 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. SDKs that target API version `2025-10` will be available soon. ## Limitations While Pinecone tracks read unit usage with decimal precision, the Pinecone API and SDKs round these values up to the nearest whole number in query, fetch, and list responses. For example, if a query uses 0.45 read units, the API and SDKs will report it as 1 read unit. For precise read unit reporting, see [index-level metrics](/guides/production/monitoring) or the organization-wide [Usage dashboard](/guides/manage-cost/monitor-usage-and-costs#monitor-organization-level-usage-and-costs). ## Community SDKs Find community-contributed SDKs for Pinecone. These libraries are not supported by Pinecone. * [Ruby SDK](https://github.com/ScotterC/pinecone) (contributed by [ScotterC](https://github.com/ScotterC)) * [Scala SDK](https://github.com/cequence-io/pinecone-scala) (contributed by [cequence-io](https://github.com/cequence-io)) * [PHP SDK](https://github.com/probots-io/pinecone-php) (contributed by [protobots-io](https://github.com/probots-io)) # Python SDK Source: https://docs.pinecone.io/reference/python-sdk The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default, the `pinecone` package has a minimal set of dependencies and interacts with Pinecone via HTTP requests. However, you can install the following extras to unlock additional functionality: * `pinecone[grpc]` adds dependencies on `grpcio` and related libraries needed to run data operations such as upserts and queries over [gRPC](https://grpc.io/) for a modest performance improvement. * `pinecone[asyncio]` adds a dependency on `aiohttp` and enables usage of `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). For more details, see [Asyncio support](#async-requests). See the [Pinecone Python SDK documentation](https://sdk.pinecone.io/python/) for full installation instructions, usage examples, and reference information. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-python-client/issues). ## Requirements The Pinecone Python SDK requires Python 3.9 or later. It has been tested with CPython versions from 3.9 to 3.13. ## SDK versions SDK versions are pinned to specific [API versions](/reference/api/versioning). When a new API version is released, a new version of the SDK is also released. The mappings between API versions and Python SDK versions are as follows: | API version | SDK version | | :---------- | :------------ | | `2025-04` | v7.x | | `2025-01` | v6.x | | `2024-10` | v5.3.x | | `2024-07` | v5.0.x-v5.2.x | | `2024-04` | v4.x | When a new stable API version is released, you should upgrade your SDK to the latest version to ensure compatibility with the latest API changes. ## Install To install the latest version of the [Python SDK](https://github.com/pinecone-io/pinecone-python-client), run the following command: ```shell theme={null} # Install the latest version pip install pinecone # Install the latest version with gRPC extras pip install "pinecone[grpc]" # Install the latest version with asyncio extras pip install "pinecone[asyncio]" ``` To install a specific version of the Python SDK, run the following command: ```shell pip theme={null} # Install a specific version pip install pinecone== # Install a specific version with gRPC extras pip install "pinecone[grpc]"== # Install a specific version with asyncio extras pip install "pinecone[asyncio]"== ``` To check your SDK version, run the following command: ```shell pip theme={null} pip show pinecone ``` To use the [Inference API](/reference/api/introduction#inference), you must be on version 5.0.0 or later. ### Install the Pinecone Assistant Python plugin As of Python SDK v7.0.0, the `pinecone-plugin-assistant` package is included by default. It is only necessary to install the package if you are using a version of the Python SDK prior to v7.0.0. ```shell HTTP theme={null} pip install --upgrade pinecone pinecone-plugin-assistant ``` ## Upgrade Before upgrading to `v6.0.0`, update all relevant code to account for the breaking changes explained [here](https://github.com/pinecone-io/pinecone-python-client/blob/main/docs/upgrading.md). Also, make sure to upgrade using the `pinecone` package name instead of `pinecone-client`; upgrading with the latter will not work as of `v6.0.0`. If you already have the Python SDK, upgrade to the latest version as follows: ```shell theme={null} # Upgrade to the latest version pip install pinecone --upgrade # Upgrade to the latest version with gRPC extras pip install "pinecone[grpc]" --upgrade # Upgrade to the latest version with asyncio extras pip install "pinecone[asyncio]" --upgrade ``` ## Initialize Once installed, you can import the library and then use an [API key](/guides/projects/manage-api-keys) to initialize a client instance: ```Python HTTP theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` ```python gRPC theme={null} from pinecone.grpc import PineconeGRPC as Pinecone pc = Pinecone(api_key="YOUR_API_KEY") ``` When [creating an index](/guides/index-data/create-an-index), import the `ServerlessSpec` or `PodSpec` class as well: ```Python Serverless index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` ```Python Pod-based index theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import PodSpec pc = Pinecone(api_key="YOUR_API_KEY") pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=PodSpec( environment="us-west-1-gcp", pod_type="p1.x1", pods=1 ) ) ``` ## Proxy configuration If your network setup requires you to interact with Pinecone through a proxy, you will need to pass additional configuration using optional keyword parameters: * `proxy_url`: The location of your proxy. This could be an HTTP or HTTPS URL depending on your proxy setup. * `proxy_headers`: Accepts a python dictionary which can be used to pass any custom headers required by your proxy. If your proxy is protected by authentication, use this parameter to pass basic authentication headers with a digest of your username and password. The `make_headers` utility from `urllib3` can be used to help construct the dictionary. **Note:** Not supported with Asyncio. * `ssl_ca_certs`: By default, the client will perform SSL certificate verification using the CA bundle maintained by Mozilla in the [`certifi`](https://pypi.org/project/certifi/) package. If your proxy is using self-signed certicates, use this parameter to specify the path to the certificate (PEM format). * `ssl_verify`: SSL verification is enabled by default, but it is disabled when set to `False`. It is not recommened to go into production with SSL verification disabled. ```python HTTP theme={null} from pinecone import Pinecone import urllib3 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 import make_headers pc = Pinecone( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', proxy_headers=make_headers(proxy_basic_auth='username:password'), ssl_ca_certs='path/to/cert-bundle.pem' ) ``` ```python asyncio theme={null} import asyncio from pinecone import PineconeAsyncio async def main(): async with PineconeAsyncio( api_key="YOUR_API_KEY", proxy_url='https://your-proxy.com', ssl_ca_certs='path/to/cert-bundle.pem' ) as pc: # Do async things await pc.list_indexes() asyncio.run(main()) ``` ## Async requests Pinecone Python SDK versions 6.0.0 and later provide `async` methods for use with [asyncio](https://docs.python.org/3/library/asyncio.html). Asyncio support makes it possible to use Pinecone with modern async web frameworks such as [FastAPI](https://fastapi.tiangolo.com/), [Quart](https://quart.palletsprojects.com/en/latest/), and [Sanic](https://sanic.dev/en/), and should significantly increase the efficiency of running requests in parallel. Use the [`PineconeAsyncio`](https://sdk.pinecone.io/python/asyncio.html) class to create and manage indexes and the [`IndexAsyncio`](https://sdk.pinecone.io/python/asyncio.html#pinecone.db_data.IndexAsyncio) class to read and write index data. To ensure that sessions are properly closed, use the `async with` syntax when creating `PineconeAsyncio` and `IndexAsyncio` objects. ```python Manage indexes theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import PineconeAsyncio, ServerlessSpec async def main(): async with PineconeAsyncio(api_key="YOUR_API_KEY") as pc: if not await pc.has_index(index_name): desc = await pc.create_index( name="docs-example", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ), deletion_protection="disabled", tags={ "environment": "development" } ) asyncio.run(main()) ``` ```python Read and write index data theme={null} # pip install "pinecone[asyncio]" import asyncio from pinecone import Pinecone async def main(): pc = Pinecone(api_key="YOUR_API_KEY") async pc.IndexAsyncio(host="INDEX_HOST") as idx: await idx.upsert_records( namespace="example-namespace", records=[ { "id": "1", "title": "The Great Gatsby", "author": "F. Scott Fitzgerald", "description": "The story of the mysteriously wealthy Jay Gatsby and his love for the beautiful Daisy Buchanan.", "year": 1925, }, { "id": "2", "title": "To Kill a Mockingbird", "author": "Harper Lee", "description": "A young girl comes of age in the segregated American South and witnesses her father's courageous defense of an innocent black man.", "year": 1960, }, { "id": "3", "title": "1984", "author": "George Orwell", "description": "In a dystopian future, a totalitarian regime exercises absolute control through pervasive surveillance and propaganda.", "year": 1949, }, ] ) asyncio.run(main()) ``` ## Query across namespaces Each query is limited to a single [namespace](/guides/index-data/indexing-overview#namespaces). However, the Pinecone Python SDK provides a `query_namespaces` utility method to run a query in parallel across multiple namespaces in an index and then merge the result sets into a single ranked result set with the `top_k` most relevant results. The `query_namespaces` method accepts most of the same arguments as `query` with the addition of a required `namespaces` parameter. When using the Python SDK without gRPC extras, to get good performance, it is important to set values for the `pool_threads` and `connection_pool_maxsize` properties on the index client. The `pool_threads` setting is the number of threads available to execute requests, while `connection_pool_maxsize` is the number of cached http connections that will be held. Since these tasks are not computationally heavy and are mainly i/o bound, it should be okay to have a high ratio of threads to cpus. The combined results include the sum of all read unit usage used to perform the underlying queries for each namespace. ```python Python theme={null} from pinecone import Pinecone pc = Pinecone(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set these connection_pool_maxsize=50, # <-- make sure to set these ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` When using the Python SDK with gRPC extras, there is no need to set the `connection_pool_maxsize` because grpc makes efficient use of open connections by default. ```python Python theme={null} from pinecone.grpc import PineconeGRPC pc = PineconeGRPC(api_key="YOUR_API_KEY") index = pc.Index( name="docs-example", pool_threads=50, # <-- make sure to set this ) query_vec = [ 0.1, ...] # an embedding vector with same dimension as the index combined_results = index.query_namespaces( vector=query_vec, namespaces=['ns1', 'ns2', 'ns3', 'ns4'], metric="cosine", top_k=10, include_values=False, include_metadata=True, filter={"genre": { "$eq": "comedy" }}, show_progress=False, ) for scored_vec in combined_results.matches: print(scored_vec) print(combined_results.usage) ``` ## Upsert from a dataframe To quickly ingest data when using the [Python SDK](/reference/python-sdk), use the `upsert_from_dataframe` method. The method includes retry logic and`batch_size`, and is performant especially with Parquet file data sets. The following example upserts the `uora_all-MiniLM-L6-bm25` dataset as a dataframe. ```Python Python theme={null} from pinecone import Pinecone, ServerlessSpec from pinecone_datasets import list_datasets, load_dataset pc = Pinecone(api_key="API_KEY") dataset = load_dataset("quora_all-MiniLM-L6-bm25") pc.create_index( name="docs-example", dimension=384, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) # To get the unique host for an index, # see https://docs.pinecone.io/guides/manage-data/target-an-index index = pc.Index(host="INDEX_HOST") index.upsert_from_dataframe(dataset.drop(columns=["blob"])) ``` # Rust SDK Source: https://docs.pinecone.io/reference/rust-sdk The Rust SDK is in "alpha" and is under active development. The SDK should be considered unstable and should not be used in production. Before a 1.0 release, there are no guarantees of backward compatibility between minor versions. See the [Rust SDK README](https://github.com/pinecone-io/pinecone-rust-client/blob/main/README.md) for full installation instructions and usage examples. To make a feature request or report an issue, please [file an issue](https://github.com/pinecone-io/pinecone-rust-client/issues). ## Install To install the latest version of the [Rust SDK](https://github.com/pinecone-io/pinecone-rust-client), add a dependency to the current project: ```shell theme={null} cargo add pinecone-sdk ``` ## Initialize Once installed, you can import the SDK and then use an [API key](/guides/production/security-overview#api-keys) to initialize a client instance: ```rust Rust theme={null} use pinecone_sdk::pinecone::PineconeClientConfig; use pinecone_sdk::utils::errors::PineconeError; #[tokio::main] async fn main() -> Result<(), PineconeError> { let config = PineconeClientConfig { api_key: Some("YOUR_API_KEY".to_string()), ..Default::default() }; let pinecone = config.client()?; let indexes = pinecone.list_indexes().await?; println!("Indexes: {:?}", indexes); Ok(()) } ``` # Spark-Pinecone connector Source: https://docs.pinecone.io/reference/tools/pinecone-spark-connector Use the [`spark-pinecone` connector](https://github.com/pinecone-io/spark-pinecone/) to efficiently create, ingest, and update [vector embeddings](https://www.pinecone.io/learn/vector-embeddings/) at scale with [Databricks and Pinecone](/integrations/databricks). ## Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ## Batch upsert To batch upsert embeddings to Pinecone: ```python Python theme={null} from pyspark import SparkConf from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark spark = SparkSession.builder.getOrCreate() # Read the file and apply the schema df = spark.read \ .option("multiLine", value = True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("src/test/resources/sample.jsonl") # Show if the read was successful df.show() # Write the dataFrame to Pinecone in batches df.write \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .format("io.pinecone.spark.pinecone.Pinecone") \ .mode("append") \ .save() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" val sourceTag = "PINECONE_SOURCE_TAG" // Configure Spark to run locally with all available cores val conf = new SparkConf() .setMaster("local[*]") // Create a Spark session with the defined configuration val spark = SparkSession.builder().config(conf).getOrCreate() // Read the JSON file into a DataFrame, applying the COMMON_SCHEMA val df = spark.read .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("src/test/resources/sample.jsonl") // path to sample.jsonl // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> apiKey, PineconeOptions.PINECONE_INDEX_NAME_CONF -> indexName, PineconeOptions.PINECONE_SOURCE_TAG_CONF -> sourceTag ) // Show if the read was successful df.show(df.count().toInt) // Write the DataFrame to Pinecone using the defined options in batches df.write .options(pineconeOptions) .format("io.pinecone.spark.pinecone.Pinecone") .mode(SaveMode.Append) .save() } ``` For a guide on how to set up batch upserts, refer to the [Databricks integration page](/integrations/databricks#setup-guide). ## Stream upsert To stream upsert embeddings to Pinecone: ```python Python theme={null} from pyspark.sql import SparkSession from pyspark.sql.types import StructType, StructField, ArrayType, FloatType, StringType, LongType import os # Your API key and index name api_key = "PINECONE_API_KEY" index_name = "PINECONE_INDEX_NAME" source_tag = "PINECONE_SOURCE_TAG" COMMON_SCHEMA = StructType([ StructField("id", StringType(), False), StructField("namespace", StringType(), True), StructField("values", ArrayType(FloatType(), False), False), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) # Initialize Spark session spark = SparkSession.builder \ .appName("StreamUpsertExample") \ .config("spark.sql.shuffle.partitions", 3) \ .master("local") \ .getOrCreate() # Read the stream of JSON files, applying the schema from the input directory lines = spark.readStream \ .option("multiLine", True) \ .option("mode", "PERMISSIVE") \ .schema(COMMON_SCHEMA) \ .json("path/to/input/directory/") # Write the stream to Pinecone using the defined options upsert = lines.writeStream \ .format("io.pinecone.spark.pinecone.Pinecone") \ .option("pinecone.apiKey", api_key) \ .option("pinecone.indexName", index_name) \ .option("pinecone.sourceTag", source_tag) \ .option("checkpointLocation", "path/to/checkpoint/dir") \ .outputMode("append") \ .start() upsert.awaitTermination() ``` ```scala Scala theme={null} import io.pinecone.spark.pinecone.{COMMON_SCHEMA, PineconeOptions} import org.apache.spark.SparkConf import org.apache.spark.sql.{SaveMode, SparkSession} object MainApp extends App { // Your API key and index name val apiKey = "PINECONE_API_KEY" val indexName = "PINECONE_INDEX_NAME" // Create a Spark session val spark = SparkSession.builder() .appName("StreamUpsertExample") .config("spark.sql.shuffle.partitions", 3) .master("local") .getOrCreate() // Read the JSON files into a DataFrame, applying the COMMON_SCHEMA from input directory val lines = spark.readStream .option("multiLine", value = true) .option("mode", "PERMISSIVE") .schema(COMMON_SCHEMA) .json("path/to/input/directory/") // Define Pinecone options as a Map val pineconeOptions = Map( PineconeOptions.PINECONE_API_KEY_CONF -> System.getenv("PINECONE_API_KEY"), PineconeOptions.PINECONE_INDEX_NAME_CONF -> System.getenv("PINECONE_INDEX"), PineconeOptions.PINECONE_SOURCE_TAG_CONF -> System.getenv("PINECONE_SOURCE_TAG") ) // Write the stream to Pinecone using the defined options val upsert = lines .writeStream .format("io.pinecone.spark.pinecone.Pinecone") .options(pineconeOptions) .option("checkpointLocation", "path/to/checkpoint/dir") .outputMode("append") .start() upsert.awaitTermination() } ``` ## Learn more * [Spark-Pinecone connector setup guide](/integrations/databricks#setup-guide) * [GitHub](https://github.com/pinecone-io/spark-pinecone) # Notebooks Source: https://docs.pinecone.io/examples/notebooks export const UtilityExampleCard = ({title, text, link}) => { return

{title}

{text}

; }; export const ExampleCard = ({title, text, link, children, arrow, vectors, namespaces}) => { return

{title}

{text}

{children &&
{children}
} {arrow && } {(vectors || namespaces) &&
{vectors && {vectors} vectors} {namespaces && {namespaces} namespaces}
} ; }; export const Tag = ({text, icon}) => { return {icon && } {text} ; };

Search

Retrieval-augmented generation (RAG)

Miscellaneous

# Reference architectures Source: https://docs.pinecone.io/examples/reference-architectures
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 export const Tag = ({text, icon}) => { return {icon && } {text} ; }; export const UtilityExampleCard = ({title, text, link}) => { return

{title}

{text}

; }; export const ExampleCard = ({title, text, link, children, arrow, vectors, namespaces}) => { return

{title}

{text}

{children &&
{children}
} {arrow && } {(vectors || namespaces) &&
{vectors && {vectors} vectors} {namespaces && {namespaces} namespaces}
} ; };

More code examples

# AI Engine Source: https://docs.pinecone.io/integrations/ai-engine export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; AI Engine seamlessly connects WordPress with the world's leading AI models. Create intelligent chatbots, generate content, build AI forms, and automate tasks—all from your WordPress dashboard. With AI Engine, you can create a chatbot to assist your visitors, answer support questions, or guide users through your products and services. Need fresh content? AI Engine can write posts in your voice, help rewrite existing ones, or translate them naturally into other languages. It can also generate custom images for your articles, refine messy text, or just lend a hand when you're stuck. For developers and power users, AI Engine offers internal APIs, shortcode flexibility, and advanced features like function calling and real-time audio chat. You can build your own AI-powered tools, automate tasks, or even create AI-driven SaaS applications on top of WordPress. And with support for a wide range of providers — OpenAI, Anthropic, Google, Hugging Face, and more — you have full control over the models you want to use. Everything is designed to feel native to WordPress. Whether you're exploring ideas in the AI Playground, using Copilot to help in the editor, or letting an AI agent manage your content through MCP, AI Engine is built to grow with you — and shaped by real user feedback every step of the way. # Airbyte Source: https://docs.pinecone.io/integrations/airbyte export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Airbyte offers a platform for creating ETL pipelines without writing integration code. It supports integrations with hundreds of systems, including databases, data warehouses, and SaaS products. The Pinecone connector for Airbyte allows users to connect these systems directly into Pinecone. The connector fetches data from the connected source, embeds the data using an large language model (LLM), and then upserts it into Pinecone. From enhancing semantic search capabilities to building intelligent recommendation systems, the Pinecone Airbyte connector offers a versatile solution. By tapping into Airbyte's extensive array of source connectors, you can explore new ways to enrich your data-driven projects and achieve your specific goals. ## Related articles * [Data Sync and Search: Pinecone and Airbyte](https://www.pinecone.io/learn/series/airbyte/) * [Introduction to Airbyte and the Pinecone connector](https://www.pinecone.io/learn/series/airbyte/airbyte-and-pinecone-intro/) * [Postgres to Pinecone Syncing](https://www.pinecone.io/learn/series/airbyte/airbyte-postgres-to-pinecone/) # Amazon Bedrock Source: https://docs.pinecone.io/integrations/amazon-bedrock Pinecone as a Knowledge Base for Amazon Bedrock export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Users can now 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. The Pinecone vector database is a key component of the AI tech stack, helping companies solve one of the biggest challenges in deploying GenAI solutions — hallucinations — by allowing them to store, search, and find the most relevant and up-to-date information from company data and send that context to Large Language Models (LLMs) with every query. This workflow is called Retrieval Augmented Generation (RAG), and with Pinecone, it aids in providing relevant, accurate, and fast responses from search or GenAI applications to end users. With the release of Knowledge Bases for Amazon Bedrock, developers can integrate their enterprise data into Amazon Bedrock using Pinecone as the fully-managed vector database to build GenAI applications that are: * **Highly performant:** Speed through data in milliseconds. Leverage metadata filters and sparse-dense index support for top-notch relevance, ensuring quick, accurate, and grounded results across diverse search tasks. * **Cost effective at scale:** Start for free on the starter plan and seamlessly scale usage with transparent usage-based pricing. Add or remove resources to meet your desired capacity and performance, upwards of billions of embeddings. * **Enterprise ready:** Launch, use, and scale your AI solution without needing to maintain infrastructure, monitor services, or troubleshoot algorithms. Pinecone meets the security and operational requirements of enterprises. ## What are Agents for Amazon Bedrock? In Bedrock, users interact with **Agents** that are capable of combining the natural language interface of the supported LLMs with those 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 the Pinecone index is used to retrieve semantically relevant content upon the user's query to the agent. **Note:** the LLM used for embeddings may be different than the one used for the natural language generation. For example, you may choose to use Amazon Titan to generate embeddings and use Anthropic's Claude to generate natural language responses. Additionally, Agents for Amazon Bedrock may be configured to execute various actions in the context of responding to a user's query - but we won't get into this functionality in this post. ## What is a Knowledge Base 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 given a user's query. Overall, the Knowledge Base feature is a valuable tool for users who want to improve their AI models' performance. With Bedrock's LLMs and Pinecone, users can easily integrate their data from AWS storage solutions and enhance the accuracy and relevance of their AI models. In this post, we'll go through the steps required for creating a Knowledge Base for Amazon Bedrock as well as an agent that will retrieve information from the knowledge base. ## Setup guide The process of using a Bedrock knowledge base with Pinecone works as follows: Create an empty Pinecone index with an embedding model in mind. The index must be empty for Bedrock integration. Upload sample data to Amazon S3. Sync data with Bedrock to create embeddings saved in Pinecone. Use the knowledge base to reference the data saved in Pinecone. Agents can interact directly with the Bedrock knowledge base, which will retrieve the semantically relevant content. ### 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, as your index's dimensions will need to match the model's. For example, the AWS Titan Text Embeddings V2 model can use dimension sizes 1024, 384, and 256. After signing up to 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). Your index must have the same dimensions as the model you will 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 setting up your Pinecone index, you'll have to 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. 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 on the new secret you created and save the secret ARN for a later step. #### Set up S3 The knowledge base is going to draw on data saved in S3. For this example, we use a [sample of research papers](https://huggingface.co/datasets/jamescalam/ai-arxiv2-semantic-chunks) obtained from a dataset. This data will be embedded and then saved in Pinecone. 1. Create a new general purpose bucket in [Amazon S3](https://console.aws.amazon.com/s3/home). 2. Once the bucket is created, upload a CSV file. 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 do not want to use the default chunking strategy, select a chunking strategy. 6. Click **Next**. ### 4. Connect Pinecone to the knowledge base Now you will need to 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. Mark the check box for authorizing AWS to access your Pinecone index. Ensure your Pinecone index is empty before proceeding. Bedrock cannot 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 will be used for metadata managed by Bedrock (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. Sync the data source whenever you add new data to the data source to start the ingestion workflow of converting your Amazon S3 data into vector embeddings and upserting the embeddings into the vector database. Depending on the amount of data, this whole workflow 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 an **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 will 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 is using the knowledge base. 9. Click **Save and exit**. Your agent is now set up and ready to go! In the next section, we'll show how to interact with the newly created agent. #### Create an alias for your agent In order to deploy the agent, create an alias for it that points to a specific version of the agent. Once the alias is created, it will display 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, use the playground on the right of the screen when we open the agent. In this example, we used a dataset of research papers for our source data. We can ask a question about those papers and retrieve a detailed response, this time with the deployed version. By inspecting the trace, we can see what chunks were used by the Agent and diagnose issues with responses. ## Related articles * [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 export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Amazon SageMaker is a fully managed service that brings together a broad set of tools to enable high-performance, low-cost machine learning (ML) for any use case. With SageMaker, you can build, train and deploy ML models at scale-- all 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. Amazon SageMaker and Pinecone can be used together for high-performance, scalable, and reliable retrieval augmented generation (RAG) use cases. The integration uses Amazon SageMaker to compute and host models for 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. ## Related articles * [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 export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; [Apify](https://apify.com) is a web scraping and data extraction platform. It provides an app store with more than a thousand ready-made cloud tools called Actors. These tools are suitable for use cases including extracting structured data from e-commerce sites, social media, search engines, online maps, or any other website. For example, the [Website Content Crawler](https://apify.com/apify/website-content-crawler) Actor can deeply crawl websites, clean their HTML by removing a cookies modal, footer, or navigation, and then transform the HTML into Markdown. This Markdown can then be used as training data for AI models or to feed LLM and generative AI applications with web content. The Apify integration for Pinecone makes it easy to transfer results from Actors to the Pinecone vector database, enabling Retrieval-Augmented Generation (RAG) or semantic search over data extracted from the web. # Aryn Source: https://docs.pinecone.io/integrations/aryn export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Aryn is an AI-powered ETL system for complex, unstructured documents like PDFs, HTML, presentations, and more. It's purpose-built for building RAG and GenAI applications, providing up to 6x better accuracy in chunking and extracting information from documents. This can lead to 30% better recall and 2x improvement in answer accuracy for real-world use cases. Aryn's ETL system has two components: Sycamore and the Aryn Partitioning Service. Sycamore is Aryn's open source document processing engine, available as a Python library. It contains a set of transforms for information extraction, LLM-powered enrichment, data cleaning, creating vector embeddings, and loading Pinecone indexes. The Aryn Partitioning Service is used as a first step in a Sycamore data processing pipeline, and it identifies and extracts parts of documents, like text, tables, images, and more. It uses a state-of-the-art vision segmentation AI model, trained on hundreds of thousands of human-annotated documents. The Pinecone integration with Aryn enables developers to easily chunk documents, create vector embeddings, and load Pinecone with high-quality data. # Box Source: https://docs.pinecone.io/integrations/box export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Connect a [Box](https://www.box.com/) account to a Pinecone vector database. This integration allows embeddings generation based on content stored in a particular account and folder in Box. By default, the Pinecone Inference API is used, as well as OpenAI for the LLM. The integration can be used within a larger AI agent or workflow. # Confluent Source: https://docs.pinecone.io/integrations/confluent export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Confluent allows you to connect and process all of your data in real time with a cloud-native and complete data streaming platform available everywhere you need it. Confluent's Kafka Connect is a tool for scalably and reliably streaming data between Apache Kafka and other data systems. It makes it simple to quickly define connectors that move large data sets in and out of Kafka. Use the Pinecone Sink Connector, a Kafka Connect plugin for Pinecone, to take content from Confluent Cloud, convert it into vector embeddings using large language models (LLMs), and then store these embeddings in a Pinecone vector database. # Databricks Source: https://docs.pinecone.io/integrations/databricks Using Databricks and Pinecone to create and index vector embeddings at scale export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Databricks is a Unified Analytics Platform on top of Apache Spark. The primary advantage of using Spark is its ability to distribute workloads across a cluster of machines. By adding more machines or increasing the number of cores on each machine, it is easy to horizontally scale a cluster to handle computationally intensive tasks like vector embedding, where parallelization can save many hours of precious computation time and resources. Leveraging GPUs with Spark can produce even better results — enjoying the benefits of the fast computation of a GPU combined with parallelization will ensure optimal performance. Efficiently create, ingest, and update vector embeddings at scale with Databricks and Pinecone. ## Setup guide In this guide, you'll create embeddings based on the [sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model from [Hugging Face](https://huggingface.co/), but the approach demonstrated here should work with any other model and dataset. ### Before you begin Ensure you have the following: * A [Databricks cluster](https://docs.databricks.com/en/compute/configure.html) * A [Pinecone account](https://app.pinecone.io/) * A [Pinecone API key](/guides/projects/understanding-projects#api-keys) ### 1. Install the Spark-Pinecone connector 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` Databricks platform users must use the Pinecone assembly jar listed above to ensure that the proper dependecies are installed. 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. Select **File path/S3** as the **Library Source**. 2. Enter the S3 URI for the Pinecone assembly JAR file: ``` s3://pinecone-jars/1.1.0/spark-pinecone-uberjar.jar ``` 3. Click **Install**. 1. [Install the Spark-Pinecone connector as a library](https://docs.databricks.com/en/libraries/cluster-libraries.html#install-a-library-on-a-cluster). 2. Configure the library as follows: 1. [Download the Pinecone assembly JAR file](https://repo1.maven.org/maven2/io/pinecone/spark-pinecone_2.12/1.1.0/). 2. Select **Workspace** as the **Library Source**. 3. Upload the JAR file. 4. Click **Install**. ### 2. Load the dataset into partitions As your example dataset, use a collection of news articles from Hugging Face's datasets library: 1. [Create a new notebook](https://docs.databricks.com/en/notebooks/notebooks-manage.html#create-a-notebook) attached to your cluster. 2. Install dependencies: ``` pip install datasets transformers pinecone torch ``` 3. Load the dataset: ```Python Python theme={null} from datasets import list_datasets, load_dataset dataset_name = "allenai/multinews_sparse_max" dataset = load_dataset(dataset_name, split="train") ``` 4. Convert the dataset from the Hugging Face format and repartition it: ```Python Python theme={null} dataset.to_parquet("/dbfs/tmp/dataset_parquet.pq") num_workers = 10 dataset_df = spark.read.parquet("/tmp/dataset_parquet.pq").repartition(num_workers) ``` Once the repartition is complete, you get back a DataFrame, which is a distributed collection of the data organized into named columns. It is conceptually equivalent to a table in a relational database or a dataframe in R/Python, but with richer optimizations under the hood. As mentioned above, each partition in the dataframe has an equal amount of the original data. 5. The dataset doesn't have identifiers associated with each document, so add them: ```Python Python theme={null} from pyspark.sql.types import StringType from pyspark.sql.functions import monotonically_increasing_id dataset_df = dataset_df.withColumn("id", monotonically_increasing_id().cast(StringType())) ``` As its name suggests, `withColumn` adds a column to the dataframe, containing a simple increasing identifier that you cast to a string. ### 3. Create the vector embeddings 1. Create a UDF (User-Defined Function) to create the embeddings, using the AutoTokenizer and AutoModel classes from the Hugging Face transformers library: ```Python Python theme={null} from transformers import AutoTokenizer, AutoModel def create_embeddings(partitionData): tokenizer = AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") model = AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2") for row in partitionData: document = str(row.document) inputs = tokenizer(document, padding=True, truncation=True, return_tensors="pt", max_length=512) result = model(**inputs) embeddings = result.last_hidden_state[:, 0, :].cpu().detach().numpy() lst = embeddings.flatten().tolist() yield [row.id, lst, "", "{}", None] ``` 2. Apply the UDF to the data: ```Python Python theme={null} embeddings = dataset_df.rdd.mapPartitions(create_embeddings) ``` A dataframe in Spark is a higher-level abstraction built on top of a more fundamental building block called a resilient distributed dataset (RDD). Here, you use the `mapPartitions` function, which provides finer control over the execution of the UDF by explicitly applying it to each partition of the RDD. 3. Convert the resulting RDD back into a dataframe with the schema required by Pinecone: ```Python Python theme={null} from pyspark.sql.types import StructType, StructField, StringType, ArrayType, FloatType, IntegerType schema = StructType([ StructField("id",StringType(),True), StructField("values",ArrayType(FloatType()),True), StructField("namespace",StringType(),True), StructField("metadata", StringType(), True), StructField("sparse_values", StructType([ StructField("indices", ArrayType(LongType(), False), False), StructField("values", ArrayType(FloatType(), False), False) ]), True) ]) embeddings_df = spark.createDataFrame(data=embeddings,schema=schema) ``` ### 4. Save the embeddings in Pinecone 1. Initialize the connection to Pinecone: ```Python Python theme={null} from pinecone.grpc import PineconeGRPC as Pinecone from pinecone import ServerlessSpec pc = Pinecone(api_key="YOUR_API_KEY") ``` 2. Create an index for your embeddings: ```Python Python theme={null} pc.create_index( name="news", dimension=1536, metric="cosine", spec=ServerlessSpec( cloud="aws", region="us-east-1" ) ) ``` 3. Use the Spark-Pinecone connector to save the embeddings to your index: ```Python Python theme={null} ( embeddings_df.write .option("pinecone.apiKey", api_key) .option("pinecone.indexName", index_name) .format("io.pinecone.spark.pinecone.Pinecone") .mode("append") .save() ) ``` The process of writing the embeddings to Pinecone should take approximately 15 seconds. When it completes, you'll see the following: ``` spark: org.apache.spark.sql.SparkSession = org.apache.spark.sql.SparkSession@41638051 pineconeOptions: scala.collection.immutable.Map[String,String] = Map(pinecone.apiKey ->, pinecone.indexName -> "news") ``` This means the process was completed successfully and the embeddings have been stored in Pinecone. 4. Perform a similarity search using the embeddings you loaded into Pinecone by providing a set of vector values or a vector ID. The [query endpoint](/reference/api/2025-10/data-plane/query) will return the IDs of the most similar records in the index, along with their similarity scores: ```Python Python theme={null} index.query( namespace="example-namespace", vector=[0.3, 0.3, 0.3, 0.3, ... 0.3], top_k=3, include_values=True ) ``` If you want to make a query with a text string (e.g., `"Summarize this article"`), use the [`search` endpoint via integrated inference](/reference/api/2025-10/data-plane/search_records). # Datavolo Source: https://docs.pinecone.io/integrations/datavolo export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; [Datavolo](https://datavolo.io/) helps data teams build multimodal data pipelines to support their AI initiatives. Every organization has their own private data that they need to incorporate into their AI apps, and a predominant pattern to do so has emerged: retrieval augmented generation (RAG). Datavolo sources, transforms, and enriches data in a continuous, composable and customizable manner, landing the data in Pinecone for retrieval. This ensures organizations can securely access their unstructured data. # Estuary Source: https://docs.pinecone.io/integrations/estuary export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; [Estuary](https://estuary.dev/) builds real-time data pipelines that focus on moving data from sources to destinations with millisecond latency. It supports integrations with hundreds of systems including databases, warehouses, SaaS products and streaming solutions. The Pinecone connector for Estuary enables users to source from these systems and push data to Pinecone, for an always up-to-date view. It incrementally updates source data to ensure that minimal credits are used when reaching out to get embeddings from providers prior to pushing them to Pinecone. Estuary's Pinecone connector enables a variety of use cases like enabling LLM-based search across your organizations data and building intelligent recommendation systems. It can be set up in 5 minutes, without any engineering effort to maximize efficiency. # Fleak Source: https://docs.pinecone.io/integrations/fleak export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Fleak simplifies the process of building, deploying, and managing data workflows. As a low-code platform, Fleak lets users create and deploy complex workflows using SQL and pre-configured processing nodes. The platform facilitates seamless data processing, microservice interactions, and the inference of large language models (LLMs) within a single, intuitive environment. Fleak makes advanced technology accessible and manageable for Pinecone users without requiring extensive coding hours or infrastructure knowledge. The platform provides serverless, autoscaling HTTP API endpoints, ensuring that workflows are robust, reliable, and scalable to meet the complex data needs of enterprises. This setup allows businesses to automate and enhance their operations, driving productivity and innovation through powerful, user-friendly tools. By integrating Pinecone into Fleak's platform, users can access and leverage their vector data to enrich their workflows without additional engineering overhead, enabling seamless data-driven decision-making, advanced analytics, and the integration of AI-driven insights. # FlowiseAI Source: https://docs.pinecone.io/integrations/flowise export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Flowise is a low-code LLM apps development platform. It supports integrations with dozens of systems, including databases and chat models. The Pinecone integration with Flowise allows users to build RAG apps, including upserting and querying documents. # Gathr Source: https://docs.pinecone.io/integrations/gathr export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; [Gathr](https://www.gathr.one/) is the world's first and only "data to outcome" platform. Leading enterprises use Gathr to build and operationalize data and AI-driven solutions at scale. Gathr unifies data engineering, machine learning, generative AI, actionable analytics, and process automation on a single platform. With Gen AI capabilities and no-code rapid application development, Gathr significantly boosts productivity for all. The unified experience fosters seamless handoff and collaboration between teams, accelerating the journey from prototype to production. Users have achieved success with Gathr, from ingesting petabyte-scale data in real time to orchestrating thousands of complex data processing pipelines in months and delivering actionable insights and xOps solutions to multiply business impact. Additionally, Gathr helps enterprises architect Gen AI solutions for use cases like document summarization, sentiment analysis, next best action, insider threat detection, predictive maintenance, custom chatbots, and more. Gathr Gen AI Fabric is designed to build enterprise-grade Gen AI solutions end-to-end on a unified platform. It offers production-ready building blocks for creating Gen AI solutions, out-of-the-box Gen AI solution templates, and GathrIQ, a data-to-outcome copilot. One of the building blocks is integration with Vector DB and Knowledge Graphs. Gathr supports reading and writing from Pinecone using a built-in, ready-to-use connector to support use cases requiring knowledge graphs. # Matillion Source: https://docs.pinecone.io/integrations/matillion export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; [Matillion Data Productivity Cloud](https://www.matillion.com/) is a unified platform that helps your team move faster with one central place to build and manage graphical, low-code data pipelines. It allows data teams to use structured, semi-structured, and unstructured data in analytics; build AI pipelines for new use cases; and be more productive. Matillion Data Productivity Cloud and Pinecone can be used together for retrieval augmented generation (RAG) use cases, helping to contextualize business insights without code. Matillion supports 150+ pre-built data source connectors, as well as the ability to build custom connectors to any REST API source system, making it easy to chunk unstructured datasets, create embeddings, and upsert to Pinecone. Matillion's graphical AI Prompt Components integrate with large language models (LLM) running in OpenAI, Amazon Bedrock, Azure OpenAI, and Snowpark Container Services. They enable no-code lookup of external knowledge stored in Pinecone, enabling data engineers to enrich GenAI answers with contextualized and proprietary data. ## Additional 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) # Nexla Source: https://docs.pinecone.io/integrations/nexla export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Nexla is a Data + AI Integration Platform that makes it easy for users to build data pipelines in a no-code/low-code manner. The Pinecone integration with Nexla makes it easy for enterprise users to ingest data from systems like Sharepoint, OneDrive, Cloud Storage, Data Warehouses, and 500+ other connectors that Nexla supports natively. # Integrations Source: https://docs.pinecone.io/integrations/overview Pinecone integrations enable you to build and deploy AI applications faster and more efficiently. Integrate Pinecone with your favorite frameworks, data sources, and infrastructure providers. export const OpenAIIcon = () => ; export const SagemakerIcon = () => ; export const BedrockIcon = () => ;
Frameworks

AI Engine

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

Airbyte

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

Amazon Bedrock

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

Amazon Sagemaker

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

Anyscale

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

Apify

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

Aryn

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

AWS Marketplace

Access Pinecone through our AWS Marketplace listing.
Data Sources

Box

Connect a Box account to a Pinecone vector database.
Frameworks

Cloudera AI

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

Cohere

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

Confluent

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

Context Data

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

Databricks

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

Datadog

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

Datavolo

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

Estuary

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

FlowiseAI

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

Fleak

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

Gathr

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

Google Cloud Marketplace

Access Pinecone through our Google Cloud Marketplace listing.
Frameworks

Genkit

Build AI powered applications and agents.
Infrastructure

GitHub Copilot

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

Haystack

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

HoneyHive

Clearly visualize your execution traces and spans.
Frameworks

Hugging Face

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

Instill AI

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

Jina

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

LangChain

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

Langtrace

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

Llama Index

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

Matillion

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

Microsoft Marketplace

Access Pinecone through our Microsoft Marketplace listing.
Observability

New Relic

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

Nexla

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

Nuclia

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

OctoAI

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

OpenAI

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

Pulumi

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

Redpanda

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

Snowflake

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

StreamNative

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

Terraform

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

Traceloop

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

TruLens

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

Twelve Labs

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

Unstructured

Load data into Pinecone with a single click.
Infrastructure

Vercel

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

VoltAgent

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

Voyage AI

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

Zapier

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

 # Redpanda Source: https://docs.pinecone.io/integrations/redpanda export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Redpanda Connect is a declarative data streaming service that solves a wide range of data engineering problems with simple, chained, stateless processing steps. It implements transaction based resiliency with back pressure, so when connecting to at-least-once sources and sinks, it's able to guarantee at-least-once delivery without needing to persist messages during transit. It's simple to deploy, comes with a wide range of connectors, and is totally data agnostic, making it easy to drop into your existing infrastructure. Redpanda Connect has functionality that overlaps with integration frameworks, log aggregators and ETL workflow engines, and can therefore be used to complement these traditional data engineering tools or act as a simpler alternative. The Pinecone connector for Redpanda provides a production-ready integration from many existing data sources, all in a few lines of YAML. # Snowflake Source: https://docs.pinecone.io/integrations/snowflake export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Deploy and run Pinecone with Snowpark Container Services. Snowpark Container Services is a fully managed container offering designed to facilitate the deployment, management, and scaling of containerized applications within the Snowflake ecosystem. This service enables users to run containerized workloads directly within Snowflake, ensuring that data does't need to be moved out of the Snowflake environment for processing. Unlike traditional container orchestration platforms like Docker or Kubernetes, Snowpark Container Services offers an OCI runtime execution environment specifically optimized for Snowflake. This integration allows for the seamless execution of OCI images, leveraging Snowflak's robust data platform. ## Related articles * [Snowpark Container Services: Securely Deploy and run Sophisticated Generative AI and full-stack apps in Snowflake](https://www.snowflake.com/blog/snowpark-container-services-deploy-genai-full-stack-apps/) # StreamNative Source: https://docs.pinecone.io/integrations/streamnative export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Founded by the original developers of Apache Pulsar and Apache BookKeeper, [StreamNative](https://streamnative.io) provides StreamNative Cloud, offering Apache Pulsar as a Service. The company also supports on-premise Pulsar deployments and related commercial support. StreamNative Cloud provides a scalable, resilient, and secure messaging and event streaming platform for enterprises. Additionally, StreamNative offers Kafka compatibility, enabling seamless integration with existing Kafka-based systems. The Pinecone integration with StreamNative allows access to pinecone.io with a Pulsar topic. The sink connector takes in messages and writes them if they are in a proper format to a Pinecone index. # Unstructured Source: https://docs.pinecone.io/integrations/unstructured export const PrimarySecondaryCTA = ({primaryLabel, primaryHref, primaryTarget, secondaryLabel, secondaryHref, secondaryTarget}) =>
{primaryLabel && primaryHref && } {secondaryLabel && secondaryHref && }
; Unstructured builds ETL tools for LLMs, including an open source Python library, a SaaS API, and an ETL platform. Unstructured extracts content and metadata from 25+ document types, including PDFs, Word documents and PowerPoints. After extracting content and metadata, Unstructured performs additional 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. Integrating Pinecone with Unstructured enables developers to load data from an source or document type into Pinecone with a single click, accelerating the building of LLM apps that connect to organizational data. # Model Gallery Source: https://docs.pinecone.io/models/overview Pinecone integrations enable you to build and deploy AI applications faster and more efficiently. Integrate Pinecone with your favorite frameworks, data sources, and infrastructure providers. export const ModelCard = ({logoSrc, company, modelName, description, task, modality, maxInputTokens, price, buttonLabel, buttonHref, buttonTarget, inferenceAPI, isPreviewCard, logoInvert}) => { const handleButtonClick = () => { if (inferenceAPI) { if (buttonTarget === "_blank") { window.open(buttonHref, buttonTarget); } else { window.location.href = buttonHref; } } else {} }; return
{`${company}

{modelName}

{company.toUpperCase()}

{description}

Task

{task}

Modality

{modality}

Max Input Tokens

{maxInputTokens}

Price

{price}

{isPreviewCard &&
Preview
}
; };
Inference

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

Request a model
{ const carousel = e.target; const prevButton = document.getElementById('prevButton'); const nextButton = document.getElementById('nextButton'); if (!prevButton || !nextButton) return; // Guard against null elements // Check if we're at the start or end const isAtStart = carousel.scrollLeft === 0; const isAtEnd = Math.abs(carousel.scrollLeft + carousel.offsetWidth - carousel.scrollWidth) < 1; // Update button visibility prevButton.style.visibility = isAtStart ? 'hidden' : 'visible'; nextButton.style.visibility = isAtEnd ? 'hidden' : 'visible'; }} >
{" "}