v2 Migration Guide

Warning: This migration guide is specific to migrating from the v1.x to v2.x. The code examples in this guide demonstrate moving from v1.x to v2.x. For details on migrating from v0.x please see the v1-migration guide.

Changes overview

The v2 TypeScript SDK is consuming the new Global Control Plane API. This results in a large amount of flexibility in how API keys are used in comparison to the v1 TypeScript SDK built around the legacy regional control planes where API keys and environments had a rigid 1:1 relationship.
Refactored createIndex to accept either a PodSpec or ServerlessSpec interface depending on how users would like to deploy their index. Many old properties such as podType, pods, etc are moved into PodSpec since they do not apply to serverless indexes.
The listIndexes function now returns an array with full descriptions of each index rather than an array of names.
THe describeIndex function takes the same argument as before, but returns data in a different shape reflecting the move of some configurations under the spec key and elevation of host to the top level.
Added optional environment variables, see below for details.
- PINECONE_DEBUG
- PINECONE_DEBUG_CURL
- PINECONE_CONTROLLER_HOST

Installation, Importing, and Initialization

Installing `v2.0.0`

npm install @pinecone-database/pinecone@2

Importing and Initialization

Improvements in v2.0.0

Thanks to changes implemented in the Global Control Plane, there is no longer a need to specify environment along with the API key. This allows the use of a single API key to create and manage indexes in multiple environments. We’ve also added the ability to pass controllerHostUrl on initialization, which is useful if you’re using a proxy or know the address of your index, allowing you to bypass control plane calls to resolve the index host.

Initialization with keyword arguments

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({
  apiKey: 'your_api_key',
  environment: 'your_environmet',
});

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({ apiKey: 'your_api_key' });

Initialization with environment variables

If you attempt to initialize with no arguments and the expected environment variable for API key is not set, a PineconeConfigurationError will be thrown.

Before: ≤ 1.1.2

Expected env vars:

PINECONE_API_KEY
PINECONE_ENVIRONMENT

After: ≥ 2.0.0

Expected env vars:

PINECONE_API_KEY

In both cases, when the proper environment variables are set initialization does not require any additional arguments:

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone();

New Feature: View verbose debug output about requests

Set PINECONE_DEBUG=true and / or PINECONE_DEBUG_CURL=true environment variables to see verbose output about the network requests being made. Be careful as this output may include secrets such as API keys passed in request headers.

Control Plane Operations

The primary differences between v1.1.2 and v2.0.0 is how you interact with your indexes through control plane operations. The shape of request and response payloads have changed in some cases as well.

Creating Indexes

In the new v2.0.0 client, there is a lot more flexibility in how indexes are created. With the introduction of Pinecone’s serverless offering, we need a way to tell the API how we would like to deploy our index. Many configuration fields are now passed as part of a deployment spec parameter, which can contain either a serverless configuration, or a pod configuration.

Creating a serverless index

Serverless indexes are newly available with the v2.0.0 client, and you must be on this version or greater to work with them. Creating a serverless index requires defining the cloud and region where the server should be hosted via the spec object with the key serverless. For more information on serverless and regional availability, see Understanding indexes.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
  name: 'sample-index',
  dimension: 1536,
  metric: 'cosine',
  spec: {
    serverless: {
      cloud: 'aws',
      region: 'us-west-2',
    },
  },
});

Creating a pod-based index

The most important changes to how pod indexes are created are:

Configuration that describes how the index is deployed is now passed as a spec object with the key pod which should conform to the type of the PodSpec interface.
environment used to be a required configuration parameter for the client, but is now passed as part of PodSpec.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
  name: 'sample-index',
  dimension: 1536,
  metric: 'cosine',
  podType: 'p1.x1',
  pods: 1,
  metadataConfig: {
    indexed: ['propertyName'],
  },
});

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
  name: 'sample-index',
  dimension: 1536,
  metric: 'cosine',
  spec: {
    pod: {
      environment: 'us-east1-gcp',
      podType: 'p1.x1',
      pods: 1,
      metadataConfig: {
        indexed: ['propertyName'],
      },
    },
  },
});

Special cases: gcp-starter indexes

Starter indexes are a special case of the “pod-based index” described above. Here’s a specific example of how this work post v2.0.0.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
  name: 'sample-index',
  dimension: 1536,
  metric: 'cosine',
});

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createIndex({
  name: 'sample-index',
  dimension: 1536,
  metric: 'cosine',
  spec: {
    pod: {
      environment: 'gcp-starter',
      podType: 'p1.x1',
      pods: 1,
    },
  },
});

