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

# DuckDBストレージ

[DuckDB](https://duckdb.org/)は、プロセスに組み込んで使用する分析データベースです。`@mastra/duckdb`パッケージは、外部サービスを実行せずにトレース、ログ、メトリクス、スコア、フィードバックを扱える、ローカル開発向けのOLAPベースのObservabilityストアを提供します。

ベクトル検索については、同じパッケージ内の独立したAPIである[DuckDBベクトルストアのリファレンス](https://mastra.zisheng.pro/ja/reference/vectors/duckdb)を参照してください。

## DuckDBを使用する場面

Observability機能のローカル開発に使用します。DuckDBは組み込み型かつファイルベースのため、サーバーが不要ですぐに起動できます。ClickHouseと同じObservabilityシグナルをサポートしているため、本番バックエンドへデプロイする前のダッシュボードのテストやトレースの調査に役立ちます。

現在、DuckDBが実装しているのは`observability`ドメインのみです。[複合ストレージ](https://mastra.zisheng.pro/ja/reference/storage/composite)構成で、`memory`と`workflows`には別のストレージアダプター（[LibSQL](https://mastra.zisheng.pro/ja/reference/storage/libsql)など）を組み合わせてください。

> **警告:** DuckDBは開発用であり、本番環境には推奨されません。プロセス内で動作し、単一のローカルファイルに永続化するため、一時ファイルシステムを使用するプラットフォーム（Railway、Fly.io、Render、Heroku、サーバーレスコンテナなど）では動作しません。本番環境のObservabilityには[ClickHouse](https://mastra.zisheng.pro/ja/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
```

## 使用方法

### 複合ストアのObservabilityドメインとして使用する

これは標準的なローカル開発構成です。LibSQLがその他のドメインを、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`アクセサーは、Observabilityドメインストアを直接返します。同等の汎用形式では`getStore()`を使用します。これは、複合型のすべてのストレージアダプターで利用できます。

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

### スタンドアロン

`Mastra`の複合ストレージ以外でObservabilityストレージだけが必要な場合は、`DuckDBStore`を直接インスタンス化し、Observabilityドメインにアクセスします。

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

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

await observability.init()
```

### インメモリデータベース

一時的なDuckDBインスタンスを使用するには、`:memory:`を渡します。プロセスの終了時にデータが失われるため、ユニットテストや短時間のスクリプトに適しています。

```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が使用できるスレッド数。共有アプリケーションサーバーの全コアをクエリが占有しないようにするには、この値を減らしてください。 (Default: `one per CPU core`)

### 低レベルの型

`@mastra/duckdb`は、複数のMastraストレージインスタンスで単一の基盤データベースを共有するための`DuckDBConnection`と、対応する`DuckDBStorageConfig`型もエクスポートします。ほとんどのアプリケーションでは、これらを直接使用する必要はありません。

## サポートされるドメイン

現在、DuckDBが実装しているストレージドメインは1つです。

| ドメイン            | サポート |
| --------------- | ---- |
| `observability` | はい   |
| `memory`        | いいえ  |
| `workflows`     | いいえ  |
| `scores`        | いいえ  |
| `agents`        | いいえ  |

完全なストレージソリューションにするには、不足しているドメインを扱えるアダプター（ローカル開発では通常[LibSQL](https://mastra.zisheng.pro/ja/reference/storage/libsql)）と`DuckDBStore`を組み合わせてください。

## 初期化

`MastraCompositeStore`を介して`Mastra`に渡すと、Observabilityドメインは初回使用時に自動で初期化されます。`Mastra`の外部で明示的に初期化するには、Observabilityストアで`init()`を呼び出します。

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

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

## Observability戦略

DuckDBは、`MastraStorageExporter`が使用する`event-sourced`戦略をサポートしています。この戦略では、spanをメモリにバッファリングし、完了したイベントをバッチで書き込みます。開発規模のトラフィックに適しています。大規模な本番ワークロードについては、[`MastraStorageExporter`がサポートするストレージProvider](https://mastra.zisheng.pro/ja/docs/observability/integrations/exporters/mastra-storage)を参照してください。

## 関連項目

- [ストレージの概要](https://mastra.zisheng.pro/ja/reference/storage/overview)
- [複合ストレージ](https://mastra.zisheng.pro/ja/reference/storage/composite)
- [ClickHouseストレージ](https://mastra.zisheng.pro/ja/reference/storage/clickhouse): 本番環境向けObservabilityバックエンド
- [DuckDBベクトルストア](https://mastra.zisheng.pro/ja/reference/vectors/duckdb): 同じパッケージを使用したベクトル検索
- [Observabilityの概要](https://mastra.zisheng.pro/ja/docs/observability/overview)