Class Index<T>

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 index = pc.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.

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

constructor

Methods

deleteAll deleteMany deleteOne describeIndexStats fetch listPaginated namespace query update upsert

Constructors

constructor

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

    • Optional additionalHeaders: HTTPHeaders

      An optional object of additional header to send with each request.

    Returns Index<T>

    Example

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

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

Methods

deleteAll

  • 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

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

    await index.describeIndexStats();
    // {
    //  namespaces: {
    //    '': { recordCount: 10 },
    //   foo: { recordCount: 1 }
    //   },
    //   dimension: 8,
    //   indexFullness: 0,
    //   totalRecordCount: 11
    // }

    await index.deleteAll();

    // Records from namespace 'foo' are now deleted. Records in other namespaces are not modified.
    await index.describeIndexStats();
    // {
    //  namespaces: {
    //   foo: { recordCount: 1 }
    //   },
    //   dimension: 8,
    //   indexFullness: 0,
    //   totalRecordCount: 1
    // }

    await index.deleteAll();
    // Since no namespace was specified, records in default namespace '' are now deleted.

    Throws

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

deleteMany

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

    Example

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

    await index.deleteMany(['record-1', 'record-2']);

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

    Throws

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

    Throws

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

deleteOne

  • Delete a record from the index by id.

    Parameters

    • id: string

      The id of the record to delete.

    Returns Promise<void>

    A promise that resolves when the delete is completed.

    Example

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

    await index.deleteOne('record-1');

    Throws

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

    Throws

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

describeIndexStats

  • 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

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

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

    Throws

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

fetch

  • Fetch records from the index.

    Parameters

    Returns Promise<FetchResponse<T>>

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

    Example

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

    await index.fetch(['record-1', 'record-2']);

    Throws

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

    Throws

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

listPaginated

  • 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

    • Optional options: ListOptions

      The ListOptions for the operation.

    Returns Promise<ListResponse>

    • A promise that resolves with the ListResponse when the operation is completed.

    Example

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

    const index = pc.index('my-index').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.

    Throws

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

    Throws

    PineconeArgumentError when invalid arguments are passed.

namespace

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

    Returns Index<T>

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

    Example

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

query

  • 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

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

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

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

    Throws

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

    Throws

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

update

  • Update a record in the index by id.

    Parameters

    Returns Promise<void>

    A promise that resolves when the update is completed.

    Example

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

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

    Throws

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

    Throws

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

upsert

  • Upsert records to the index.

    Parameters

    Returns Promise<void>

    A promise that resolves when the upsert is completed.

    Example

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

    await index.upsert([{
     id: 'record-1',
     values: [0.176, 0.345, 0.263],
    },{
     id: 'record-2',
     values: [0.176, 0.345, 0.263],
    }])

    Throws

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

    Throws

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

Settings

Member Visibility

Theme

On This Page