# 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