This page shows you how to save a legacy starter index as a collection and then create a new serverless index from that collection.

Legacy starter indexes that have not been migrated to serverless by May 31st, 2024 will be auto-saved as collections and then deleted.

Before you begin

  • If your starter index is in the gcp-starter environment, see Convert a gcp-starter index to serverless instead.

  • On the free Starter plan, you can store no more than 2 GB of data across all of your serverless indexes, and each serverless index can have no more than 100 namespaces.

    After migrating your legacy starter index, if you are over the 2 GB storage limit, you will not be able to make any more upserts and updates, and if your new serverless index has more than 100 namespaces, you will not be able to add more namespaces to the index.

    • If you know you will have more than 2 GB of data after migration, delete records ahead of time to avoid service interruptions. Alternatively, migrate your index and then upgrade your plan.
    • If your legacy starter index has more than 100 namespaces, and you know you will need to add more namespaces in the future, migrate your index and then upgrade your plan.

1. Prepare to migrate

Migrating a legacy index to serverless can take up to 30 minutes. During that time, you can continue reading from the legacy index. However, any upserts, updates, and deletes to the legacy index will not automatically be reflected in the new severless index, so be sure to prepare in one of the following ways:

  • Pause write traffic: If downtime is acceptible, pause traffic to the legacy index before starting migration. After migration, you will start sending all traffic to the serverless index.

  • Log your writes: If you need to continue reading from the legacy during migration, send read traffic to the legacy index, but log 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.

2. Start migration

  1. In the Pinecone console, go to your legacy starter index and click Migrate to serverless.

  2. To save the legacy index and create a new serverless index now, click Migrate now, enter a name for your new serverless index, and follow the prompts.

    To save the legacy index now and create a serverless index later, click Create a collection and follow the prompts.

The process can take up to 30 minutes.

3. 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  
    

4. 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.

5. 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 legacy index. Update your code to target the new serverless index:

    index = pc.Index("YOUR_SERVERLESS_INDEX_NAME")  
    
  2. Reinitialize your clients.

  3. If you logged writes to the legacy index during migration, replay the logged writes to your serverless index.

  4. Delete the legacy starter index.

See also

Was this page helpful?