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

# LanceDB 儲存空間

LanceDB 儲存空間實作採用 LanceDB 資料庫系統，提供高效能的儲存解決方案，擅長同時處理傳統資料儲存與向量操作。

> **不支援可觀測性:** LanceDB 儲存空間**不支援 observability domain**。`MastraStorageExporter` 的 Trace 無法持久化至 LanceDB；若 LanceDB 是唯一的儲存 Provider，[Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 的可觀測性功能也無法運作。若要啟用可觀測性，請使用[複合儲存空間](https://mastra.zisheng.pro/zh-TW/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（序列化）
- `binary` → Binary

### 初始化

將 storage 傳入 Mastra 類別時，系統會在進行任何儲存操作前自動呼叫 `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 建立資料表
- 刪除資料表
- 清除資料表（刪除所有記錄）
- 依 key 載入記錄
- 插入單筆與批次記錄