Pinecone’s new API gives you the same great vector database but with a drastically improved developer experience over the legacy API. This page summarizes the most important changes. For a comprehensive list, see the Python client v3 migration guide and Node.js client v2 migration guide.

Docs for the legacy API remain available at https://docs.pinecone.io/legacy.

Improvements

Serverless indexes

The new API lets you create serverless indexes for storing and querying your vector data. With serverless indexes, you don’t configure or manage compute and storage resources. You just load your data and your indexes scale automatically based on usage. Likewise, you don’t pay for dedicated resources that may sometimes lay idle. Instead, the pricing model for serverless indexes is consumption-based: You pay only for the amount of data stored and operations performed, with no minimums. You can still create pod-based indexes on the new API as well, and you can also continue to access indexes you created previously on the legacy API.

For guidance on creating serverless indexes, see Create indexes. For more on how costs are calculated for serverless indexes, see Understanding cost.

Serverless indexes are in public preview and are available only on AWS in the us-west-2, us-east-1, and eu-west-1 regions. Check current limits and restrictions and test thoroughly before using them in production.

Multi-region projects

On the legacy API, all indexes in a project are hosted in a single cloud region. On the new API, you have the flexibility to choose a different cloud region for each index. This makes it possible to consolidate related work across regions in a single project.

Global URL for control plane operations

On the new API, the global URL for all control plane operations like create_index, describe_index, and list_indexes is https://api.pinecone.io. You use this URL regardless of the cloud environment where an index is hosted. This simplifes the experience compared to the legacy API, where each environment has a unique URL: https://controller.{environment}.pinecone.io.

Changes

Updated clients

To use the new API, existing users of Pinecone clients must upgrade to new client versions and adapt some code. This page summarizes the most important changes. For a comprehensive list, see the Python client v3 migration guide and Node.js client v2 migration guide.

Python

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

Shell
pip install pinecone-client

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

Shell
pip install pinecone-client --upgrade

Node.js

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

Shell
npm install @pinecone-database/pinecone

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

Shell
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:

Java
// 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"

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

New API

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

Legacy API

Using the legacy API, you initialize a client with your project API key and environment:

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

Creating indexes

Now that you can create serverless or pod-based indexes, the syntax for defining indexes has changed compared to the legacy API.

Creating a serverless index

Serverless indexes are in public preview and are available only on AWS in the us-west-2, us-east-1, and eu-west-1 regions. Check current limits and restrictions and test thoroughly before using them in production.

New API

Using the new API, you create a serverless index by importing the ServerlessSpec class and using the spec parameter to define the cloud and region where the index should be deployed:

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

Legacy API

Serverless indexes cannot be created on the legacy API. You must use the new API.

Creating a pod-based index

New API

Using the new API, you create a pod-based index by importing the PodSpec class and using the spec parameter to define the environment where the index should be deployed, the pod type and size to use, and other index characteristics:

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

Listing indexes

Using the legacy API, the list_indexes operation returns an array of index names and no other information. Using the new API, the 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.

New API

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

Legacy API

Using the legacy API, the list_indexes operation returns an array of index names and no other information.

import pinecone

pinecone.init(
    api_key='YOUR_API_KEY', 
    environment='PROJECT_ENVIRONMENT'
)

pinecone.list_indexes()

# Response:
# ['sample-movies', 'news']

Describing 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 again the index.

New API

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

Legacy API

import pinecone

pinecone.init(
    api_key='YOUR_API_KEY', 
    environment='PROJECT_ENVIRONMENT'
)

pinecone.describe_index("test-index")

# # Response:
# IndexDescription(
#     name='sample-movies', 
#     metric='cosine', replicas=1, 
#     dimension=1536.0, 
#     shards=1, 
#     pods=1, 
#     pod_type='p1.x1', 
#     status={'ready': True, 'state': 'Ready'}, 
#     metadata_config=None, 
#     source_collection=''
# )

Serverless limitations

For serverless limitations, see Quotas and rate limits and Known limitations.

Get started

  • Try the Quickstart to get a vector search service up and running in minutes using the new API.