@mastra/duckdb 1.0.1 → 1.1.0-alpha.0

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

@@ -1,4 +1,4 @@
-# DuckDBVector Store
+# DuckDB vector store
 
 The DuckDB storage implementation provides an embedded high-performance vector search solution using [DuckDB](https://duckdb.org/), an in-process analytical database. It uses the VSS extension for vector similarity search with HNSW indexing, offering a lightweight and efficient vector database that requires no external server.
 
@@ -73,59 +73,59 @@ const results = await store.query({
 await store.close();
 ```
 
-## Constructor Options
+## Constructor options
 
-**id:** (`string`): Unique identifier for the vector store instance
+**id** (`string`): Unique identifier for the vector store instance
 
-**path?:** (`string`): Database file path. Use ':memory:' for in-memory database, or a file path like './vectors.duckdb' for persistence. (Default: `':memory:'`)
+**path** (`string`): Database file path. Use ':memory:' for in-memory database, or a file path like './vectors.duckdb' for persistence. (Default: `':memory:'`)
 
-**dimensions?:** (`number`): Default dimension for vector embeddings (Default: `1536`)
+**dimensions** (`number`): Default dimension for vector embeddings (Default: `1536`)
 
-**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Default distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Default distance metric for similarity search (Default: `cosine`)
 
 ## Methods
 
-### createIndex()
+### `createIndex()`
 
 Creates a new vector collection with optional HNSW index for fast approximate nearest neighbor search.
 
-**indexName:** (`string`): Name of the index to create
+**indexName** (`string`): Name of the index to create
 
-**dimension:** (`number`): Vector dimension size (must match your embedding model)
+**dimension** (`number`): Vector dimension size (must match your embedding model)
 
-**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
-### upsert()
+### `upsert()`
 
 Adds or updates vectors and their metadata in the index.
 
-**indexName:** (`string`): Name of the index to insert into
+**indexName** (`string`): Name of the index to insert into
 
-**vectors:** (`number[][]`): Array of embedding vectors
+**vectors** (`number[][]`): Array of embedding vectors
 
-**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+**metadata** (`Record<string, any>[]`): Metadata for each vector
 
-**ids?:** (`string[]`): Optional vector IDs (auto-generated UUIDs if not provided)
+**ids** (`string[]`): Optional vector IDs (auto-generated UUIDs if not provided)
 
-### query()
+### `query()`
 
 Searches for similar vectors with optional metadata filtering.
 
-**indexName:** (`string`): Name of the index to search in
+**indexName** (`string`): Name of the index to search in
 
-**queryVector:** (`number[]`): Query vector to find similar vectors for
+**queryVector** (`number[]`): Query vector to find similar vectors for
 
-**topK?:** (`number`): Number of results to return (Default: `10`)
+**topK** (`number`): Number of results to return (Default: `10`)
 
-**filter?:** (`Filter`): Metadata filters using MongoDB-like query syntax
+**filter** (`Filter`): Metadata filters using MongoDB-like query syntax
 
-**includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)
+**includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
 
-### describeIndex()
+### `describeIndex()`
 
 Gets information about an index.
 
-**indexName:** (`string`): Name of the index to describe
+**indexName** (`string`): Name of the index to describe
 
 Returns:
 
@@ -137,53 +137,53 @@ interface IndexStats {
 }
 ```
 
-### deleteIndex()
+### `deleteIndex()`
 
 Deletes an index and all its data.
 
-**indexName:** (`string`): Name of the index to delete
+**indexName** (`string`): Name of the index to delete
 
-### listIndexes()
+### `listIndexes()`
 
 Lists all vector indexes in the database.
 
 Returns: `Promise<string[]>`
 
-### updateVector()
+### `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
+**indexName** (`string`): Name of the index containing the vector
 
-**id?:** (`string`): ID of the vector entry to update (mutually exclusive with filter)
+**id** (`string`): ID of the vector entry to update (mutually exclusive with filter)
 
-**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
+**filter** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)
 
-**update:** (`object`): Update data containing vector and/or metadata
+**update** (`object`): Update data containing vector and/or metadata
 
-**update.vector?:** (`number[]`): New vector data to update
+**update.vector** (`number[]`): New vector data to update
 
-**update.metadata?:** (`Record<string, any>`): New metadata to update
+**update.metadata** (`Record<string, any>`): New metadata to update
 
-### deleteVector()
+### `deleteVector()`
 
 Deletes a specific vector entry from an index by its ID.
 
-**indexName:** (`string`): Name of the index containing the vector
+**indexName** (`string`): Name of the index containing the vector
 
-**id:** (`string`): ID of the vector entry to delete
+**id** (`string`): ID of the vector entry to delete
 
-### deleteVectors()
+### `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
+**indexName** (`string`): Name of the index containing the vectors to delete
 
-**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)
+**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)
+**filter** (`Record<string, any>`): Metadata filter to identify vectors to delete (mutually exclusive with ids)
 
