@mastra/core/dist/docs/references/reference-storage-lance.md

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

# 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 **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to LanceDB, and [Studio's](https://mastra.ai/docs/studio/overview) 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.

## 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()` isn't 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