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

T extends RecordMetadata = RecordMetadata

The type of metadata associated with each record.

Hierarchy

Index

Index

Constructors

constructor

Methods

cancelImport deleteAll deleteMany deleteOne describeImport describeIndexStats fetch listImports listPaginated namespace query startImport update upsert

Constructors

constructor

new Index<T>(indexName, config, namespace?, indexHostUrl?, additionalHeaders?): Index<T>
Instantiation of Index is handled by Pinecone
Type Parameters
- T extends RecordMetadata = RecordMetadata
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');
```
- Defined in src/data/index.ts:185

Methods

cancelImport

cancelImport(id): Promise<object>

Cancel a specific import operation.

Parameters

id: string

The id of the import operation to cancel.

Returns Promise<object>

Example

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

// {}

deleteAll

deleteAll(): Promise<void>

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

deleteMany(options): Promise<void>
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: DeleteManyOptions
  
  An array of record id values or a filter object.
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.
- Defined in src/data/index.ts:314

deleteOne

deleteOne(id): Promise<void>
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.
- Defined in src/data/index.ts:334

describeImport

describeImport(id): Promise<ImportModel>

Return details of a specific import operation.

Parameters

id: string

The id of the import operation to describe.

Returns Promise<ImportModel>

Example

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index('my-serverless-index');
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
// }

describeIndexStats

describeIndexStats(): Promise<IndexStatsDescription>
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.
- Defined in src/data/index.ts:362

fetch

fetch(options): Promise<FetchResponse<T>>
Fetch records from the index.
Parameters
- options: FetchOptions
  
  The FetchOptions for the operation.
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.
- Defined in src/data/index.ts:491

listImports

listImports(limit?, paginationToken?): Promise<ListImportsResponse>

List all recent and ongoing import operations.

Parameters

Optional limit: number

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

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

Returns Promise<ListImportsResponse>

Example

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

// {
//  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.
// }

listPaginated

listPaginated(options?): Promise<ListResponse>
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.
- Defined in src/data/index.ts:408

namespace

namespace(namespace): Index<T>
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.
- Defined in src/data/index.ts:439

query

query(options): Promise<QueryResponse<T>>
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
- options: QueryOptions
  
  The QueryOptions for the operation.
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.
- Defined in src/data/index.ts:517

startImport

startImport(uri, errorMode?, integration?): Promise<StartImportResponse>
Start an asynchronous import of vectors from object storage into a Pinecone Serverless index.
Parameters
- uri: string
  
  (Required) The URI prefix under which the data to import is available. All data within this prefix will be listed then imported into the target index. Currently only s3:// URIs are supported.
- Optional errorMode: string
  
  (Optional) Defaults to "Continue". If set to "Continue", the import operation will continue even if some records fail to import. To inspect failures in "Continue" mode, send a request to listImports. Pass "Abort" to stop the import operation if any records fail to import.
- Optional integration: string
  
  (Optional) The name of the storage integration that should be used to access the data. Defaults to None.
Returns Promise<StartImportResponse>
Example
```
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index('my-serverless-index');
console.log(await index.startImport('s3://my-bucket/my-data'));

// {"id":"1"}
```
- Defined in src/data/index.ts:566

update

update(options): Promise<void>
Update a record in the index by id.
Parameters
- options: UpdateOptions<T>
  
  The UpdateOptions for the operation.
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.
- Defined in src/data/index.ts:541

upsert

upsert(data): Promise<void>
Upsert records to the index.
Parameters
- data: PineconeRecord<T>[]
  
  An array of PineconeRecord objects to upsert.
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.
- Defined in src/data/index.ts:471

Class Index<T>

Targeting an index, with user-defined Metadata types

Type Parameters

T extends RecordMetadata = RecordMetadata

Hierarchy

Index

Constructors

Methods

Constructors

constructor

Type Parameters

T extends RecordMetadata = RecordMetadata

Parameters

indexName: string

config: PineconeConfiguration

namespace: string = ''

Optional indexHostUrl: string

Optional additionalHeaders: HTTPHeaders

Returns Index<T>

Example

Methods

cancelImport

Parameters

id: string

Returns Promise<object>

Example

deleteAll

Returns Promise<void>

Example

Throws

deleteMany

Parameters

options: DeleteManyOptions

Returns Promise<void>

Example

Throws

Throws

deleteOne

Parameters

id: string

Returns Promise<void>

Example

Throws

Throws

describeImport

Parameters

id: string

Returns Promise<ImportModel>

Example

describeIndexStats

Returns Promise<IndexStatsDescription>

Example

Throws

fetch

Parameters

options: FetchOptions

Returns Promise<FetchResponse<T>>

Example

Throws

Throws

listImports

Parameters

Optional limit: number

Optional paginationToken: string

Returns Promise<ListImportsResponse>

Example

listPaginated

Parameters

Optional options: ListOptions

Returns Promise<ListResponse>

Example

Throws

Throws

namespace

Parameters

namespace: string

Returns Index<T>

Example

query

Parameters

`Optional` indexHostUrl: string

`Optional` additionalHeaders: HTTPHeaders

`Optional` limit: number

`Optional` paginationToken: string

`Optional` options: ListOptions

`Optional` errorMode: string

`Optional` integration: string