-### close()
+### `close()`
 
 Closes the database connection and releases resources.
 
@@ -191,7 +191,7 @@ Closes the database connection and releases resources.
 await store.close()
 ```
 
-## Response Types
+## Response types
 
 Query results are returned in this format:
 
@@ -204,7 +204,7 @@ interface QueryResult {
 }
 ```
 
-## Filter Operators
+## Filter operators
 
 DuckDB vector store supports MongoDB-like filter operators:
 
@@ -239,7 +239,7 @@ const results = await store.query({
 });
 ```
 
-## Distance Metrics
+## Distance metrics
 
 | Metric       | Description       | Score Interpretation   | Best For                            |
 | ------------ | ----------------- | ---------------------- | ----------------------------------- |
@@ -247,7 +247,7 @@ const results = await store.query({
 | `euclidean`  | L2 distance       | 0-∞ (0 = most similar) | Image embeddings, spatial data      |
 | `dotproduct` | Inner product     | Higher = more similar  | When vector magnitude matters       |
 
-## Error Handling
+## Error handling
 
 The store throws specific errors for different failure cases:
 
@@ -276,7 +276,7 @@ Common error cases include:
 - Empty filter or ids array in delete/update operations
 - Mutual exclusivity violations (providing both `id` and `filter`)
 
-## Use Cases
+## Use cases
 
 ### Embedded Semantic Search
 

package/dist/index.cjs

@@ -1,12 +1,11 @@
 'use strict';
 
+var chunkS2AWBPTS_cjs = require('./chunk-S2AWBPTS.cjs');
 var nodeApi = require('@duckdb/node-api');
 var error = require('@mastra/core/error');
 var storage = require('@mastra/core/storage');
 var vector = require('@mastra/core/vector');
 
-// src/vector/index.ts
-
 // src/vector/filter-builder.ts
 function escapeString(value) {
   return value.replace(/'/g, "''");
@@ -253,7 +252,9 @@ var DuckDBVector = class extends vector.MastraVector {
       let paramIndex = 0;
       const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
       const stmt = await connection.prepare(preparedSql);
-      stmt.bind(params);
+      for (let i = 0; i < params.length; i++) {
+        chunkS2AWBPTS_cjs.bindParam(stmt, i + 1, params[i]);
+      }
       const result = await stmt.run();
       const rows = await result.getRows();
       const columns = result.columnNames();
@@ -279,7 +280,9 @@ var DuckDBVector = class extends vector.MastraVector {
         let paramIndex = 0;
         const preparedSql = sql.replace(/\?/g, () => `$${++paramIndex}`);
         const stmt = await connection.prepare(preparedSql);
-        stmt.bind(params);
+        for (let i = 0; i < params.length; i++) {
+          chunkS2AWBPTS_cjs.bindParam(stmt, i + 1, params[i]);
+        }
         await stmt.run();
       }
     } finally {
@@ -309,6 +312,7 @@ var DuckDBVector = class extends vector.MastraVector {
         return "array_cosine_distance";
     }
   }
+  /** Perform a vector similarity search with optional metadata filtering. */
   async query(params) {
     await this.initialize();
     const { indexName, queryVector, topK = 10, filter, includeVector = false } = params;
@@ -364,6 +368,7 @@ var DuckDBVector = class extends vector.MastraVector {
       return queryResult;
     });
   }
+  /** Insert or replace vectors with metadata. Returns the vector IDs. */
   async upsert(params) {
     await this.initialize();
     const { indexName, vectors, metadata, ids } = params;
@@ -384,6 +389,7 @@ var DuckDBVector = class extends vector.MastraVector {
     }
     return vectorIds;
   }
+  /** Create a vector table with HNSW index for similarity search. */
   async createIndex(params) {
     await this.initialize();
     const { indexName, dimension, metric } = params;
@@ -412,6 +418,7 @@ var DuckDBVector = class extends vector.MastraVector {
       this.logger.warn(`Could not create HNSW index for ${indexName}, falling back to linear scan`);
     }
   }
+  /** List all vector table names in the database. */
   async listIndexes() {
     await this.initialize();
     const connection = await this.getConnection();
@@ -424,6 +431,7 @@ var DuckDBVector = class extends vector.MastraVector {
     const rows = await result.getRows();
     return rows.map((row) => row[0]);
   }
+  /** Return dimension, row count, and metric for a vector index. */
   async describeIndex(params) {
     await this.initialize();
     const { indexName } = params;
@@ -450,6 +458,7 @@ var DuckDBVector = class extends vector.MastraVector {
       metric: this.config.metric || "cosine"
     };
   }
+  /** Drop a vector table and its HNSW index. */
   async deleteIndex(params) {
     await this.initialize();
     const { indexName } = params;
@@ -457,6 +466,7 @@ var DuckDBVector = class extends vector.MastraVector {
     const connection = await this.getConnection();
     await connection.run(`DROP TABLE IF EXISTS ${tableName}`);
   }
+  /** Update a vector's embedding and/or metadata by ID or filter. */
   async updateVector(params) {
     await this.initialize();
     const { indexName, update } = params;
@@ -492,6 +502,7 @@ var DuckDBVector = class extends vector.MastraVector {
       await this.runStatement(`UPDATE ${tableName} SET ${updates.join(", ")} WHERE ${clause}`);
     }
   }
+  /** Delete a single vector by ID. */
   async deleteVector(params) {
     await this.initialize();
     const { indexName, id } = params;
@@ -499,6 +510,7 @@ var DuckDBVector = class extends vector.MastraVector {
     const sql = `DELETE FROM ${tableName} WHERE id = ?`;
     await this.runStatement(sql, [id]);
   }
+  /** Delete multiple vectors by IDs or metadata filter (mutually exclusive). */
   async deleteVectors(params) {
     await this.initialize();
     const { indexName, ids, filter } = params;
@@ -536,7 +548,232 @@ var DuckDBVector = class extends vector.MastraVector {
     }
   }
 };
+var OBSERVABILITY_UPGRADE_MESSAGE = "DuckDB observability storage requires `@mastra/core` with observability storage support. Upgrade `@mastra/core` to use this store.";
+function isObservabilityCompatibilityError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.message.includes("@mastra/core") && (error.message.includes("does not provide an export named") || error.message.includes("No matching export") || error.message.includes("Cannot find module") || error.message.includes("Cannot find package"));
+}
+var ObservabilityStorageDuckDB = class extends storage.ObservabilityStorage {
+  db;
+  delegate = null;
+  loadPromise = null;
+  unavailableError = null;
+  constructor(config) {
+    super();
+    this.db = config.db;
+  }
+  createUnavailableError(cause) {
+    return new error.MastraError(
+      {
+        id: "OBSERVABILITY_STORAGE_DUCKDB_CORE_UPGRADE_NOT_IMPLEMENTED",
+        domain: error.ErrorDomain.MASTRA_OBSERVABILITY,
+        category: error.ErrorCategory.SYSTEM,
+        text: OBSERVABILITY_UPGRADE_MESSAGE
+      },
+      cause
+    );
+  }
+  async loadDelegate() {
+    if (this.delegate) {
+      return this.delegate;
+    }
+    if (this.unavailableError) {
+      return null;
+    }
+    if (!this.loadPromise) {
+      this.loadPromise = import('./observability-W2QRBK56.cjs').then(({ ObservabilityStorageDuckDB: ObservabilityStorageDuckDB2 }) => {
+        const delegate = new ObservabilityStorageDuckDB2({ db: this.db });
+        this.delegate = delegate;
+        return delegate;
+      }).catch((error) => {
+        if (isObservabilityCompatibilityError(error)) {
+          this.unavailableError = this.createUnavailableError(error);
+          return null;
+        }
+        throw error;
+      });
+    }
+    return this.loadPromise;
+  }
+  async requireDelegate() {
+    const delegate = await this.loadDelegate();
+    if (!delegate) {
+      throw this.unavailableError ?? this.createUnavailableError();
+    }
+    return delegate;
+  }
+  get observabilityStrategy() {
+    return this.delegate?.observabilityStrategy ?? {
+      preferred: "event-sourced",
+      supported: ["event-sourced"]
+    };
+  }
+  get tracingStrategy() {
+    return this.delegate?.tracingStrategy ?? this.observabilityStrategy;
+  }
+  async init(...args) {
+    const delegate = await this.loadDelegate();
+    if (!delegate) {
+      return;
+    }
+    return delegate.init(...args);
+  }
+  async dangerouslyClearAll(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.dangerouslyClearAll(...args);
+  }
+  async createSpan(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.createSpan(...args);
+  }
+  async updateSpan(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.updateSpan(...args);
+  }
+  async getSpan(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getSpan(...args);
+  }
+  async getRootSpan(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getRootSpan(...args);
+  }
+  async getTrace(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getTrace(...args);
+  }
+  async listTraces(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.listTraces(...args);
+  }
+  async batchCreateSpans(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchCreateSpans(...args);
+  }
+  async batchUpdateSpans(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchUpdateSpans(...args);
+  }
+  async batchDeleteTraces(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchDeleteTraces(...args);
+  }
+  async batchCreateLogs(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchCreateLogs(...args);
+  }
+  async listLogs(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.listLogs(...args);
+  }
+  async batchCreateMetrics(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchCreateMetrics(...args);
+  }
+  async listMetrics(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.listMetrics(...args);
+  }
+  async getMetricAggregate(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricAggregate(...args);
+  }
+  async getMetricBreakdown(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricBreakdown(...args);
+  }
+  async getMetricTimeSeries(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricTimeSeries(...args);
+  }
+  async getMetricPercentiles(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricPercentiles(...args);
+  }
+  async getMetricNames(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricNames(...args);
+  }
+  async getMetricLabelKeys(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricLabelKeys(...args);
+  }
+  async getMetricLabelValues(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getMetricLabelValues(...args);
+  }
+  async getEntityTypes(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getEntityTypes(...args);
+  }
+  async getEntityNames(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getEntityNames(...args);
+  }
+  async getServiceNames(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getServiceNames(...args);
+  }
+  async getEnvironments(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getEnvironments(...args);
+  }
+  async getTags(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.getTags(...args);
+  }
+  async createScore(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.createScore(...args);
+  }
+  async batchCreateScores(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchCreateScores(...args);
+  }
+  async listScores(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.listScores(...args);
+  }
+  async createFeedback(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.createFeedback(...args);
+  }
+  async batchCreateFeedback(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.batchCreateFeedback(...args);
+  }
+  async listFeedback(...args) {
+    const delegate = await this.requireDelegate();
+    return delegate.listFeedback(...args);
+  }
+};
+var DuckDBStore = class extends storage.MastraCompositeStore {
+  db;
+  observabilityStore;
+  stores;
+  constructor(config = {}) {
+    const id = config.id ?? "duckdb";
+    super({ id, name: "DuckDBStore" });
+    this.db = new chunkS2AWBPTS_cjs.DuckDBConnection({ path: config.path });
+    this.observabilityStore = new ObservabilityStorageDuckDB({ db: this.db });
+    this.stores = {
+      observability: this.observabilityStore
+    };
+  }
+  /** Convenience accessor for the observability domain. */
+  get observability() {
+    return this.observabilityStore;
+  }
+};
 
+Object.defineProperty(exports, "DuckDBConnection", {
+  enumerable: true,
+  get: function () { return chunkS2AWBPTS_cjs.DuckDBConnection; }
+});
+exports.DuckDBStore = DuckDBStore;
 exports.DuckDBVector = DuckDBVector;
+exports.ObservabilityStorageDuckDB = ObservabilityStorageDuckDB;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map