Migrate to the new API

Pinecone’s new API gives you the same great vector database but with a drastically improved developer experience over the legacy API.

To use the new API, existing Pinecone client users must:

• Upgrade to new client versions
• Adapt existing code

If you are a new Pinecone user, try the Quickstart to get a vector search service up and running in minutes using the new API.

​

Install the latest client version

​

Python

To install the latest version of the Python client, run the following command:

pip install pinecone-client

If you already have the Python client, run the following command:

pip install pinecone-client --upgrade

​

Node.js

To install the new version of the Node.js client, run the following command:

npm install @pinecone-database/pinecone

If you already have the Node.js client, run the following command:

npm install @pinecone-database/pinecone@latest

​

Java

You can install the latest version of the Java client from Maven Central for use as a maven dependency in the following ways:

// Maven
<dependency>
  <groupId>io.pinecone</groupId>
  <artifactId>pinecone-client</artifactId>
  <version>1.0.0</version>
</dependency>

// Gradle
implementation "io.pinecone:pinecone-client:1.0.0"

​

Adapt existing code

The new API requires some code adaptation if you are migrating from the legacy API. This section summarizes the most important changes to address.

For a comprehensive list of changes, see the Python client v3 migration guide and Node.js client v2 migration guide.

​

Update the URL for control plane operations

On the new API, the global URL for all control plane operations, regardless of cloud environment, is https://api.pinecone.io. The control plane is where you can list indexes, create indexes, list collections, and more.

​

Authentication

Authenticating with a Pinecone client or the REST API now requires only the API key for your project. The environment parameter is no longer required because you now choose a cloud environment for each index, and all control operations use a global URL (https://api.pinecone.io).

Using the new API, you initialize a client object just with your project API key:

from pinecone import Pinecone

pc = Pinecone(api_key='YOUR_API_KEY')

​

Create indexes

In the new API, you can create both serverless and pod-based indexes..

​

Create a serverless index

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

from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

pc.create_index(
    name="serverless-index",
    dimension=1536,
    metric="cosine",
    spec=ServerlessSpec(
        cloud='aws', 
        region='us-east-1'
    ) 
) 

​

Create a pod-based index

To create a pod-based index, use the spec parameter to define the environment where the index should be deployed, the pod type and size to use, and other index characteristics. For Python, you also need to import the PodSpec class.

from pinecone import Pinecone, PodSpec

pc = Pinecone(api_key='YOUR_API_KEY')

pc.create_index(
    name='pod-index', 
    dimension=1536, 
    metric='cosine', 
    spec=PodSpec(
        environment="us-west1-gcp", 
        pod_type="p1.x1",
        pods=1
    )
)

​

List indexes

Using the new API, the list_indexes operation now fetches a complete description of each index. The data returned on each index is equivalent to what you get back from the describe_index operation.

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

​

Describe indexes

Using the new API, the describe_index operation returns a description of an index in a different format than the legacy API. It also returns the index endpoint needed to run data plane operations against the index.

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