This page shows you how to convert a free starter index in the gcp-starter environment to a serverless index.

Before you begin

Make sure your starter index is in the gcp-starter environment. If your starter index is in another environment, see Migrate a legacy starter index to serverless.

1. Pause traffic to the index

Converting your index to serverless can take up to 30 minutes. During that time, writes to the gcp-starter index will not be reflected in the new serverless index, so it’s recommended to pause client traffic to the gcp-starter index before starting conversion.

2. Update clients

If you are using an older version of the Python, Node.js, or Java client, you must update the client to work with serverless indexes.

  1. Check your client version:

    pip show pinecone-client  
    
  2. If your client version is less than 3.0.0 for Python, 2.0.0 for Node.js, or 1.0.0 for Java, upgrade the client as follows:

    pip install pinecone-client --upgrade  
    

3. Adapt existing code

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:

    from pinecone import Pinecone, ServerlessSpec, PodSpec  
    # ServerlessSpec and PodSpec are required only when  
    # creating serverless and pod-based indexes.  
    pc = Pinecone(api_key="YOUR_API_KEY")  
    
  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.

    from pinecone import Pinecone
    
    pc = Pinecone(api_key="YOUR_API_KEY")
    
    pc.list_indexes()
    
    # Response:
    # {'indexes': [{'dimension': 1536,
    #               'host': 'serverless-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
    #               'metric': 'cosine',
    #               'name': 'serverless-index',
    #               'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
    #               'status': {'ready': True, 'state': 'Ready'}},
    #              {'dimension': 1536,
    #               'host': 'pod-index-4zo0ijk.svc.us-west2-aws.pinecone.io',
    #               'metric': 'cosine',
    #               'name': 'pod-index',
    #               'spec': {'pod': {'environment': 'us-west2-aws',
    #                                'pod_type': 'p1.x1',
    #                                'pods': 1,
    #                                'replicas': 1,
    #                                'shards': 1}},
    #               'status': {'ready': True, 'state': 'Ready'}}]}
    
  3. Describing an index now returns a description of an index in a different format. It also returns the index endpoint 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.

    from pinecone import Pinecone
    
    pc = Pinecone(api_key="YOUR_API_KEY")
    
    pc.describe_index("serverless-index")
    
    # Response:
    # {'dimension': 1536,
    #  'host': 'serverless-index-4zo0ijk.svc.us-weset2-aws.pinecone.io',
    #  'metric': 'cosine',
    #  'name': 'serverless-index',
    #  'spec': {'serverless': {'cloud': 'aws', 'region': 'us-east-1'}},
    #  'status': {'ready': True, 'state': 'Ready'}}
    
  4. Serverless indexes do not support the following features. If you were relying on these features for your legacy starter index, you’ll need to adapt your code.

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, Node.js client v2 migration guide, or Java client v1 migration guide.

4. 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, this process transforms your starter index into a serverless index and moves it to the us-east-1 region of the AWS cloud.

5. 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"  
    

See also

Was this page helpful?