Listing Indexes

In the past the listIndexes operation returned an array of index names and no other information. In the v2.0.0 client, the listIndexes operation fetches a complete description of each index. The model returned for each index is equivalent to what you would get back from a describeIndex call.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

const indexes = await pc.listIndexes();
console.log(indexes);
//[ { name: 'sample-index1' }, { name: 'sample-index2' } ]

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

const indexes = await pc.listIndexes();
console.log(indexes);
// {
//     indexes: [
//       {
//         name: "sample-index-1",
//         dimension: 3,
//         metric: "cosine",
//         host: "sample-index-1-1234567.svc.apw5-2e18-32fa.pinecone.io",
//         spec: {
//           serverless: {
//             cloud: "aws",
//             region: "us-west-2"
//           }
//         },
//         status: {
//           ready: true,
//           state: "Ready"
//         }
//       },
//       {
//         name: "sample-index-2",
//         dimension: 3,
//         metric: "cosine",
//         host: "sample-index-2-1234567.svc.apw2-5e76-83fa.pinecone.io",
//         spec: {
//           serverless: {
//             cloud: "aws",
//             region: "us-west-2"
//           }
//         },
//         status: {
//           ready: true,
//           state: "Ready"
//         }
//       }
//     ]
//   }

Describing indexes

The describeIndex operation still takes one argument (the name of an index) which has not changed, but the response now includes different data. The response properties have evolved and moved around so that we can represent the description of both pod and serverless indexes:

name	no change
dimension	no change
metric	no change
status.ready	no change
status.state	no change
host	added
environment	added to spec object (for pod indexes)
replicas	moved to spec object (for pod indexes)
shards	moved to spec object (for pod indexes)
pods	moved to spec object (for pod indexes)
pod_type	moved to spec object (for pod indexes)
metadata_config	moved to spec object (for pod indexes)
source_collection	moved to spec object (for pod indexes)
region	added to spec object (for serverless indexes)
cloud	added to spec object (for serverless indexes)

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

const index = await pc.describeIndex('sample-index');
console.log(index);
// {
//     database: {
//         name: 'sample-index',
//         dimension: 3,
//         metric: 'cosine',
//         pods: 1,
//         replicas: 1,
//         shards: 1,
//         podType: 'p1.x1'
//     },
//     status: {
//         ready: true,
//         state: 'Ready',
//         host: 'search-history-1234567.svc.us-east4-gcp.pinecone.io',
//         port: 433
//     }
// }

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

const index = await pc.describeIndex('sample-index');
console.log(index);
// {
//     name: 'sample-index-1',
//     dimension: 3,
//     metric: 'cosine',
//     host: 'sample-index-1-1390950.svc.apw5-4e34-81fa.pinecone.io',
//     spec: {
//           pod: undefined,
//           serverless: {
//               cloud: 'aws',
//               region: 'us-west-2'
//           }
//     },
//     status: {
//           ready: true,
//           state: 'Ready'
//     }
// }

Deleting Indexes

There are no significant changes to the deleteIndex operation.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.deleteIndex('sample-index');

Configure pod-based indexes

Configuring an index after creation is specific to pod indexes. With serverless indexes, you don't configure any compute or storage resources. Calls to configureIndex are unchanged. However, v2.0.0 will return the index object after a successful configuration request.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.configureIndex('sample-index', { replicas: 5, podType: 'p2.x2' });
// undefined

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.configureIndex('sample-index', { replicas: 5, podType: 'p2.x2' });
// {
//   name: 'sample-index',
//   dimension: 3,
//   metric: 'cosine',
//   host: 'sample-index-1-1390950.svc.apw5-4e34-81fa.pinecone.io',
//   spec: {
// 		pod: {
// 			environment: 'us-west-1-aws',
// 			replicas: 1,
// 			shards: 1,
// 			podType: 'p1.x1',
// 			pods: 10
// 		},
// 	},
//   status: {
// 		ready: false,
// 		state: 'ScalingUp'
// 	}
// }

Collections

ℹ️ Note

Serverless and starter indexes do not support collections.

Collection operations in the SDK are largely unchanged. However, note that collections can only be created from data in pod indexes, and collections can only be used to create pod indexes. Attempting to use these with serverless indexes will result in errors.

