DuckDB 儲存

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

如需向量搜尋，請參閱 DuckDB vector store 參考。這是同一套件中的獨立 API。

何時使用 DuckDB

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

DuckDB 目前只實作 observability domain。如要在 composite storage 設定中使用 memory 及 workflows，請配合另一個 storage adapter（例如 LibSQL）使用。

注意

DuckDB 適合開發用途，不建議用於生產環境。它在程序內運行、將資料保存至單一本機檔案，而且不適用於採用臨時檔案系統的平台（例如 Railway、Fly.io、Render、Heroku 或 serverless container）。如需用於生產環境的 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

用法

作為 composite store 中的 observability domain

這是標準的本機開發設定。LibSQL 處理其他 domain，而 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 accessor 會直接傳回 observability domain store。功能相同的通用寫法會使用 getStore()，適用於任何 composite-style storage adapter：

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

獨立使用

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

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。

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

設定

DuckDBStore 選項

id?:

string

= 'duckdb'

此 storage instance 的唯一識別碼。

path?:

string

= 'mastra.duckdb'

DuckDB 資料庫檔案的路徑。使用 :memory: 可建立臨時 in-memory database。

memoryLimit?:

string

= '2GB'

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

threads?:

number

= 每個 CPU 核心一個

DuckDB 可使用的 thread 數目。降低此值可避免查詢佔用共享應用程式伺服器的所有核心。

較低階的 type

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

支援的 domain

DuckDB 目前實作了一個 storage domain：

Domain	支援
observability	是
memory	否
workflows	否
scores	否
agents	否

如需完整的儲存方案，請將 DuckDBStore 與涵蓋欠缺 domain 的 adapter 組合使用（本機開發最常配合 LibSQL）。

初始化

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

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 支援。

相關內容

• 儲存概覽
• Composite storage
• ClickHouse 儲存：生產環境 observability 後端
• DuckDB vector store：使用同一套件進行向量搜尋
• Observability 概覽