AlphaAlpha
Deletes documents from a namespace by their IDs, or deletes all documents in the namespace.
Exactly one of ids or deleteAll must be set.
The namespace to delete documents from.
The PreviewDeleteDocumentsOptions: either ids (a non-empty list of document IDs) or deleteAll: true. These options are mutually exclusive.
A promise that resolves when the deletion is complete.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
// Delete specific documents by ID
await index.deleteDocuments('my-namespace', { ids: ['doc-1', 'doc-2'] });
// Delete all documents in the namespace
await index.deleteDocuments('my-namespace', { deleteAll: true });
Errors.PineconeArgumentError when neither ids nor deleteAll is set, both are set at the same time, or ids is an empty array.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Alpha
Fetches documents from a namespace by their IDs.
The namespace to fetch documents from.
The PreviewFetchDocumentsOptions containing ids (required) and an optional includeFields list to limit which fields are returned.
A promise that resolves to a PreviewFetchDocumentsResponse containing a documents map, namespace, and usage.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
// Fetch all fields
const result = await index.fetchDocuments('my-namespace', {
ids: ['doc-1', 'doc-2'],
});
console.log(result);
// {
// documents: {
// 'doc-1': { _id: 'doc-1', chunk_text: 'Machine learning is fascinating' },
// 'doc-2': { _id: 'doc-2', chunk_text: 'Vector databases enable semantic search' },
// },
// namespace: 'my-namespace',
// usage: { read_units: 1 }
// }
// Fetch only specific fields
const partial = await index.fetchDocuments('my-namespace', {
ids: ['doc-1'],
includeFields: ['chunk_text'],
});
Errors.PineconeArgumentError when ids is empty or not provided.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Alpha
Lists documents in a namespace, returning their IDs in sorted order.
Returns up to 100 documents per page by default. Use prefix to limit
results to documents whose IDs start with a given string, and limit to
control the page size. When more documents remain, the response includes a
pagination.next token you can pass back as paginationToken to retrieve
the next page. When no token is returned, there are no more documents.
The namespace to list documents from.
The optional PreviewListDocumentsOptions: prefix to filter by ID prefix, limit to set the page size, and paginationToken to fetch a subsequent page.
A promise that resolves to a PreviewListDocumentsResponse containing documents, an optional pagination token, namespace, and usage.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
// List the first page of documents
const page = await index.listDocuments('my-namespace', { limit: 50 });
console.log(page);
// {
// documents: [{ _id: 'doc-1' }, { _id: 'doc-2' }],
// pagination: { next: 'eyJ...' },
// namespace: 'my-namespace',
// usage: { readUnits: 1 }
// }
// Retrieve the next page
const next = await index.listDocuments('my-namespace', {
paginationToken: page.pagination?.next,
});
// Only list documents whose IDs start with a prefix
const prefixed = await index.listDocuments('my-namespace', { prefix: 'doc-' });
Errors.PineconeArgumentError when limit is provided but less than 1.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Alpha
Searches for documents in a namespace using one or more scoring methods.
The scoreBy array specifies how documents are ranked. Supported scoring
method types are text (BM25), dense_vector, sparse_vector, and
query_string. Multiple scoring methods can be combined for hybrid search.
The namespace to search.
The PreviewSearchDocumentsOptions for the search, including scoreBy (required), topK (required), and optional includeFields.
A promise that resolves to a PreviewSearchDocumentsResponse containing matches, namespace, and usage.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
const results = await index.searchDocuments('my-namespace', {
scoreBy: [
{ type: 'text', field: 'chunk_text', query: 'machine learning' },
],
topK: 5,
includeFields: ['chunk_text'],
});
console.log(results);
// {
// matches: [
// { _id: 'doc-1', _score: 0.98, chunk_text: 'Machine learning is fascinating' },
// { _id: 'doc-2', _score: 0.72, chunk_text: 'Vector databases enable semantic search' },
// ],
// namespace: 'my-namespace',
// usage: { readUnits: 1 }
// }
Errors.PineconeArgumentError when scoreBy is empty or topK is less than 1.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Alpha
Applies partial updates to documents in a namespace.
Each update is identified by its _id. Any other fields set new values for
those fields, fields listed in _remove_fields are removed from the
document, and fields that are not mentioned are left unchanged. Updates to a
document that does not exist are accepted but have no effect.
The namespace to update documents in.
The PreviewUpdateDocumentsOptions containing a non-empty documents array. Each entry is a PreviewUpdateDocumentRecord with a required _id field, optional replacement fields, and an optional _remove_fields list.
A promise that resolves when the update is complete.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
await index.updateDocuments('my-namespace', {
documents: [
// Set a new value for `chunk_text` on doc-1
{ _id: 'doc-1', chunk_text: 'Updated content' },
// Remove the `category` field from doc-2
{ _id: 'doc-2', _remove_fields: ['category'] },
],
});
Errors.PineconeArgumentError when documents is empty or not provided.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Alpha
Upserts documents into a namespace of this schema-based index.
Each document must include an _id field (the unique identifier) and any
additional fields defined in the index schema. If a document with the same
_id already exists it is overwritten.
The namespace to upsert documents into.
The PreviewUpsertDocumentsOptions containing the documents array (1–1000 entries). Each entry must be a PreviewDocumentRecord with a required _id field.
A promise that resolves to a PreviewUpsertDocumentsResponse.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
const index = pc.preview.index('my-schema-index');
const result = await index.upsertDocuments('my-namespace', {
documents: [
{ _id: 'doc-1', chunk_text: 'Machine learning is fascinating' },
{ _id: 'doc-2', chunk_text: 'Vector databases enable semantic search' },
],
});
console.log(result);
// { upsertedCount: 2 }
Errors.PineconeArgumentError when documents is empty or not provided.
Errors.PineconeConnectionError when network problems or an outage of Pinecone's APIs prevent the request from being completed.
Data-plane document operations for a schema-based index. Access via
pc.preview.index('index-name').Uses Pinecone API version
2026-01.alpha. Preview surface is not covered by SemVer — signatures and behavior may change in any minor SDK release. Pin your SDK version when relying on preview features.