Create collection

The createCollection operation is unchanged. However, v2.0.0 will return the collection model after a successful create request.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createCollection({
  name: 'sample-collection',
  source: 'sample-index',
});
// undefined

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.createCollection({
  name: 'sample-collection',
  source: 'sample-index',
});
// {
// 	name: 'sample-collection',
// 	size: 1532895,
// 	status: 'Ready',
// 	dimension: 10,
// 	recordCount: 2039,
// 	environment: 'us-west-1-aws'
// }

List collections

The listCollections response now contains the full collection models.

Before: ≤ 1.1.2

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.listCollections();
// [{ name: 'sample-collection-1' }, { name: 'sample-collection-2' }];

After: ≥ 2.0.0

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.listCollections();
// {
//   collections: [
//     {
//       name: 'sample-collection-1',
//       size: 1532895,
//       status: 'Ready',
//       dimension: 10,
//       recordCount: 2039,
//       environment: 'us-west-1-aws',
//     },
//     {
//       name: 'sample-collection-2',
//       size: 28393829,
//       status: 'Ready',
//       dimension: 15,
//       recordCount: 3129,
//       environment: 'us-west-1-aws',
//     },
//   ];
// }

Describe collection

The describeCollections operation is unchanged. v2.0.0 will return an additional field denoting the environment in which the collection is hosted.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.describeCollection('sample-collection');
// {
// 	name: 'sample-collection',
// 	size: 1532895,
// 	status: 'Ready',
// 	dimension: 10,
// 	recordCount: 2039,
// 	environment: 'us-west-1-aws' // only returned by v2.0.0
// }

Delete collection

The deleteCollection operation is unchanged.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

await pc.deleteCollection('sample-collection');

Vector Operations

Across both client versions vector operations remain largely unchanged. Data plane operations are performed against specific indexes. The SDK will resolve the relevant host for each index automatically when you target an index for operations. Targeting an index involves using the index method and providing an index name.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

const index = pc.index('my-index');

// Now perform data plane operations against 'my-index'
await index.fetch(['1', '2', '3']);

Vector Operations: Upsert, query, fetch, etc

Once you've targeted an index, the usage for data plane operations has not changed. Please see the section in the README.md Index operations.

For serverless indexes, see cost information in responses

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index('my-index');

index.fetch(['1']);
// {
//   records: {
//     '1': {
//       id: '1',
//       values: [0.5, 0.7],
//       sparseValues: undefined,
//       metadata: undefined
//     }
//   },
//   namespace: '',
//   usage: {
//     readUnits: 5
//   }
// }

index.query({ vector: [0.3, 0.5], topK: 1 });
// {
//   matches: [
//     {
//       id: '556',
//       score: 1.00000012,
//       values: [],
//       sparseValues: undefined,
//       metadata: undefined
//     }
//   ],
//   namespace: '',
//   usage: {
//     readUnits: 5
//   }
// }

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

v2-migration.md

v2-migration.md

v2 Migration Guide

Changes overview

Installation, Importing, and Initialization

Installing `v2.0.0`

Importing and Initialization

Improvements in v2.0.0

Initialization with keyword arguments

Initialization with environment variables

New Feature: View verbose debug output about requests

Control Plane Operations

Creating Indexes

Creating a serverless index

Creating a pod-based index

Special cases: gcp-starter indexes

Listing Indexes

Describing indexes

Deleting Indexes

Configure pod-based indexes

Collections

Create collection

List collections

Describe collection

Delete collection

Vector Operations

Vector Operations: Upsert, query, fetch, etc

For serverless indexes, see cost information in responses

Files

v2-migration.md

Latest commit

History

v2-migration.md

File metadata and controls

v2 Migration Guide

Changes overview

Installation, Importing, and Initialization

Installing v2.0.0

Importing and Initialization

Improvements in v2.0.0

Initialization with keyword arguments

Initialization with environment variables

New Feature: View verbose debug output about requests

Control Plane Operations

Creating Indexes

Creating a serverless index

Creating a pod-based index

Special cases: gcp-starter indexes

Listing Indexes

Describing indexes

Deleting Indexes

Configure pod-based indexes

Collections

Create collection

List collections

Describe collection

Delete collection

Vector Operations

Vector Operations: Upsert, query, fetch, etc

For serverless indexes, see cost information in responses

Installing `v2.0.0`