Convert a starter index to serverless

This page shows you how to convert a pod-based starter index to a serverless index.

Serverless indexes are in public preview and are available only on AWS in the us-west-2 and us-east-1 regions. Check the current limitations and test thoroughly before using it in production.

Before you begin

• Make sure your starter index is in the gcp-starter environment. Starter indexes in other environments cannot be converted to serverless at this time.

• Serverless indexes are available on the Standard and Enterprise plans. If your starter index is in an organization on the Starter plan, you must upgrade the organization before the index can be converted.

  During upgrade, you will enter a payment method. However, note that upgrading comes with $100 in serverless credits, which will cover the cost of your converted index for some time. Once those credits have been used, you’ll start paying only based on the amount of data stored and operations performed. Since your index will be serverless, you won’t need to worry about scaling up to meet demand or scaling down to avoid paying for unused resources. Instead, your index will automically scale based on your usage.

  For more details about how costs are calculated for serverless indexes, see Understanding cost.

Step 1. Pause traffic to the index

Converting your index to serverless takes less than 5 minutes. During that time, upsert and update requests will fail, so it’s recommended to pause client traffic to the index before starting conversion.

Step 2. Update clients and code

If you are using an older version of the Python or Node.js client, you must update the client to work with serverless indexes and make minor changes to your code.

1. Check your client version:

   Shell

   # For the Python client:  
   pip show pinecone-client  
   # For the Node.js client:  
   npm list | grep @pinecone-database/pinecone  
   

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

   Python

   pip install pinecone-client --upgrade  
   

3. In your code, make the following changes:

   • Change how you import the Pinecone library:

     Python

     from pinecone import Pinecone, ServerlessSpec, PodSpec  
     # ServerlessSpec and PodSpec are required only when  
     # creating serverless and pod-based indexes.  
     

   • Change how you authenticate and initialize the client:

     Python

     pc = Pinecone(api_key="YOUR_API_KEY")  
     

Depending on your usage of the client, there may be other changes to make. For a comprehensive list, see the Python client v3 migration guide or Node.js client v2 migration guide.

Step 3. Convert the index

In the Pinecone console, go to your starter index and click Convert to serverless.

The process takes less than 5 minutes and does not involve creating or deleting any indexes; instead, your starter index is transformed into a serverless index and moved to the us-west-2 region of the AWS cloud.

Step 4. Reinitialize clients

Once your index has been converted to serverless, your index will have a new DNS endpoint.

• If you are using Pinecone clients, reinitialize them so they pick up the new index endpoint.

• If you are using the REST API directly, get the new index endpoint and use it in all data plane requests:

  Shell

  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"