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.
usage.egressBytes is the billed size of the response in bytes, when the server reports it.
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, usage information, and pagination.next when
another page is available. usage.egressBytes is the billed size of the response in bytes,
when the server reports it.
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. usage.egressBytes is the billed size of the response in bytes, when the
server reports it.
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, usage information, and
pagination.next when another page is available. usage.egressBytes is the billed size of the
response in bytes, when the server reports it.
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.
usage.egressBytes is the billed size of the response in bytes, when the server reports it.
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.
usage.egressBytes is the billed size of the response in bytes, when the server reports it.
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);
Documents.search for schema-based search, including text queries on fields with integrated embedding; Index.searchRecords to search and rerank a legacy integrated index.
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. usage.egressBytes is the
billed size of the response in bytes, when the server reports it.
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 to search a legacy integrated index; Index.query for vector similarity queries.
Use Documents.search through index.documents.search().
Search records with text, a vector, or an existing record ID (legacy Records API).
Text queries require a legacy integrated index, created with Indexes.createForModel. To search a document index with integrated embedding, use Documents.search.
A query with topK, optional result fields, reranking settings, and a
namespace override.
Ranked hits in result.hits and usage information. usage.egressBytes is the billed
size of the response in bytes, when the server reports it.
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. On an index with
integrated embedding, usage.embedTotalTokens counts the tokens Pinecone embedded for the
update; usage is omitted when the request embedded nothing.
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' } }],
});
Documents.upsert to have Pinecone embed text, on a document index with integrated embedding; 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. On an index with integrated
embedding, usage.embedTotalTokens counts the tokens Pinecone embedded for the write;
usage is omitted when the request embedded nothing.
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; IntegratedEmbeddingStringField to have Pinecone embed a field's text; Index.upsertRecords to write to a legacy integrated index.
Use Documents.upsert through index.documents.upsert().
Write text records to a legacy integrated index (legacy Records API).
A legacy integrated index, created with Indexes.createForModel, embeds the text field
named in its field map. The example assumes the index maps its embedding input to
chunk_text. For a new index, declare embed or sparseEmbed on a string field and write
through Documents.upsert instead.
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