> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# LanceDB 存储

LanceDB 存储实现使用 LanceDB 数据库系统提供高性能存储方案，擅长处理传统数据存储和向量操作。

> **不支持 Observability:** LanceDB 存储**不支持 observability 域**。来自 `MastraStorageExporter` 的 Trace 无法持久化到 LanceDB，并且仅将 LanceDB 作为存储 Provider 时，[Studio](https://mastra.zisheng.pro/docs/studio/overview) 的 observability 功能无法使用。若要启用 observability，请使用[组合存储](https://mastra.zisheng.pro/reference/storage/composite)将 observability 数据路由到 ClickHouse 等受支持的 Provider。

## 安装

**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
```

## 使用方法

### 基本存储用法

```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' },
})
```

## 参数

### `LanceStorage.create()`

**name** (`string`): 存储实例的名称标识符

**uri** (`string`): 用于连接 LanceDB 数据库的 URI。可以是本地路径、云数据库 URL 或 S3 存储桶 URL

**options** (`ConnectionOptions`): LanceDB 的连接选项，例如超时设置、身份验证等。

## 补充说明

### Schema 管理

LanceStorage 实现会自动处理 schema 创建和更新。它将 Mastra 的 schema 类型映射为 LanceDB 内部使用的 Apache Arrow 数据类型：

- `text`, `uuid` → Utf8
- `int`, `integer` → Int32
- `float` → Float32
- `jsonb`, `json` → Utf8（序列化）
- `binary` → Binary

### 初始化

将 storage 传递给 Mastra class 时，会在任何存储操作之前自动调用 `init()`：

```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
})
```

如果不通过 Mastra 而直接使用 storage，必须显式调用 `init()` 来创建表：

```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: '...' })
```

> **注意:** 如果未调用 `init()`，不会创建表，存储操作将静默失败或抛出错误。

### 部署选项

LanceDB 存储可针对不同部署场景进行配置：

- **本地开发**：使用本地文件路径进行开发和测试
  ```text
  /path/to/db
  ```
- **云端部署**：连接到托管的 LanceDB 实例
  ```text
  db://host:port
  ```
- **S3 存储**：使用 Amazon S3 进行大容量云存储
  ```text
  s3://bucket/db
  ```

### 表管理

LanceStorage 提供用于管理表的方法：

- 使用自定义 schema 创建表
- 删除表
- 清空表（删除所有记录）
- 按键加载记录
- 插入单条和批量记录