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.

InstallationDirect link to Installation

npm install @mastra/lance

UsageDirect link to Usage

Basic Storage UsageDirect link to Basic Storage Usage

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" },
});

ParametersDirect link to Parameters

LanceStorage.create()Direct link to 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 NotesDirect link to Additional Notes

Schema ManagementDirect link to 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

InitializationDirect link to Initialization

When you pass storage to the Mastra class, init() is called automatically before any storage operation:

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:

import { LanceStorage } from "@mastra/lance";

const storage = await LanceStorage.create("my-storage", "/path/to/db");

// Required when using storage directly
await storage.init();

// Now you can use the storage
await storage.getThread({ threadId: "..." });

warning

If init() is not called, tables won't be created and storage operations will fail silently or throw errors.

Deployment OptionsDirect link to 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 ManagementDirect link to 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