@mastra/pinecone 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/dist/docs/references/reference-vectors-pinecone.md

@@ -0,0 +1,168 @@
+# Pinecone Vector Store
+
+The PineconeVector class provides an interface to [Pinecone](https://www.pinecone.io/)'s vector database. It provides real-time vector search, with features like hybrid search, metadata filtering, and namespace management.
+
+## Constructor Options
+
+The constructor accepts all [Pinecone configuration options](https://docs.pinecone.io/reference/typescript-sdk) plus Mastra-specific fields.
+
+**id:** (`string`): Unique identifier for this vector store instance
+
+**apiKey:** (`string`): Pinecone API key
+
+**controllerHostUrl?:** (`string`): Custom Pinecone controller host URL
+
+**additionalHeaders?:** (`Record<string, string>`): Additional HTTP headers to include in requests
+
+**sourceTag?:** (`string`): Source tag for request tracking
+
+**cloud?:** (`'aws' | 'gcp' | 'azure'`): Cloud provider for new index creation (Default: `aws`)
+
+**region?:** (`string`): Region for new index creation (Default: `us-east-1`)
+
+## Methods
+
+### createIndex()
+
+**indexName:** (`string`): Name of the index to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search. Use 'dotproduct' if you plan to use hybrid search. (Default: `cosine`)
+
+### upsert()
+
+**indexName:** (`string`): Name of your Pinecone index
+
+**vectors:** (`number[][]`): Array of dense embedding vectors
+
+**sparseVectors?:** (`{ indices: number[], values: number[] }[]`): Array of sparse vectors for hybrid search. Each vector must have matching indices and values arrays.
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
+**namespace?:** (`string`): Optional namespace to store vectors in. Vectors in different namespaces are isolated from each other.
+
+### query()
+
+**indexName:** (`string`): Name of the index to query
+
+**queryVector:** (`number[]`): Dense query vector to find similar vectors
+
+**sparseVector?:** (`{ indices: number[], values: number[] }`): Optional sparse vector for hybrid search. Must have matching indices and values arrays.
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters for the query
+
+**includeVector?:** (`boolean`): Whether to include the vector in the result (Default: `false`)
+
+**namespace?:** (`string`): Optional namespace to query vectors from. Only returns results from the specified namespace.
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+}
+```
+
+### deleteIndex()
+
+**indexName:** (`string`): Name of the index to delete
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id?:** (`string`): ID of the vector to update (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+
+**namespace?:** (`string`): Optional namespace for the update operation
+
+**update:** (`object`): Update parameters
+
+**update.vector?:** (`number[]`): New vector values to update
+
+**update.metadata?:** (`Record<string, any>`): New metadata to update
+
+### deleteVector()
+
+**indexName:** (`string`): Name of the index containing the vector
+
+**id:** (`string`): ID of the vector to delete
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+**indexName:** (`string`): Name of the index containing the vectors to delete
+
+**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+
+**filter?:** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
+
+**namespace?:** (`string`): Optional namespace for the deletion operation
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[] // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: 'index_name',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details) // Additional error context
+  }
+}
+```
+
+### Environment Variables
+
+Required environment variables:
+
+- `PINECONE_API_KEY`: Your Pinecone API key
+
+## Hybrid Search
+
+Pinecone supports hybrid search by combining dense and sparse vectors. To use hybrid search:
+
+1. Create an index with `metric: 'dotproduct'`
+2. During upsert, provide sparse vectors using the `sparseVectors` parameter
+3. During query, provide a sparse vector using the `sparseVector` parameter
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/dist/index.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 var error = require('@mastra/core/error');
+var storage = require('@mastra/core/storage');
 var vector = require('@mastra/core/vector');
 var pinecone = require('@pinecone-database/pinecone');
 var filter = require('@mastra/core/vector/filter');
@@ -86,25 +87,19 @@ var PineconeFilterTranslator = class extends filter.BaseFilterTranslator {
 // src/vector/index.ts
 var PineconeVector = class extends vector.MastraVector {
   client;
+  cloud;
+  region;
   /**
    * Creates a new PineconeVector client.
-   * @param apiKey - The API key for Pinecone.
-   * @param environment - The environment for Pinecone.
+   *
+   * @param config - Configuration options for the Pinecone client.
+   * @see {@link PineconeVectorConfig} for all available options.
    */
-  constructor({ apiKey, environment }) {
-    super();
-    const opts = { apiKey };
-    if (environment) {
-      opts["controllerHostUrl"] = environment;
-    }
-    const baseClient = new pinecone.Pinecone(opts);
-    const telemetry = this.__getTelemetry();
-    this.client = telemetry?.traceClass(baseClient, {
-      spanNamePrefix: "pinecone-vector",
-      attributes: {
-        "vector.type": "pinecone"
-      }
-    }) ?? baseClient;
+  constructor({ id, cloud, region, ...pineconeConfig }) {
+    super({ id });
+    this.client = new pinecone.Pinecone(pineconeConfig);
+    this.cloud = cloud || "aws";
+    this.region = region || "us-east-1";
   }
   get indexSeparator() {
     return "-";
@@ -120,7 +115,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (validationError) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_CREATE_INDEX_INVALID_ARGS",
+          id: storage.createVectorErrorId("PINECONE", "CREATE_INDEX", "INVALID_ARGS"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.USER,
           details: { indexName, dimension, metric }
@@ -135,8 +130,8 @@ var PineconeVector = class extends vector.MastraVector {
         metric,
         spec: {
           serverless: {
-            cloud: "aws",
-            region: "us-east-1"
+            cloud: this.cloud,
+            region: this.region
           }
         }
       });
@@ -148,7 +143,7 @@ var PineconeVector = class extends vector.MastraVector {
       }
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_CREATE_INDEX_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "CREATE_INDEX", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: { indexName, dimension, metric }
@@ -183,7 +178,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_UPSERT_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "UPSERT", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: { indexName, vectorCount: vectors.length }
@@ -205,6 +200,15 @@ var PineconeVector = class extends vector.MastraVector {
     namespace,
     sparseVector
   }) {
+    if (!queryVector) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "QUERY", "MISSING_VECTOR"),
+        text: "queryVector is required for Pinecone queries. Metadata-only queries are not supported by this vector store.",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
     const index = this.client.Index(indexName).namespace(namespace || "");
     const translatedFilter = this.transformFilter(filter) ?? void 0;
     const queryParams = {
@@ -228,7 +232,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_QUERY_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "QUERY", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: { indexName, topK }
@@ -244,7 +248,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_LIST_INDEXES_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "LIST_INDEXES", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY
         },
@@ -272,7 +276,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_DESCRIBE_INDEX_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "DESCRIBE_INDEX", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: { indexName }
@@ -287,7 +291,7 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_DELETE_INDEX_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "DELETE_INDEX", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
           details: { indexName }
@@ -298,42 +302,102 @@ var PineconeVector = class extends vector.MastraVector {
   }
   /**
    * Updates a vector by its ID with the provided vector and/or metadata.
-   * @param indexName - The name of the index containing the vector.
-   * @param id - The ID of the vector to update.
-   * @param update - An object containing the vector and/or metadata to update.
-   * @param update.vector - An optional array of numbers representing the new vector.
-   * @param update.metadata - An optional record containing the new metadata.
-   * @param namespace - The namespace of the index (optional).
+   * Note: Pinecone only supports update by ID, not by filter.
+   * @param params - Parameters containing the id for targeting the vector to update
+   * @param params.indexName - The name of the index containing the vector.
+   * @param params.id - The ID of the vector to update.
+   * @param params.update - An object containing the vector and/or metadata to update.
+   * @param namespace - The namespace of the index (optional, Pinecone-specific).
    * @returns A promise that resolves when the update is complete.
    * @throws Will throw an error if no updates are provided or if the update operation fails.
    */
-  async updateVector({ indexName, id, update, namespace }) {
+  async updateVector(params) {
+    const { indexName, update } = params;
+    if ("id" in params && params.id && "filter" in params && params.filter) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "UPDATE_VECTOR", "MUTUALLY_EXCLUSIVE"),
+        text: "Cannot specify both id and filter - they are mutually exclusive",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
+    if (!("id" in params && params.id) && !("filter" in params && params.filter)) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "UPDATE_VECTOR", "NO_TARGET"),
+        text: "Either id or filter must be provided",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
     if (!update.vector && !update.metadata) {
       throw new error.MastraError({
-        id: "STORAGE_PINECONE_VECTOR_UPDATE_VECTOR_INVALID_ARGS",
+        id: storage.createVectorErrorId("PINECONE", "UPDATE_VECTOR", "NO_PAYLOAD"),
         domain: error.ErrorDomain.STORAGE,
         category: error.ErrorCategory.USER,
         text: "No updates provided",
-        details: { indexName, id }
+        details: { indexName }
       });
     }
+    const namespace = params.namespace;
     try {
       const index = this.client.Index(indexName).namespace(namespace || "");
-      const updateObj = { id };
-      if (update.vector) {
-        updateObj.values = update.vector;
-      }
-      if (update.metadata) {
-        updateObj.metadata = update.metadata;
+      if ("id" in params && params.id) {
+        const updateObj = { id: params.id };
+        if (update.vector) {
+          updateObj.values = update.vector;
+        }
+        if (update.metadata) {
+          updateObj.metadata = update.metadata;
+        }
+        await index.update(updateObj);
+      } else if ("filter" in params && params.filter) {
+        if (Object.keys(params.filter).length === 0) {
+          throw new error.MastraError({
+            id: storage.createVectorErrorId("PINECONE", "UPDATE_VECTOR", "EMPTY_FILTER"),
+            text: "Filter cannot be an empty filter object",
+            domain: error.ErrorDomain.STORAGE,
+            category: error.ErrorCategory.USER,
+            details: { indexName }
+          });
+        }
+        const translatedFilter = this.transformFilter(params.filter);
+        if (translatedFilter) {
+          const stats = await this.describeIndex({ indexName });
+          const dummyVector = new Array(stats.dimension).fill(1 / Math.sqrt(stats.dimension));
+          const results = await index.query({
+            vector: dummyVector,
+            topK: 1e4,
+            filter: translatedFilter,
+            includeMetadata: false,
+            includeValues: false
+          });
+          const idsToUpdate = results.matches.map((m) => m.id);
+          for (const id of idsToUpdate) {
+            const updateObj = { id };
+            if (update.vector) {
+              updateObj.values = update.vector;
+            }
+            if (update.metadata) {
+              updateObj.metadata = update.metadata;
+            }
+            await index.update(updateObj);
+          }
+        }
       }
-      await index.update(updateObj);
     } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_UPDATE_VECTOR_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "UPDATE_VECTOR", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName, id }
+          details: {
+            indexName,
+            ..."id" in params && params.id && { id: params.id },
+            ..."filter" in params && params.filter && { filter: JSON.stringify(params.filter) }
+          }
         },
         error$1
       );
@@ -354,10 +418,100 @@ var PineconeVector = class extends vector.MastraVector {
     } catch (error$1) {
       throw new error.MastraError(
         {
-          id: "STORAGE_PINECONE_VECTOR_DELETE_VECTOR_FAILED",
+          id: storage.createVectorErrorId("PINECONE", "DELETE_VECTOR", "FAILED"),
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.THIRD_PARTY,
-          details: { indexName, id }
+          details: {
+            indexName,
+            ...id && { id }
+          }
+        },
+        error$1
+      );
+    }
+  }
+  /**
+   * Deletes multiple vectors by IDs or filter.
+   * @param indexName - The name of the index containing the vectors.
+   * @param ids - Array of vector IDs to delete (mutually exclusive with filter).
+   * @param filter - Filter to match vectors to delete (mutually exclusive with ids).
+   * @param namespace - The namespace of the index (optional, Pinecone-specific).
+   * @returns A promise that resolves when the deletion is complete.
+   * @throws Will throw an error if both ids and filter are provided, or if neither is provided.
+   */
+  async deleteVectors(params) {
+    const { indexName, filter, ids } = params;
+    const namespace = params.namespace;
+    if (ids && filter) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "DELETE_VECTORS", "MUTUALLY_EXCLUSIVE"),
+        text: "Cannot specify both ids and filter - they are mutually exclusive",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
+    if (!ids && !filter) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "DELETE_VECTORS", "NO_TARGET"),
+        text: "Either filter or ids must be provided",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
+    if (ids && ids.length === 0) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "DELETE_VECTORS", "EMPTY_IDS"),
+        text: "Cannot delete with empty ids array",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
+    if (filter && Object.keys(filter).length === 0) {
+      throw new error.MastraError({
+        id: storage.createVectorErrorId("PINECONE", "DELETE_VECTORS", "EMPTY_FILTER"),
+        text: "Cannot delete with empty filter object",
+        domain: error.ErrorDomain.STORAGE,
+        category: error.ErrorCategory.USER,
+        details: { indexName }
+      });
+    }
+    try {
+      const index = this.client.Index(indexName).namespace(namespace || "");
+      if (ids) {
+        await index.deleteMany(ids);
+      } else if (filter) {
+        const translatedFilter = this.transformFilter(filter);
+        if (translatedFilter) {
+          const stats = await this.describeIndex({ indexName });
+          const dummyVector = new Array(stats.dimension).fill(1 / Math.sqrt(stats.dimension));
+          const results = await index.query({
+            vector: dummyVector,
+            topK: 1e4,
+            filter: translatedFilter,
+            includeMetadata: false,
+            includeValues: false
+          });
+          const idsToDelete = results.matches.map((m) => m.id);
+          if (idsToDelete.length > 0) {
+            await index.deleteMany(idsToDelete);
+          }
+        }
+      }
+    } catch (error$1) {
+      if (error$1 instanceof error.MastraError) throw error$1;
+      throw new error.MastraError(
+        {
+          id: storage.createVectorErrorId("PINECONE", "DELETE_VECTORS", "FAILED"),
+          domain: error.ErrorDomain.STORAGE,
+          category: error.ErrorCategory.THIRD_PARTY,
+          details: {
+            indexName,
+            ...filter && { filter: JSON.stringify(filter) },
+            ...ids && { idsCount: ids.length }
+          }
         },
         error$1
       );