The Index class is used to perform data operations (upsert, query, etc) against Pinecone indexes. Typically it will be instantiated via a Pinecone client instance that has already built the required configuration from a combination of sources.

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

Hierarchy

  • Index

Constructors

  • Instantiation of Index is handled by Pinecone

    Type Parameters

    Parameters

    • indexName: string

      The name of the index that will receive operations from this Index instance.

    • config: PineconeConfiguration

      The configuration from the Pinecone client.

    • namespace: string = ''

      The namespace for the index.

    • Optional indexHostUrl: string

      An optional override for the host address used for data operations.

    Returns Index<T>

    Example

    const pinecone = new Pinecone();
    const index = pinecone.index('my-index');

Methods

  • Delete all records from the targeted namespace. To delete all records from across all namespaces, delete the index using deleteIndex and create a new one using createIndex.

    Returns Promise<void>

    A promise that resolves when the delete is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').describeIndexStats();
    // {
    // namespaces: {
    // '': { recordCount: 10 },
    // foo: { recordCount: 1 }
    // },
    // dimension: 8,
    // indexFullness: 0,
    // totalRecordCount: 11
    // }

    await pinecone.index('my-index').deleteAll();

    // Records in default namespace '' are now gone, but records in namespace 'foo' are not modified.
    await client.index('my-index').describeIndexStats();
    // {
    // namespaces: {
    // foo: { recordCount: 1 }
    // },
    // dimension: 8,
    // indexFullness: 0,
    // totalRecordCount: 1
    // }
  • Delete records from the index by either an array of ids, or a filter object. See Filtering with metadata for more on deleting records with filters.

    Parameters

    • options: any

      An array of record id values or a filter object.

    Returns Promise<void>

    A promise that resolves when the delete is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').deleteMany(['record-1', 'record-2']);

    // or
    await pinecone.index('my-index').deleteMany({ genre: 'classical' });

    Throws

    PineconeArgumentError when invalid arguments are passed.

  • Delete a record from the index by id.

    Parameters

    • id: any

      The id of the record to delete.

    Returns Promise<void>

    A promise that resolves when the delete is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').deleteOne('record-1');

    Throws

    PineconeArgumentError when invalid arguments are passed.

  • Describes the index's statistics such as total number of records, records per namespace, and the index's dimension size.

    Returns Promise<IndexStatsDescription>

    A promise that resolves with the IndexStatsDescription value when the operation is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').describeIndexStats();

    // {
    // namespaces: {
    // '': { recordCount: 10 }
    // foo: { recordCount: 2000 },
    // bar: { recordCount: 2000 }
    // },
    // dimension: 1536,
    // indexFullness: 0,
    // totalRecordCount: 4010
    // }
  • Returns an Index targeting the specified namespace. By default, all operations take place inside the default namespace ''.

    Parameters

    • namespace: string

      The namespace to target within the index. All operations performed with the returned client instance will be scoped only to the targeted namespace.

      This namespace() method will inherit custom metadata types if you are chaining the call off an Index client instance that is typed with a user-specified metadata type. See index for more info.

    Returns Index<T>

    Example

    const pinecone = new Pinecone();

    // Create an Index client instance scoped to operate on a
    // single namespace
    const ns = pinecone.index('my-index').namespace('my-namespace');

    // Now operations against this intance only affect records in
    // the targeted namespace
    ns.upsert([
    // ... records to upsert in namespace 'my-namespace'
    ])

    ns.query({
    // ... query records in namespace 'my-namespace'
    })
  • Query records from the index. Query is used to find the topK records in the index whose vector values are most similar to the vector values of the query according to the distance metric you have configured for your index. See Query data for more on querying.

    Parameters

    Returns Promise<QueryResponse<T>>

    A promise that resolves with the QueryResponse when the query is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').query({ topK: 3, id: 'record-1'});

    // or
    await pinecone.index('my-index').query({ topK: 3, vector: [0.176, 0.345, 0.263] });

    Throws

    PineconeConnectionError when invalid environment, project id, or index name is configured.

    Throws

    PineconeArgumentError when invalid arguments are passed.

  • Upsert records to the index.

    Parameters

    Returns Promise<void>

    A promise that resolves when the upsert is completed.

    Example

    const pinecone = new Pinecone();
    await pinecone.index('my-index').upsert([{
    id: 'record-1',
    values: [0.176, 0.345, 0.263],
    },{
    id: 'record-2',
    values: [0.176, 0.345, 0.263],
    }])

    Throws

    PineconeConnectionError when invalid environment, project id, or index name is configured.

    Throws

    PineconeArgumentError when invalid arguments are passed.