DuckDBストレージ

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

ベクトル検索については、同じパッケージ内の独立したAPIであるDuckDBベクトルストアのリファレンスを参照してください。

DuckDBを使用する場面

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

現在、DuckDBが実装しているのはobservabilityドメインのみです。複合ストレージ構成で、memoryとworkflowsには別のストレージアダプター（LibSQLなど）を組み合わせてください。

警告

DuckDBは開発用であり、本番環境には推奨されません。プロセス内で動作し、単一のローカルファイルに永続化するため、一時ファイルシステムを使用するプラットフォーム（Railway、Fly.io、Render、Heroku、サーバーレスコンテナなど）では動作しません。本番環境のObservabilityにはClickHouseを使用してください。

インストール

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

使用方法

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

これは標準的なローカル開発構成です。LibSQLがその他のドメインを、DuckDBがObservabilityを処理します。

src/mastra/index.ts

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()を使用します。これは、複合型のすべてのストレージアダプターで利用できます。

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

スタンドアロン

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

import { DuckDBStore } from '@mastra/duckdb'

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

await observability.init()

インメモリデータベース

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

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

設定

DuckDBStoreのオプション

id?:

string

= 'duckdb'

このストレージインスタンスの一意な識別子。

path?:

string

= 'mastra.duckdb'

DuckDBデータベースファイルのパス。一時的なインメモリデータベースには:memory:を使用します。

memoryLimit?:

string

= '2GB'

DuckDBが使用できる最大メモリ（'2GB'や'512MB'など）。ファイルベースのデータベースでは、メモリ容量を超える処理はディスクに退避されます。専用の分析ワークロードでは、この値を増やしてください。

threads?:

number

= one per CPU core

DuckDBが使用できるスレッド数。共有アプリケーションサーバーの全コアをクエリが占有しないようにするには、この値を減らしてください。

低レベルの型

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

サポートされるドメイン

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

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

完全なストレージソリューションにするには、不足しているドメインを扱えるアダプター（ローカル開発では通常LibSQL）とDuckDBStoreを組み合わせてください。

初期化

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

import { DuckDBStore } from '@mastra/duckdb'

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

Observability戦略

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

関連項目

• ストレージの概要
• 複合ストレージ
• ClickHouseストレージ: 本番環境向けObservabilityバックエンド
• DuckDBベクトルストア: 同じパッケージを使用したベクトル検索
• Observabilityの概要