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

package/dist/docs/references/reference-storage-lance.md

@@ -0,0 +1,131 @@
+# LanceDB Storage
+
+The LanceDB storage implementation provides a high-performance storage solution using the LanceDB database system, which excels at handling both traditional data storage and vector operations.
+
+> **Observability Not Supported:** LanceDB storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to LanceDB, and Mastra Studio's observability features won't work with LanceDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/lance@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/lance@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/lance@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/lance@latest
+```
+
+## Usage
+
+### Basic Storage Usage
+
+```typescript
+import { LanceStorage } from '@mastra/lance'
+
+// Connect to a local database
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
+
+// Connect to a LanceDB cloud database
+const storage = await LanceStorage.create('my-storage', 'db://host:port')
+
+// Connect to a cloud database with custom options
+const storage = await LanceStorage.create('my-storage', 's3://bucket/db', {
+  storageOptions: { timeout: '60s' },
+})
+```
+
+## Parameters
+
+### LanceStorage.create()
+
+**name:** (`string`): Name identifier for the storage instance
+
+**uri:** (`string`): URI to connect to the LanceDB database. Can be a local path, cloud DB URL, or S3 bucket URL
+
+**options?:** (`ConnectionOptions`): Connection options for LanceDB, such as timeout settings, authentication, etc.
+
+## Additional Notes
+
+### Schema Management
+
+The LanceStorage implementation automatically handles schema creation and updates. It maps Mastra's schema types to Apache Arrow data types, which are used by LanceDB internally:
+
+- `text`, `uuid` → Utf8
+- `int`, `integer` → Int32
+- `float` → Float32
+- `jsonb`, `json` → Utf8 (serialized)
+- `binary` → Binary
+
+### Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LanceStorage } from '@mastra/lance'
+
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+})
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { LanceStorage } from '@mastra/lance'
+
+const storage = await LanceStorage.create('my-storage', '/path/to/db')
+
+// Required when using storage directly
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```
+
+> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+
+### Deployment Options
+
+LanceDB storage can be configured for different deployment scenarios:
+
+- **Local Development**: Use a local file path for development and testing
+  ```text
+  /path/to/db
+  ```
+- **Cloud Deployment**: Connect to a hosted LanceDB instance
+  ```text
+  db://host:port
+  ```
+- **S3 Storage**: Use Amazon S3 for scalable cloud storage
+  ```text
+  s3://bucket/db
+  ```
+
+### Table Management
+
+LanceStorage provides methods for managing tables:
+
+- Create tables with custom schemas
+- Drop tables
+- Clear tables (delete all records)
+- Load records by key
+- Insert single and batch records

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

@@ -0,0 +1,220 @@
+# Lance Vector Store
+
+The LanceVectorStore class provides vector search using [LanceDB](https://lancedb.github.io/lancedb/), an embedded vector database built on the Lance columnar format. It offers efficient storage and fast similarity search for both local development and production deployments.
+
+## Factory Method
+
+The LanceVectorStore uses a factory pattern for creation. You should use the static `create()` method rather than the constructor directly.
+
+**uri:** (`string`): Path to LanceDB database or URI for cloud deployments
+
+**options?:** (`ConnectionOptions`): Additional connection options for LanceDB
+
+## Constructor Examples
+
+You can create a `LanceVectorStore` instance using the static create method:
+
+```ts
+import { LanceVectorStore } from '@mastra/lance'
+
+// Connect to a local database
+const vectorStore = await LanceVectorStore.create('/path/to/db')
+
+// Connect to a LanceDB cloud database
+const cloudStore = await LanceVectorStore.create('db://host:port')
+
+// Connect to a cloud database with options
+const s3Store = await LanceVectorStore.create('s3://bucket/db', {
+  storageOptions: { timeout: '60s' },
+})
+```
+
+## Methods
+
+### createIndex()
+
+**tableName:** (`string`): Name of the table to create index in
+
+**indexName:** (`string`): Name of the index (column name) to create
+
+**dimension:** (`number`): Vector dimension (must match your embedding model)
+
+**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
+
+**indexConfig?:** (`LanceIndexConfig`): Index configuration (Default: `{ type: 'hnsw' }`)
+
+#### LanceIndexConfig
+
+**type:** (`'ivfflat' | 'hnsw'`): stringivfflat:ivfflatClusters vectors into lists for approximate search.hnsw:hnswGraph-based index offering fast search times and high recall. (Default: `hnsw`)
+
+**numPartitions?:** (`number`): Number of partitions for IVF indexes (Default: `128`)
+
+**numSubVectors?:** (`number`): Number of sub-vectors for product quantization (Default: `16`)
+
+**hnsw?:** (`HNSWConfig`): objectm?:numberMaximum number of connections per node (default: 16)efConstruction?:numberBuild-time complexity (default: 100)
+
+### createTable()
+
+**tableName:** (`string`): Name of the table to create
+
+**data:** (`Record<string, unknown>[] | TableLike`): Initial data for the table
+
+**options?:** (`Partial<CreateTableOptions>`): Additional table creation options
+
+### upsert()
+
+**tableName:** (`string`): Name of the table to upsert vectors into
+
+**vectors:** (`number[][]`): Array of embedding vectors
+
+**metadata?:** (`Record<string, any>[]`): Metadata for each vector
+
+**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)
+
+### query()
+
+**tableName:** (`string`): Name of the table to query
+
+**queryVector:** (`number[]`): Query vector
+
+**topK?:** (`number`): Number of results to return (Default: `10`)
+
+**filter?:** (`Record<string, any>`): Metadata filters
+
+**includeVector?:** (`boolean`): Whether to include the vector in the result (Default: `false`)
+
+**columns?:** (`string[]`): Specific columns to include in the result (Default: `[]`)
+
+**includeAllColumns?:** (`boolean`): Whether to include all columns in the result (Default: `false`)
+
+### listTables()
+
+Returns an array of table names as strings.
+
+```typescript
+const tables = await vectorStore.listTables()
+// ['my_vectors', 'embeddings', 'documents']
+```
+
+### getTableSchema()
+
+**tableName:** (`string`): Name of the table to describe
+
+Returns the schema of the specified table.
+
+### deleteTable()
+
+**tableName:** (`string`): Name of the table to delete
+
+### deleteAllTables()
+
+Deletes all tables in the database.
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+**indexName:** (`string`): Name of the index to describe
+
+Returns information about the index:
+
+```typescript
+interface IndexStats {
+  dimension: number
+  count: number
+  metric: 'cosine' | 'euclidean' | 'dotproduct'
+  type: 'ivfflat' | 'hnsw'
+  config: {
+    m?: number
+    efConstruction?: number
+    numPartitions?: number
+    numSubVectors?: number
+  }
+}
+```
+
+### 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)
+
+**update:** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or 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)
+
+### close()
+
+Closes the database connection.
+
+## 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
+  document?: string // Document text if available
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    tableName: 'my_vectors',
+    queryVector: queryVector,
+  })
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.message)
+  }
+}
+```
+
+## Best Practices
+
+- Use the appropriate index type for your use case:
+
+  - HNSW for better recall and performance when memory isn't constrained
+  - IVF for better memory efficiency with large datasets
+
+- For optimal performance with large datasets, consider adjusting `numPartitions` and `numSubVectors` values
+
+- Use `close()` method to properly close connections when done with the database
+
+- Store metadata with a consistent schema to simplify filtering operations
+
+## Related
+
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)