Migrate a pod-based index to serverless

This page shows you how to migrate a pod-based index to serverless. The migration process is free; the standard costs of upserting records to a new serverless index aren't applied.

Migration is supported for pod-based indexes with up to 500 million records and 20,000 namespaces across all supported clouds (AWS, GCP, and Azure). If your index has more than 500 million records, contact Pinecone Support before you migrate.

After you migrate, note that serverless indexes don't support the following features:

• Selective metadata indexing

  • Because high-cardinality metadata in serverless indexes doesn't cause high memory utilization, this operation isn't relevant.

• Filtering index statistics by metadata

If you were using either feature with your pod-based index, you'll need to adapt your code. If you're blocked by these limitations, contact Pinecone Support.

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.

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 for help estimating and managing cost implications.

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, updates, and deletes to the pod-based index won't automatically be reflected in the new serverless index, so be sure to prepare in one of the following ways:

• Pause write traffic: If downtime is acceptable, pause traffic to the pod-based index before starting migration. After migration, you will start sending traffic to the serverless index.

• Log your writes: If you need to continue reading from the pod-based index during migration, send read traffic to the pod-based index, but log your writes to a temporary location outside of Pinecone (e.g., S3). After migration, you will replay the logged writes to the new serverless index and start sending all traffic to the serverless index.

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:

   • Python
   • JavaScript
   • Java
   • Go

   pip show pinecone  

   npm list | grep @pinecone-database/pinecone  

   # Check your dependency file or classpath

   go list -u -m all | grep go-pinecone

2. If your SDK version is less than 3.0.0 for Python, 2.0.0 for Node.js, 1.0.0 for Java, or 1.0.0 for Go, upgrade the SDK as follows:

   • Python
   • JavaScript
   • Java
   • Go

   pip install "pinecone[grpc]" --upgrade  

   npm install @pinecone-database/pinecone@latest  

   # Maven
   <dependency>
     <groupId>io.pinecone</groupId>
     <artifactId>pinecone-client</artifactId>
     <version>5.0.0</version>
   </dependency>
   
   # Gradle
   implementation "io.pinecone:pinecone-client:5.0.0"

   go get -u github.com/pinecone-io/go-pinecone/v4/pinecone@latest

You must make some minor code changes to work with serverless indexes.

1. Change how you import the Pinecone library and authenticate and initialize the client:

   • Python
   • JavaScript
   • Java
   • Go

   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")  

   import { Pinecone } from '@pinecone-database/pinecone';  
   
   const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

   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();
       }
   }

   package main
   
   import (
       "context"
       "log"
   
       "github.com/pinecone-io/go-pinecone/v4/pinecone"
   )
   
   func main() {
       ctx := context.Background()
   
       pc, err := pinecone.NewClient(pinecone.NewClientParams{
           ApiKey: "YOUR_API_KEY",
       })
       if err != nil {
           log.Fatalf("Failed to create Client: %v", err)
       }
   }

2. Listing indexes 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
   • JavaScript
   • Java
   • Go
   • curl

   from pinecone.grpc import PineconeGRPC as Pinecone
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   index_list = pc.list_indexes()
   
   print(index_list)

   import { Pinecone } from '@pinecone-database/pinecone'
   
   const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' })
   
   const indexList = await pc.listIndexes();
   
   console.log(indexList);

   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);
       }
   }

   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))
           }
       }
   }

   PINECONE_API_KEY="YOUR_API_KEY"
   
   curl -i -X GET "https://api.pinecone.io/indexes" \
   -H "Api-Key: $PINECONE_API_KEY" \
   -H "X-Pinecone-Api-Version: 2026-07"

   The list_indexes operation now returns a response like the following:

   • Python
   • JavaScript
   • Java
   • Go
   • curl

   [{
       "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"
       }
   }]

   {
     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'
       }
     ]
   }

   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
   }

   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"
     }
   }

   {
     "indexes": [
       {
         "name": "docs-example-sparse",
         "host": "docs-example-sparse-govk0nt.svc.aped-4627-b74a.pinecone.io",
         "status": {
           "ready": true,
           "state": "Ready"
         },
         "deployment": {
           "deployment_type": "managed",
           "region": "us-east-1",
           "cloud": "aws",
           "environment": "aped-4627-b74a"
         },
         "read_capacity": {
           "mode": "OnDemand",
           "status": {
             "state": "Ready",
             "current_shards": null,
             "current_replicas": null
           }
         },
         "schema": {
           "fields": {
             "sparse_embedding": {
               "type": "sparse_vector",
               "description": null
             }
           }
         },
         "tags": {
           "environment": "development"
         },
         "deletion_protection": "disabled"
       },
       {
         "name": "docs-example-dense",
         "host": "docs-example-dense-govk0nt.svc.aped-4627-b74a.pinecone.io",
         "status": {
           "ready": true,
           "state": "Ready"
         },
         "deployment": {
           "deployment_type": "managed",
           "region": "us-east-1",
           "cloud": "aws",
           "environment": "aped-4627-b74a"
         },
         "read_capacity": {
           "mode": "OnDemand",
           "status": {
             "state": "Ready",
             "current_shards": null,
             "current_replicas": null
           }
         },
         "schema": {
           "fields": {
             "chunk_text": {
               "type": "string",
               "description": null,
               "full_text_search": {
                 "language": "en",
                 "stemming": false,
                 "stop_words": false
               }
             },
             "embedding": {
               "type": "dense_vector",
               "description": null,
               "dimension": 1536,
               "metric": "cosine"
             }
           }
         },
         "tags": {
           "environment": "development"
         },
         "deletion_protection": "disabled"
       }
     ]
   }

3. Describing an index 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
   • JavaScript
   • Java
   • Go
   • curl

   from pinecone.grpc import PineconeGRPC as Pinecone
   
   pc = Pinecone(api_key="YOUR_API_KEY")
   
   pc.describe_index(name="docs-example")

   import { Pinecone } from '@pinecone-database/pinecone';
   
   const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
   
   await pc.describeIndex('docs-example');

   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);
       }
   }

   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))
       }
   }

   PINECONE_API_KEY="YOUR_API_KEY"
   
   curl -i -X GET "https://api.pinecone.io/indexes/docs-example" \
       -H "Api-Key: $PINECONE_API_KEY" \
       -H "X-Pinecone-Api-Version: 2026-07"

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
   • JavaScript
   • Java
   • Go
   • curl

   index = pc.Index("YOUR_SERVERLESS_INDEX_NAME")  

   const index = pc.index("YOUR_SERVERLESS_INDEX_NAME");

   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");

   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)
       }
   }

   # 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 to avoid paying for unused resources.

• Limits
• Serverless architecture
• Understanding serverless cost