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

# DuckDB 儲存

[DuckDB](https://duckdb.org/) 是嵌入於程序內的分析資料庫。`@mastra/duckdb` 套件提供由 OLAP 支援的 observability store，適合本機開發，無需運行外部服務即可處理 Trace、記錄、指標、分數及意見回饋。

如需向量搜尋，請參閱 [DuckDB vector store 參考](https://mastra.zisheng.pro/zh-HK/reference/vectors/duckdb)。這是同一套件中的獨立 API。

## 何時使用 DuckDB

適用於在本機開發 observability 功能。DuckDB 是嵌入式及以檔案為基礎的資料庫，因此不需要伺服器，並可即時啟動。它支援與 ClickHouse 相同的 observability signals，方便你在部署至生產環境後端前測試 dashboard 及探索 Trace。

DuckDB 目前只實作 `observability` domain。如要在 [composite storage](https://mastra.zisheng.pro/zh-HK/reference/storage/composite) 設定中使用 `memory` 及 `workflows`，請配合另一個 storage adapter（例如 [LibSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)）使用。

> **注意:** DuckDB 適合開發用途，不建議用於生產環境。它在程序內運行、將資料保存至單一本機檔案，而且不適用於採用臨時檔案系統的平台（例如 Railway、Fly.io、Render、Heroku 或 serverless container）。如需用於生產環境的 observability，請使用 [ClickHouse](https://mastra.zisheng.pro/zh-HK/reference/storage/clickhouse)。

## 安裝

**npm**:

```bash
npm install @mastra/duckdb@latest
```

**pnpm**:

```bash
pnpm add @mastra/duckdb@latest
```

**Yarn**:

```bash
yarn add @mastra/duckdb@latest
```

**Bun**:

```bash
bun add @mastra/duckdb@latest
```

## 用法

### 作為 composite store 中的 observability domain

這是標準的本機開發設定。LibSQL 處理其他 domain，而 DuckDB 則處理 observability。

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { LibSQLStore } from '@mastra/libsql'
import { DuckDBStore } from '@mastra/duckdb'
import { Observability, MastraStorageExporter } from '@mastra/observability'

export const mastra = new Mastra({
  storage: new MastraCompositeStore({
    id: 'composite-storage',
    default: new LibSQLStore({
      id: 'mastra-storage',
      url: 'file:./mastra.db',
    }),
    domains: {
      observability: new DuckDBStore().observability,
    },
  }),
  observability: new Observability({
    configs: {
      default: {
        serviceName: 'mastra',
        exporters: [new MastraStorageExporter()],
      },
    },
  }),
})
```

`.observability` accessor 會直接傳回 observability domain store。功能相同的通用寫法會使用 `getStore()`，適用於任何 composite-style storage adapter：

```typescript
const observability = await new DuckDBStore().getStore('observability')
```

### 獨立使用

如果只需要在 `Mastra` composite 以外使用 observability storage，請直接建立 `DuckDBStore`，然後存取 observability domain：

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
const observability = duckdb.observability

await observability.init()
```

### In-memory database

傳入 `:memory:` 即可使用臨時 DuckDB instance。程序結束時資料會遺失，適合單元測試及短期運行的 script。

```typescript
const duckdb = new DuckDBStore({ path: ':memory:' })
```

## 設定

### `DuckDBStore` 選項

**id** (`string`): 此 storage instance 的唯一識別碼。 (Default: `'duckdb'`)

**path** (`string`): DuckDB 資料庫檔案的路徑。使用 :memory: 可建立臨時 in-memory database。 (Default: `'mastra.duckdb'`)

**memoryLimit** (`string`): DuckDB 可使用的記憶體上限，例如 '2GB' 或 '512MB'。對於以檔案為基礎的資料庫，超出記憶體容量的操作會改用磁碟。專用分析工作負載可提高此值。 (Default: `'2GB'`)

**threads** (`number`): DuckDB 可使用的 thread 數目。降低此值可避免查詢佔用共享應用程式伺服器的所有核心。 (Default: `每個 CPU 核心一個`)

### 較低階的 type

`@mastra/duckdb` 亦會匯出 `DuckDBConnection`，讓多個 Mastra storage instance 共用同一個底層資料庫，並匯出對應的 `DuckDBStorageConfig` type。大多數應用程式都不需要直接使用這些項目。

## 支援的 domain

DuckDB 目前實作了一個 storage domain：

| Domain          | 支援 |
| --------------- | -- |
| `observability` | 是  |
| `memory`        | 否  |
| `workflows`     | 否  |
| `scores`        | 否  |
| `agents`        | 否  |

如需完整的儲存方案，請將 `DuckDBStore` 與涵蓋欠缺 domain 的 adapter 組合使用（本機開發最常配合 [LibSQL](https://mastra.zisheng.pro/zh-HK/reference/storage/libsql)）。

## 初始化

透過 `MastraCompositeStore` 傳入 `Mastra` 時，observability domain 會在首次使用時自行初始化。如要在 `Mastra` 以外明確執行初始化，請在 observability store 上呼叫 `init()`：

```typescript
import { DuckDBStore } from '@mastra/duckdb'

const duckdb = new DuckDBStore({ path: './traces.duckdb' })
await duckdb.observability.init()
```

## Observability 策略

DuckDB 支援 `MastraStorageExporter` 所使用的 `event-sourced` 策略。此策略會在記憶體中緩衝 span，並分批寫入已完成的 event，適合開發規模的流量。高流量的生產環境工作負載請參閱 [`MastraStorageExporter` storage provider 支援](https://mastra.zisheng.pro/zh-HK/docs/observability/integrations/exporters/mastra-storage)。

## 相關內容

- [儲存概覽](https://mastra.zisheng.pro/zh-HK/reference/storage/overview)
- [Composite storage](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)
- [ClickHouse 儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/clickhouse)：生產環境 observability 後端
- [DuckDB vector store](https://mastra.zisheng.pro/zh-HK/reference/vectors/duckdb)：使用同一套件進行向量搜尋
- [Observability 概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/overview)