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

# DuckDB 儲存空間

[DuckDB](https://duckdb.org/) 是嵌入式、同處理程序的分析資料庫。`@mastra/duckdb` 套件提供以 OLAP 為基礎、用於本機開發的可觀測性 store；不需執行外部服務，即可用於 Trace、log、metric、分數與意見回饋。

如需向量搜尋，請參閱同一套件中獨立 API 的 [DuckDB 向量儲存空間參考資料](https://mastra.zisheng.pro/zh-TW/reference/vectors/duckdb)。

## 適合使用 DuckDB 的時機

在本機開發可觀測性功能時。DuckDB 是嵌入式且以檔案為基礎，因此不需要伺服器，並可立即啟動。它支援與 ClickHouse 相同的可觀測性 signal，適合在部署至正式環境 backend 前測試 dashboard 與探索 Trace。

DuckDB 目前只實作 `observability` domain。在[複合儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)設定中，請搭配其他儲存 adapter（例如 [LibSQL](https://mastra.zisheng.pro/zh-TW/reference/storage/libsql)）來處理 `memory` 與 `workflows`。

> **警告:** DuckDB 適用於開發環境，不建議用於正式環境。它在處理程序內執行、持久化至單一本機檔案，且無法在使用暫時性檔案系統的平台（例如 Railway、Fly.io、Render、Heroku 或 serverless container）上運作。正式環境的可觀測性請使用 [ClickHouse](https://mastra.zisheng.pro/zh-TW/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
```

## 使用方式

### 在複合 store 中作為 observability domain

這是標準的本機開發設定。LibSQL 處理其他 domain，而 DuckDB 處理可觀測性。

```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()`，適用於任何複合型儲存 adapter：

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

### 獨立使用

若只需要 `Mastra` 複合儲存空間以外的可觀測性儲存空間，請直接建立 `DuckDBStore` 執行個體並存取 observability domain：

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

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

await observability.init()
```

### 記憶體內資料庫

傳入 `:memory:` 即可使用暫時性的 DuckDB 執行個體。處理程序結束時資料會遺失，因此適合單元測試與短期執行的 script。

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

## 設定

### `DuckDBStore` 選項

**id** (`string`): 此儲存空間執行個體的唯一識別碼。 (Default: `'duckdb'`)

**path** (`string`): DuckDB 資料庫檔案的路徑。暫時性的記憶體內資料庫請使用 :memory:。 (Default: `'mastra.duckdb'`)

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

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

### 較低階的型別

`@mastra/duckdb` 也會匯出 `DuckDBConnection`，以便在多個 Mastra 儲存空間執行個體之間共用單一底層資料庫，以及對應的 `DuckDBStorageConfig` 型別。大多數應用程式不需要直接使用這些項目。

## 支援的 domain

DuckDB 目前實作一個儲存 domain：

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

若要使用完整的儲存解決方案，請將 `DuckDBStore` 與涵蓋缺少 domain 的 adapter 組合使用（本機開發最常使用 [LibSQL](https://mastra.zisheng.pro/zh-TW/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()
```

## 可觀測性策略

DuckDB 支援 `MastraStorageExporter` 使用的 `event-sourced` 策略；此策略會在記憶體中緩衝 span，並批次寫入已完成的事件。這適合開發規模的流量。若是大量正式環境工作負載，請參閱 [`MastraStorageExporter` 儲存 Provider 支援情形](https://mastra.zisheng.pro/zh-TW/docs/observability/integrations/exporters/mastra-storage)。

## 相關內容

- [儲存空間概觀](https://mastra.zisheng.pro/zh-TW/reference/storage/overview)
- [複合儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)
- [ClickHouse 儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/clickhouse)：正式環境可觀測性 backend
- [DuckDB 向量儲存空間](https://mastra.zisheng.pro/zh-TW/reference/vectors/duckdb)：使用相同套件進行向量搜尋
- [可觀測性概觀](https://mastra.zisheng.pro/zh-TW/docs/observability/overview)