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 pc = new Pinecone()

const indexModel = await pc.describeIndex('index-name');
const index = pc.index({ host: indexModel.host })

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.

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

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

// Specify a custom metadata type while targeting the index
const index = pc.index<MovieMetadata>({ name: 'test-index' });

// Now you get type errors if upserting malformed metadata
await index.upsert({
records: [{
id: '1234',
values: [
.... // embedding values
],
metadata: {
title: '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

Constructors

  • Instantiation of Index is handled by Pinecone

    Type Parameters

    Parameters

    Returns Index<T>

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

    // Get host from describeIndex
    const indexModel = await pc.describeIndex('my-index');
    const index = pc.index({ host: indexModel.host });

    // Or get host from createIndex response
    const indexModel = await pc.createIndex({
    name: 'my-index',
    dimension: 1536,
    spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }
    });
    const index = pc.index({ host: indexModel.host });

Methods

  • Cancel a specific import operation.

    Parameters

    • id: string

      The id of the import operation to cancel.

    Returns Promise<object>

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    console.log(await index.cancelImport('import-id'));

    // {}
  • Creates a new namespace within the index with an optional metadata schema.

    Parameters

    • options: CreateNamespaceOptions

      Configuration options for creating the namespace.

      Options for creating a namespace.

      • name: string

        The name of the namespace to create.

      • Optionalschema?: MetadataSchema

        Schema for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when schema is present, only fields which are present in the fields object with a filterable: true are indexed. Note that filterable: false is not currently supported.

    Returns Promise<NamespaceDescription>

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    await index.createNamespace({
    name: 'my-namespace',
    schema: {
    fields: {
    genre: { filterable: true },
    year: { filterable: true }
    }
    }
    });
  • Delete all records from the targeted namespace. To delete all records from across all namespaces, delete the index using Pinecone.deleteIndex and create a new one using Pinecone.createIndex.

    Parameters

    Returns Promise<void>

    A promise that resolves when the delete is completed.

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

    await index.describeIndexStats();
    // {
    // namespaces: {
    // '': { recordCount: 10 },
    // foo: { recordCount: 1 }
    // },
    // dimension: 8,
    // indexFullness: 0,
    // totalRecordCount: 11
    // }
    // Deletes all records from the default namespace '__default__'. Records in other namespaces are not modified.
    await index.deleteAll();

    // Deletes all records from the namespace 'foo'. Records in other namespaces are not modified.
    await index.deleteAll({ namespace: 'foo' });

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • 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

    Returns Promise<void>

    A promise that resolves when the delete is completed.

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

    await index.deleteMany({ ids: ['record-1', 'record-2'] });

    // or
    await index.deleteMany({ filter: { genre: 'classical' } });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Deletes a specific namespace from the index, including all records within it.

    Parameters

    • namespace: string

      The namespace to delete.

    Returns Promise<void>

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    await index.deleteNamespace('ns-1');
  • Delete a record from the index by id.

    Parameters

    Returns Promise<void>

    A promise that resolves when the delete is completed.

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

    await index.deleteOne({ id: 'record-1', namespace: 'foo' });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Return details of a specific import operation.

    Parameters

    • id: string

      The id of the import operation to describe.

    Returns Promise<ImportModel>

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    console.log(await index.describeImport('import-id'));

    // {
    // id: '1',
    // uri: 's3://dev-bulk-import-datasets-pub/10-records-dim-10',
    // status: 'Completed',
    // createdAt: 2024-09-17T16:59:57.973Z,
    // finishedAt: 2024-09-17T17:00:12.809Z,
    // percentComplete: 100,
    // recordsImported: 20,
    // error: undefined
    // }
  • Describes the index's statistics such as total number of records, records per namespace, and the index's dimension size.

    Parameters

    Returns Promise<IndexStatsDescription>

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

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

    await index.describeIndexStats();
    // {
    // namespaces: {
    // '': { recordCount: 10 }
    // foo: { recordCount: 2000 },
    // bar: { recordCount: 2000 }
    // },
    // dimension: 1536,
    // indexFullness: 0,
    // totalRecordCount: 4010
    // }

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Returns the details of a specific namespace.

    Parameters

    • namespace: string

      The namespace to describe.

    Returns Promise<NamespaceDescription>

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    console.log(await index.describeNamespace('ns-1'));

    // { name: 'ns-1', recordCount: '1' }
  • Fetch records from the index.

    Parameters

    Returns Promise<FetchResponse<T>>

    A promise that resolves with the FetchResponse when the fetch is completed.

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

    // Fetch from default namespace
    await index.fetch({ ids: ['record-1', 'record-2'] });

    // Override namespace for this operation
    await index.fetch({ ids: ['record-1', 'record-2'], namespace: 'my-namespace' });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • List all recent and ongoing import operations.

    Parameters

    • Optionallimit: number

      (Optional) Max number of import operations to return per page.

    • OptionalpaginationToken: string

      (Optional) Pagination token to continue a previous listing operation.

    Returns Promise<ListImportsResponse>

    A promise that resolves to a ListImportsResponse when the operation is complete.

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    console.log(await index.listImports(10));

    // {
    // data: [
    // {
    // id: '1',
    // uri: 's3://dev-bulk-import-datasets-pub/10-records-dim-10',
    // status: 'Completed',
    // createdAt: 2024-09-17T16:59:57.973Z,
    // finishedAt: 2024-09-17T17:00:12.809Z,
    // percentComplete: 100,
    // recordsImported: 20,
    // error: undefined
    // }
    // ],
    // pagination: undefined // Example is only 1 item, so no pag. token given.
    // }

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Returns a list of namespaces within the index.

    Parameters

    Returns Promise<ListNamespacesResponse>

    A promise that resolves to a ListNamespacesResponse when the operation is complete.

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('my-serverless-index');
    const index = pc.index({ host: indexModel.host });
    console.log(await index.listNamespaces({ limit: 10 }));

    // {
    // namespaces: [
    // { name: 'ns-1', recordCount: '1' },
    // { name: 'ns-2', recordCount: '1' }
    // ],
    // pagination: undefined
    // }

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • The listPaginated operation finds vectors based on an id prefix within a single namespace. It returns matching ids in a paginated form, with a pagination token to fetch the next page of results. This id list can then be passed to fetch or delete options to perform operations on the matching records. See Get record IDs for guidance and examples.

    Parameters

    Returns Promise<ListResponse>

    • A promise that resolves with the ListResponse when the operation is completed.
    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();

    const indexModel = await pc.describeIndex('my-index');
    const index = pc.index({ host: indexModel.host, namespace: 'my-namespace' });

    const results = await index.listPaginated({ prefix: 'doc1#' });
    console.log(results);
    // {
    // vectors: [
    // { id: 'doc1#01' }, { id: 'doc1#02' }, { id: 'doc1#03' },
    // { id: 'doc1#04' }, { id: 'doc1#05' }, { id: 'doc1#06' },
    // { id: 'doc1#07' }, { id: 'doc1#08' }, { id: 'doc1#09' },
    // ...
    // ],
    // pagination: {
    // next: 'eyJza2lwX3Bhc3QiOiJwcmVUZXN0LS04MCIsInByZWZpeCI6InByZVRlc3QifQ=='
    // },
    // namespace: 'my-namespace',
    // usage: { readUnits: 1 }
    // }

    // Fetch the next page of results
    await index.listPaginated({ prefix: 'doc1#', paginationToken: results.pagination.next});

    ⚠️ Note:

    listPaginated is supported only for serverless indexes.

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

    Errors.PineconeArgumentError when invalid arguments are passed.

  • Returns an Index targeting the specified namespace. By default if no namespace is provided, all operations take place inside the default namespace '__default__'.

    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.

    Returns Index<T>

    An Index object that can be used to perform data operations scoped to the specified namespace.

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

    // Create an Index client instance scoped to operate on a
    // single namespace
    const ns = pc.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'
    })

    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 Pinecone.index for more info.

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

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

    // Query by id
    await index.query({ topK: 3, id: 'record-1'});

    // Query by vector
    await index.query({ topK: 3, vector: [0.176, 0.345, 0.263] });

    // Query a different namespace
    await index.query({ topK: 3, id: 'record-1', namespace: 'custom-namespace' });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Search a specific namespace for records within an index.

    Parameters

    Returns Promise<SearchRecordsResponse>

    a promise that resolves to SearchRecordsResponse when the operation is complete.

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('integrated-index');
    const namespace = pc.index({ host: indexModel.host, namespace: 'my-namespace' });

    const response = await namespace.searchRecords({
    query: {
    inputs: { text: 'disease prevention' }, topK: 4 },
    rerank: {
    model: 'bge-reranker-v2-m3',
    topN: 2,
    rankFields: ['chunk_text'],
    },
    fields: ['category', 'chunk_text'],
    });
    console.log(response);
    // {
    // "result": {
    // "hits": [
    // {
    // "id": "rec6",
    // "score": 0.1318424493074417,
    // "fields": {
    // "category": "nutrition",
    // "chunk_text": "Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases."
    // }
    // },
    // {
    // "id": "rec2",
    // "score": 0.004867417272180319,
    // "fields": {
    // "category": "nutrition",
    // "chunk_text": "Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut."
    // }
    // }
    // ]
    // },
    // "usage": {
    // "readUnits": 1,
    // "embedTotalTokens": 8,
    // "rerankUnits": 1
    // }
    // }

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Update a record in the index by id.

    Parameters

    Returns Promise<void>

    A promise that resolves when the update is completed.

    import { Pinecone } from '@pinecone-database/pinecone';
    const pc = new Pinecone();
    const indexModel = await pc.describeIndex('imdb-movies');
    const index = pc.index({ host: indexModel.host });

    await index.update({
    id: '18593',
    metadata: { genre: 'romance' },
    });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Upsert records to the index.

    Parameters

    Returns Promise<void>

    A promise that resolves when the upsert is completed.

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

    // Upsert to default namespace
    await index.upsert({
    records: [{
    id: 'record-1',
    values: [0.176, 0.345, 0.263],
    },{
    id: 'record-2',
    values: [0.176, 0.345, 0.263],
    }]
    })

    // Upsert to a different namespace
    await index.upsert({
    records: [{
    id: 'record-3',
    values: [0.176, 0.345, 0.263],
    }],
    namespace: 'my-namespace'
    })

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.

  • Upsert integrated records into a specific namespace within an index.

    Parameters

    Returns Promise<void>

    a promise that resolves when the operation is complete.

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

    const indexModel = await pc.describeIndex('integrated-index');
    const namespace = pc.index({ host: indexModel.host, namespace: 'my-namespace' });

    await namespace.upsertRecords({
    records: [
    {
    id: 'rec1',
    chunk_text:
    "Apple's first product, the Apple I, was released in 1976 and was hand-built by co-founder Steve Wozniak.",
    category: 'product',
    },
    {
    id: 'rec2',
    chunk_text:
    'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.',
    category: 'nutrition',
    },
    {
    id: 'rec3',
    chunk_text:
    'Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.',
    category: 'cultivation',
    },
    {
    id: 'rec4',
    chunk_text:
    'In 2001, Apple released the iPod, which transformed the music industry by making portable music widely accessible.',
    category: 'product',
    },
    {
    id: 'rec5',
    chunk_text:
    'Apple went public in 1980, making history with one of the largest IPOs at that time.',
    category: 'milestone',
    },
    {
    id: 'rec6',
    chunk_text:
    'Rich in vitamin C and other antioxidants, apples contribute to immune health and may reduce the risk of chronic diseases.',
    category: 'nutrition',
    },
    {
    id: 'rec7',
    chunk_text:
    "Known for its design-forward products, Apple's branding and market strategy have greatly influenced the technology sector and popularized minimalist design worldwide.",
    category: 'influence',
    },
    {
    id: 'rec8',
    chunk_text:
    'The high fiber content in apples can also help regulate blood sugar levels, making them a favorable snack for people with diabetes.',
    category: 'nutrition',
    },
    ]
    });

    Errors.PineconeArgumentError when arguments passed to the method fail a runtime validation.

    Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.