DOCSEARCHbyAlgolia
Submit Docs

Pinecone TypeScript SDK

repository·main·Indexed 42 days ago

https://github.com/pinecone-io/pinecone-ts-client

The official TypeScript SDK for Pinecone (v9.0.0), used to build full-text and vector search applications. It provides tools for managing serverless and pod-based indexes, performing data operations (upsert, query, fetch, update, delete), and utilizing the Inference API for embeddings and reranking. It also includes support for Pinecone Assistant for conversational AI, chat operations, and file management.

Tokens
81.9K
Snippets
245
Records
332
Agent score
55%

What's inside Pinecone

  1. Overview of Pinecone TypeScript SDK capabilities

    main

    The Pinecone TypeScript SDK provides a comprehensive suite of tools for managing vector databases and performing advanced search operations. Key functional areas include:

    • Index Management: Creating and managing serverless indexes, pod-based indexes, collections, and backups (including scheduled backups).
    • Data Operations: Managing documents and vectors (upsert, query, fetch, update, delete), utilizing namespaces for organization, applying metadata filtering, and performing bulk imports from object storage.
    • Inference: Accessing standalone embedding and reranking models via the Inference API, or using integrated inference directly within your indexes.
    • Assistant: Using Pinecone Assistant for chat operations (including streaming), context retrieval, and file management.
    • TypeScript Support: Leveraging generic metadata types for type-safe operations, async/await patterns, and structured error handling.

  2. Understand v1 terminology changes (Vector vs Record)

    main

    In v1.x, terminology has shifted from vector to record to align with official Pinecone documentation. This affects several types and response fields:

    • Types:
      • Vector is replaced by PineconeRecord.
      • ScoredVector is replaced by ScoredPineconeRecord.
    • Response Fields:
      • fetch() returns records instead of vectors.
      • describeIndexStats() returns totalRecordCount instead of totalVectorCount.

  3. Perform vector operations on an index

    main

    To perform data plane operations (like fetch, query, upsert), you must first target an index using the index() method. The SDK automatically resolves the correct host for the specified index name.

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

// Target the index
const index = pc.index('my-index');

// Perform operations
await index.fetch(['1', '2', '3']);

  4. Use Inference and Pinecone Assistant

    main

    The SDK provides high-level abstractions for AI-driven workflows:

    • Inference API: Use standalone models for generating embeddings or performing reranking.
    • Integrated Inference: Use embedding and reranking models that are natively integrated into your Pinecone indexes.
    • Pinecone Assistant: A specialized interface for conversational AI. It supports:
      • Chat Operations: Standard chat, streaming responses, and context retrieval.
      • File Management: Uploading, listing, and managing files used as context for the Assistant.

  5. Catch specific Pinecone error types

    main

    The SDK provides a hierarchy of error classes under the Errors namespace. You can use instanceof checks to identify specific failure modes and implement custom recovery logic. Common error types include:

    • Errors.PineconeConflictError: Occurs when an operation conflicts with the current state (e.g., trying to create an index that already exists).
    • Errors.PineconeConnectionError: Occurs when the client cannot connect to the Pinecone service.
    • Errors.PineconeValidationError: Occurs when request parameters do not meet requirements.
    • Errors.PineconeRequestError: Occurs when the server returns an error response.
    • Errors.PineconeConfigurationError: Occurs when there is an issue with the client configuration.

  6. Use Vector vs. Document operations based on index schema

    main

    The available data-plane methods depend on your index's schema configuration:

    1. Vector Indexes: Use reserved _values or _sparse_values schema fields. Supported methods include upsert, query, fetch, update, delete*, listPaginated, and describeIndexStats on the Index object.
    2. Document Indexes: Use indexes with custom named schema fields. These require using the documents accessor (e.g., index.documents.upsert). Supported methods are upsert, search, fetch, update, list, and delete, all scoped by .namespace().

    Calling a method that the index's schema does not support will return a server error.

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

// Vector operations, supported for new and existing vector indexes
const vectorIndex = pc.index('my-vector-index');
await vectorIndex.upsert({
  records: [{ id: 'a', values: [0.1, 0.2, 0.3] }],
});

// Document operations, for indexes with custom named schema fields
const documentIndex = pc.index('my-schema-index');
await documentIndex.namespace('my-namespace').documents.upsert({
  documents: [{ _id: 'doc-1', chunk_text: 'hello world' }],
});

  7. Perform data operations with vectors and documents

    main

    You can manipulate data within your Pinecone indexes using the following patterns:

    • Vectors: Perform standard CRUD and search operations including upsert, query, fetch, update, and delete.
    • Documents: Store, search, fetch, update, and delete documents (useful for full-text and integrated search).
    • Namespacing: Organize your vectors and documents into isolated logical partitions using Namespaces.
    • Metadata Filtering: Apply advanced filtering to your queries using metadata operators.
    • Bulk Import: Use the bulk import feature to ingest large datasets directly from object storage.

  8. How the mocked critical-path gate works

    main

    The mocked smoke gate (mockedCriticalPath.test.ts) uses a mocked HTTP transport to test the core SDK lifecycle: connect → upsert → query.

    To inject a mock at the transport layer, you use the PineconeConfiguration.fetchApi property. This allows testing of all logic above the fetch call, including configuration resolution, host caching, request building, and response deserialization, without needing a real API key.

  10. Performance considerations for metadata filtering

    main

    To optimize filtering performance, follow these best practices:

    1. Index metadata fields: For serverless indexes, use metadata schema configuration to index only the fields you intend to filter on.
    2. Pod-based indexes: For pod-based indexes, configure metadataConfig with indexed fields for high-cardinality metadata.
    3. Selective filtering: Filters that are more selective (returning fewer matching vectors) generally perform better.
    4. Avoid negation: Using negation operators like $ne and $nin may be less efficient than using positive filters (like $eq or $in).

  12. Maintain conversation context

    main

    To create a multi-turn conversation, you must manually include the previous messages (both user and assistant roles) in the messages array of subsequent chat calls.

    // 1. First turn
const response1 = await assistant.chat({
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
});
const previousAnswer = response1.message?.content;

// 2. Second turn (including history)
const response2 = await assistant.chat({
  messages: [
    { role: 'user', content: 'What is the capital of France?' },
    { role: 'assistant', content: previousAnswer },
    { role: 'user', content: 'What is the population of that city?' },
  ],
});