@mastra/lance 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/docs/storage/01-reference.md

@@ -0,0 +1,113 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## Reference: LanceDB Storage
+
+> Documentation for the LanceDB storage implementation in Mastra.
+
+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.
+
+## Installation
+
+```bash
+npm install @mastra/lance@beta
+```
+
+## 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()
+
+## 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: "..." });
+```
+
+> **Note:**
+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
+  ```
+  /path/to/db
+  ```
+- **Cloud Deployment**: Connect to a hosted LanceDB instance
+  ```
+  db://host:port
+  ```
+- **S3 Storage**: Use Amazon S3 for scalable cloud storage
+  ```
+  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/vectors/01-reference.md

@@ -0,0 +1,149 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: Lance Vector Store
+
+> Documentation for the LanceVectorStore class in Mastra, which provides vector search using LanceDB, an embedded vector database based on the Lance columnar format.
+
+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.
+
+## 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()
+
+#### LanceIndexConfig
+
+### createTable()
+
+### upsert()
+
+### query()
+
+### listTables()
+
+Returns an array of table names as strings.
+
+```typescript
+const tables = await vectorStore.listTables();
+// ['my_vectors', 'embeddings', 'documents']
+```
+
+### getTableSchema()
+
+Returns the schema of the specified table.
+
+### deleteTable()
+
+### deleteAllTables()
+
+Deletes all tables in the database.
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+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()
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### 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](../rag/metadata-filters)