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

# LanceDB 儲存

LanceDB 儲存實作採用 LanceDB 數據庫系統，提供高效能儲存方案，尤其擅長處理傳統數據儲存和向量操作。

> **不支援可觀測性:** LanceDB 儲存**不支援可觀測性 domain**。`MastraStorageExporter` 的 Trace 無法保存至 LanceDB；如果 LanceDB 是唯一的儲存 Provider，[Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 的可觀測性功能亦無法運作。如要啟用可觀測性，請使用[複合儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)，將可觀測性數據路由至 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 bucket URL

**options** (`ConnectionOptions`): LanceDB 的連接選項，例如逾時設定、驗證等。

## 其他備註

### Schema 管理

LanceStorage 實作會自動處理 schema 建立及更新。它會將 Mastra 的 schema 類型對應至 LanceDB 內部使用的 Apache Arrow 數據類型：

- `text`, `uuid` → Utf8
- `int`, `integer` → Int32
- `float` → Float32
- `jsonb`, `json` → Utf8 (serialized)
- `binary` → Binary

### 初始化

當你將儲存傳入 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 而直接使用儲存，你必須明確呼叫 `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 建立資料表
- 移除資料表
- 清空資料表（刪除所有記錄）
- 按鍵載入記錄
- 插入單筆及批次記錄