Metadata fields stored with vector records; omitted for flexible metadata.
Document operations for a schema-based index, scoped to this client's namespace.
Request cancellation of an import operation.
The import ID returned by Index.startImport or Index.listImports.
The cancellation response.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const page = await index.listImports();
const pending = page.data?.find((operation) => operation.status === 'Pending');
if (pending) {
await index.cancelImport(pending.id);
}
Index.describeImport to check the operation status.
Create a namespace with an optional metadata schema.
Supported for serverless indexes.
A namespace name, such as products-fr, and optional metadata fields to make
filterable.
The namespace description, including its name and record count.
Errors.PineconeArgumentError when the namespace name is empty or missing.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const namespace = await index.createNamespace({ name: 'products-fr' });
console.log(namespace.name);
Index.namespace to target a namespace with a client.
Delete all records in one namespace.
Records in other namespaces are unaffected.
Optionaloptions: DeleteAllOptions
Override the configured namespace; omit to use this client's namespace.
Resolves when the delete request succeeds.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.deleteAll();
Index.deleteMany to select records by IDs or metadata.
Delete schema-based documents by IDs, filter, or an entire namespace.
deleteAll: true removes all documents in this client's namespace.
Exactly one of non-empty ids, filter, or deleteAll: true.
The number of documents matched by the request in matchedRecords.
Errors.PineconeArgumentError when the selection is missing or invalid.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
const result = await index.documents.delete({ ids: ['trail-shoe-42'] });
console.log(result.matchedRecords);
Index.deleteMany for vector records.
Use Documents.delete through index.documents.delete().
Delete records selected by IDs or a metadata filter.
Provide either ids, such as ['trail-shoe-42'], or filter, and optionally
a namespace override.
Resolves when the delete request succeeds.
Errors.PineconeArgumentError when the record selection is missing or invalid.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.deleteMany({ ids: ['trail-shoe-42', 'trail-shoe-43'] });
Index.deleteAll to remove every record in a namespace.
Permanently delete a namespace and all its records.
Supported for serverless indexes. This operation is irreversible.
The namespace name, such as retired-products.
Resolves when the deletion request succeeds.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.deleteNamespace('retired-products');
Index.deleteMany to remove selected records.
Delete a record by ID.
The record ID, such as trail-shoe-42, and an optional namespace override.
Resolves when the delete request succeeds.
Errors.PineconeArgumentError when id is empty or missing.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.deleteOne({ id: 'trail-shoe-42' });
Index.deleteMany to delete multiple records.
Get the status and progress of an import operation.
The import ID returned by Index.startImport.
Import details, including status, percentComplete, and recordsImported.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const operation = await index.startImport({ uri: 's3://product-data/catalog-import' });
const progress = await index.describeImport(operation.id);
console.log(progress.status, progress.recordsImported);
Index.listImports to find import IDs.
Get record counts and dimensions for the index.
Optionaloptions: DescribeIndexStatsOptions
A metadata filter to restrict the statistics; omit for statistics across the index.
Index statistics, including namespaces with per-namespace counts and
totalRecordCount.
Get a namespace's name, record count, and schema when available.
Supported for serverless indexes.
The namespace name, such as products-en.
The namespace description.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const details = await index.describeNamespace('products-en');
console.log(details.recordCount);
Index.listNamespaces to discover namespace names.
Fetch vector records by ID.
Non-empty record IDs, such as ['trail-shoe-42'], and an optional namespace
override.
Records keyed by ID in records, the namespace, and usage information when available.
Errors.PineconeArgumentError when ids is missing or empty.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const result = await index.fetch({ ids: ['trail-shoe-42'] });
console.log(result.records['trail-shoe-42']);
Index.fetchByMetadata to select records with a filter; Documents.fetch for schema-based documents.
Fetch one page of vector records matching a metadata filter.
The metadata filter, optional page size and continuation token, and namespace override.
Records keyed by ID, the namespace, and pagination.next when another page is
available.
Errors.PineconeArgumentError when filter is missing.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const page = await index.fetchByMetadata({ filter: { category: { $eq: 'footwear' } } });
console.log(page.records);
Index.fetch to retrieve records by ID.
Fetch schema-based documents by IDs or a metadata filter.
Fetching by filter returns one page at a time.
Either non-empty ids or filter; use paginationToken only with a filter.
Documents keyed by ID in documents, the namespace, usage, and a continuation token
when available.
Errors.PineconeArgumentError when the selection is missing or invalid, or pagination is requested without a filter.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
const result = await index.documents.fetch({ ids: ['trail-shoe-42'] });
console.log(result.documents['trail-shoe-42']);
Documents.list to list document IDs; Index.fetch for vector records.
Use Documents.fetch through index.documents.fetch().
List one page of document IDs in the targeted namespace.
An optional ID prefix, page size, and continuation token; defaults to the first unfiltered page.
Document entries in documents, ordered by ID, and pagination.next when another
page is available.
Errors.PineconeArgumentError when limit is less than 1.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
const page = await index.documents.list({ prefix: 'trail-shoe-' });
console.log(page.documents);
Documents.fetch to retrieve document fields; Index.listPaginated for vector record IDs.
Use Documents.list through index.documents.list().
List one page of recent and ongoing import operations.
Optionallimit: number
Maximum operations per page, such as 10; omit for the service default.
OptionalpaginationToken: string
The previous response's pagination.next; omit for the first page.
Import operations in data and pagination.next when another page is available.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const page = await index.listImports(10);
console.log(page.data);
Index.describeImport for one import's progress.
List one page of namespaces in the index.
Supported for serverless indexes.
Optionaloptions: ListNamespacesOptions
An optional name prefix, page size, and continuation token; omit for the first unfiltered page.
Namespace descriptions in namespaces and pagination.next when another page is
available.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const page = await index.listNamespaces({ prefix: 'products-' });
console.log(page.namespaces);
Index.describeNamespace for one namespace.
List one page of record IDs in a namespace.
Supported for serverless indexes.
Optionaloptions: ListOptions
An ID prefix, page size, continuation token, or namespace override; omit for the first unfiltered page.
Record IDs in vectors and pagination.next when another page is available.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const page = await index.listPaginated({ prefix: 'trail-shoe-' });
console.log(page.vectors);
if (page.pagination?.next) {
const nextPage = await index.listPaginated({
prefix: 'trail-shoe-', paginationToken: page.pagination.next,
});
console.log(nextPage.vectors);
}
Index.fetch to retrieve values and metadata for known IDs.
Create a client scoped to a namespace in the same index.
Record operations use this namespace unless their options override it. Index-wide operations, such as listing namespaces or describing index statistics, still apply to the whole index.
The namespace to target, such as products-fr.
An Index preserving this client's metadata type and configuration.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const frenchProducts = index.namespace('products-fr');
const result = await frenchProducts.fetch({ ids: ['trail-shoe-42'] });
console.log(result.records);
Index.createNamespace to create a namespace explicitly.
Find vector records most similar to a query vector or an existing record.
The result count topK and either id or vector, with optional filtering
and returned values or metadata.
Matches ordered by similarity, the namespace, and usage information when available.
Errors.PineconeArgumentError when query values, filters, or search tuning options fail validation.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const result = await index.query({
id: 'trail-shoe-42', topK: 5, includeMetadata: true,
});
console.log(result.matches);
Index.searchRecords for text queries and reranking; Documents.search for schema-based search.
Search schema-based documents using one or more scoring methods.
Choose scoring fields and methods supported by your index schema.
Scoring methods in scoreBy, the result count topK, and optional filters
and returned fields.
Ranked matches, the namespace, and usage information.
Errors.PineconeArgumentError when scoreBy is missing or empty, or topK is
missing or less than 1.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
const result = await index.documents.search({
scoreBy: [{ type: 'text', fields: ['title'], query: 'hiking shoes' }],
topK: 5, includeFields: ['title'],
});
console.log(result.matches);
Index.searchRecords for integrated embedding search; Index.query for vector similarity queries.
Use Documents.search through index.documents.search().
Search records with text, a vector, or an existing record ID.
Text queries require an index with integrated embedding.
A query with topK, optional result fields, reranking settings, and a
namespace override.
Ranked hits in result.hits and usage information.
Errors.PineconeArgumentError when query is missing.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-search', namespace: 'products-en' });
const result = await index.searchRecords({
query: { inputs: { text: 'waterproof hiking shoes' }, topK: 5 },
fields: ['chunk_text', 'category'],
});
console.log(result.result.hits);
Index.query for vector similarity queries; Documents.search for schema-based search.
Start an asynchronous import of vectors from object storage.
Requires a serverless index. The response does not wait for the import to finish.
The import directory URI, optional storage integration, and error handling
mode (defaults to continue).
The import ID in id; use it to check progress.
Errors.PineconeArgumentError when uri is missing or errorMode is
unsupported.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
const operation = await index.startImport({ uri: 's3://product-data/catalog-import' });
console.log(operation.id);
Index.describeImport to check progress.
Update vector values or metadata on existing records.
Updating metadata leaves unspecified metadata fields and vector values unchanged.
Select a record with id to change vectors or metadata, or use filter to
change metadata on matching records; optionally override the namespace.
Resolves when the update request succeeds.
Errors.PineconeArgumentError when neither or both of id and filter are
provided.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.update({
id: 'trail-shoe-42', metadata: { category: 'hiking-footwear' },
});
Index.upsert to replace whole records; Documents.update for schema-based documents.
Partially update schema-based documents selected by IDs or a filter.
Unspecified fields are preserved. The example changes category while retaining the document's
title and other fields.
Per-ID changes in documents, or a filter with non-empty setFields and/or
removeFields.
The number of documents matched by the request in matchedRecords.
Errors.PineconeArgumentError when the selection or field changes are missing or incompatible.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
await index.documents.update({
documents: [{ _id: 'trail-shoe-42', category: 'hiking-footwear' }],
});
Documents.upsert to write documents; Index.update for vector records.
Use Documents.update through index.documents.update().
Insert vector records, replacing records with the same IDs.
The example assumes a three-dimensional dense index; use embeddings that match your index.
Records with IDs and dense or sparse values, plus an optional namespace override.
Resolves when the upsert request succeeds.
Errors.PineconeArgumentError when records are empty or a record is missing its ID or vector values.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-catalog', namespace: 'products-en' });
await index.upsert({
records: [{ id: 'trail-shoe-42', values: [0.12, 0.34, 0.56],
metadata: { category: 'footwear' } }],
});
Index.upsertRecords to embed text; Index.update for partial changes.
Write documents to a schema-based index.
A non-empty documents array; each document needs _id and fields matching
the index schema.
The number of documents written in upsertedCount.
Errors.PineconeArgumentError when documents is empty or missing.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-documents', namespace: 'products-en' });
const result = await index.documents.upsert({
documents: [{ _id: 'trail-shoe-42', title: 'Waterproof hiking shoe', category: 'footwear' }],
});
console.log(result.upsertedCount);
Documents.update for partial changes; Index.upsertRecords for integrated embedding records.
Use Documents.upsert through index.documents.upsert().
Write text records to an index with integrated embedding.
The example assumes the index maps its embedding input to chunk_text.
Records with id or _id, the text field configured in the index field map,
and optional metadata or namespace override.
Resolves when the upsert request succeeds.
Errors.PineconeArgumentError when a record has neither id nor _id.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.index({ name: 'product-search', namespace: 'products-en' });
await index.upsertRecords({
records: [{ _id: 'trail-shoe-42', chunk_text: 'Waterproof hiking shoe with a durable sole.',
category: 'footwear' }],
});
Index.upsert for precomputed vectors; Documents.upsert for schema-based documents.
A client for reading and writing records in a Pinecone index. Obtain an instance with Pinecone.index; do not construct it directly. Vector methods accept embeddings, while document methods use fields declared in a schema-based index.
Example