The Pinecone class is the main entrypoint to this sdk. You will use instances of it to create and manage indexes as well as perform data operations on those indexes after they are created.

Initializing the client

There is one piece of configuration required to use the Pinecone client: an API key. This value can be passed using environment variables or in code through a configuration object. Find your API key in the console dashboard at https://app.pinecone.io

Using environment variables

The environment variables used to configure the client are the following:

export PINECONE_API_KEY="your_api_key"
export PINECONE_CONTROLLER_HOST="your_controller_host"

When these environment variables are set, the client constructor does not require any additional arguments.

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

const pinecone = new Pinecone();

Using a configuration object

If you prefer to pass configuration in code, the constructor accepts a config object containing the apiKey and environment values. This could be useful if your application needs to interact with multiple projects, each with a different configuration.

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

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

See PineconeConfiguration for a full description of available configuration options.

Hierarchy

  • Pinecone

Constructors

Methods

  • Targets a specific index for performing data operations.

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

    const pinecone = new Pinecone()
    const index = pinecone.index('index-name')

    Targeting an index, with user-defined Metadata types

    If you are storing metadata alongside your vector values inside your Pinecone records, you can pass a type parameter to index() in order to get proper TypeScript typechecking when upserting and querying data.

    const pinecone = new Pinecone();

    type MovieMetadata = {
    title: string,
    runtime: numbers,
    genre: 'comedy' | 'horror' | 'drama' | 'action'
    }

    // Specify a custom metadata type while targeting the index
    const index = pinecone.index<MovieMetadata>('test-index');

    // Now you get type errors if upserting malformed metadata
    await index.upsert([{
    id: '1234',
    values: [
    .... // embedding values
    ],
    metadata: {
    genre: 'Gone with the Wind',
    runtime: 238,
    genre: 'drama',

    // @ts-expect-error because category property not in MovieMetadata
    category: 'classic'
    }
    }])

    const results = await index.query({
    vector: [
    ... // query embedding
    ],
    filter: { genre: { '$eq': 'drama' }}
    })
    const movie = results.matches[0];

    if (movie.metadata) {
    // Since we passed the MovieMetadata type parameter above,
    // we can interact with metadata fields without having to
    // do any typecasting.
    const { title, runtime, genre } = movie.metadata;
    console.log(`The best match in drama was ${title}`)
    }

    Type Parameters

    Parameters

    • indexName: string

      The name of the index to target.

    • Optional indexHostUrl: string

      An optional host url to use for operations against this index. If not provided, the host url will be resolved by calling describeIndex.

    Returns Index<T>

    An Index object that can be used to perform data operations.

  • Configure an index

    Use this method to update configuration on an existing index. You can update the number of replicas, and pod type.

    Parameters

    • indexName: string

      The name of the index to configure.

    • options: ConfigureIndexRequestSpecPod

      The configuration properties you would like to update

    Returns Promise<IndexModel>

    A promise that resolves to IndexModel when the request to configure the index is completed.

    Example

    await pinecone.configureIndex('my-index', { replicas: 2, podType: 'p1.x2' })
    
  • Create a new collection from an existing index

    Parameters

    Returns Promise<CollectionModel>

    a promise that resolves to CollectionModel when the request to create the collection is completed.

    Example

    const indexList = await pinecone.listIndexes()
    const indexName = indexList.indexes[0].name;
    await pinecone.createCollection({
    name: 'my-collection',
    source: indexName
    })
  • Creates a new index.

    Parameters

    Returns Promise<void | IndexModel>

    A promise that resolves to IndexModel when the request to create the index is completed. Note that the index is not immediately ready to use. You can use the describeIndex function to check the status of the index.

    Example

    The minimum required configuration to create an index is the index name, dimension, and spec.

    await pinecone.createIndex({ name: 'my-index', dimension: 128, spec: { serverless: { cloud: 'aws', region: 'us-west-2' }}})
    

    Example

    ⚠️ Warning

    Serverless indexes are in public preview and are available only on AWS in the us-west-2 region. Check the current limitations and test thoroughly before using it in production.

    The spec object defines how the index should be deployed. For serverless indexes, you define only the cloud and region where the index should be hosted. For pod-based indexes, you define the environment where the index should be hosted, the pod type and size to use, and other index characteristics. In a different example, you can create a pod-based index by specifying the pod spec object with the environment, pods, podType, and metric properties.

    await pinecone.createIndex({
    name: 'my-index',
    dimension: 1536,
    metric: 'cosine',
    spec: {
    pod: {
    environment: 'us-west-2-gcp',
    pods: 1,
    podType: 'p1.x1'
    }
    }
    })

    Example

    If you would like to create the index only if it does not already exist, you can use the suppressConflicts boolean option.

    await pinecone.createIndex({
    name: 'my-index',
    dimension: 1536,
    spec: {
    serverless: {
    cloud: 'aws',
    region: 'us-west-2'
    }
    },
    suppressConflicts: true
    })

    Example

    If you plan to begin upserting immediately after index creation is complete, you should use the waitUntilReady option. Otherwise, the index may not be ready to receive data operations when you attempt to upsert.

    await pinecone.createIndex({
    name: 'my-index',
    spec: {
    serverless: {
    cloud: 'aws',
    region: 'us-west-2'
    }
    },
    waitUntilReady: true
    });

    const records = [
    // PineconeRecord objects with your embedding values
    ]
    await pinecone.index('my-index').upsert(records)

    Example

    By default all metadata fields are indexed when records are upserted with metadata, but if you want to improve performance you can specify the specific fields you want to index. This example is showing a few hypothetical metadata fields, but the values you'd use depend on what metadata you plan to store with records in your Pinecone index.

    await pinecone.createIndex({
    name: 'my-index',
    dimension: 1536,
    spec: {
    serverless: {
    cloud: 'aws',
    region: 'us-west-2',
    metadataConfig: { 'indexed' : ['productName', 'productDescription'] }
    }
    },
    })

    See

    Throws

    PineconeArgumentError when invalid arguments are provided.

    Throws

    PineconeConflictError when attempting to create an index using a name that already exists in your project.

    Throws

    PineconeBadRequestError when index creation fails due to invalid parameters being specified or other problem such as project quotas limiting the creation of any additional indexes.

  • Delete a collection by collection name

    Parameters

    • collectionName: string

      The name of the collection to delete.

    Returns Promise<void>

    A promise that resolves when the request to delete the collection is completed.

    Example

    const collectionList = await pinecone.listCollections()
    const collectionName = collectionList.collections[0].name;
    await pinecone.deleteCollection(collectionName)
  • Deletes an index

    Parameters

    • indexName: string

      The name of the index to delete.

    Returns Promise<void>

    A promise that resolves when the request to delete the index is completed.

    Example

    await pinecone.deleteIndex('my-index')
    

    Throws

    PineconeArgumentError when invalid arguments are provided

  • Describe a collection

    Parameters

    • collectionName: string

      The name of the collection to describe.

    Returns Promise<CollectionModel>

    A promise that resolves to a CollectionModel.

    Example

    await pinecone.describeCollection('my-collection')
    
  • Describe a Pinecone index

    Parameters

    • indexName: string

      The name of the index to describe.

    Returns Promise<IndexModel>

    A promise that resolves to IndexModel

    Example

    const indexModel = await pinecone.describeIndex('my-index')
    console.log(indexModel)
    // {
    // 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'
    // }
    // }
  • Targets a specific index for performing data operations.

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

    const pinecone = new Pinecone()
    const index = pinecone.index('index-name')

    Targeting an index, with user-defined Metadata types

    If you are storing metadata alongside your vector values inside your Pinecone records, you can pass a type parameter to index() in order to get proper TypeScript typechecking when upserting and querying data.

    const pinecone = new Pinecone();

    type MovieMetadata = {
    title: string,
    runtime: numbers,
    genre: 'comedy' | 'horror' | 'drama' | 'action'
    }

    // Specify a custom metadata type while targeting the index
    const index = pinecone.index<MovieMetadata>('test-index');

    // Now you get type errors if upserting malformed metadata
    await index.upsert([{
    id: '1234',
    values: [
    .... // embedding values
    ],
    metadata: {
    genre: 'Gone with the Wind',
    runtime: 238,
    genre: 'drama',

    // @ts-expect-error because category property not in MovieMetadata
    category: 'classic'
    }
    }])

    const results = await index.query({
    vector: [
    ... // query embedding
    ],
    filter: { genre: { '$eq': 'drama' }}
    })
    const movie = results.matches[0];

    if (movie.metadata) {
    // Since we passed the MovieMetadata type parameter above,
    // we can interact with metadata fields without having to
    // do any typecasting.
    const { title, runtime, genre } = movie.metadata;
    console.log(`The best match in drama was ${title}`)
    }

    Type Parameters

    Parameters

    • indexName: string

      The name of the index to target.

    • Optional indexHostUrl: string

      An optional host url to use for operations against this index. If not provided, the host url will be resolved by calling describeIndex.

    Returns Index<T>

    An Index object that can be used to perform data operations.

  • List all Pinecone indexes

    Returns Promise<IndexList>

    A promise that resolves to IndexList.

    Example

    const indexList = await pinecone.listIndexes()
    console.log(indexList)
    // {
    // 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"
    // }
    // }
    // ]
    // }