DuckDB 儲存空間

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

如需向量搜尋，請參閱同一套件中獨立 API 的 DuckDB 向量儲存空間參考資料。

適合使用 DuckDB 的時機

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

DuckDB 目前只實作 observability domain。在複合儲存空間設定中，請搭配其他儲存 adapter（例如 LibSQL）來處理 memory 與 workflows。

警告

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

使用方式

在複合 store 中作為 observability domain

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

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

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

獨立使用

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

import { DuckDBStore } from '@mastra/duckdb'

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

await observability.init()

記憶體內資料庫

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

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

設定

DuckDBStore 選項

id?:

string

= 'duckdb'

此儲存空間執行個體的唯一識別碼。

path?:

string

= 'mastra.duckdb'

DuckDB 資料庫檔案的路徑。暫時性的記憶體內資料庫請使用 :memory:。

memoryLimit?:

string

= '2GB'

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

threads?:

number

= 每個 CPU 核心一個

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

較低階的型別

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

支援的 domain

DuckDB 目前實作一個儲存 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()

可觀測性策略

DuckDB 支援 MastraStorageExporter 使用的 event-sourced 策略；此策略會在記憶體中緩衝 span，並批次寫入已完成的事件。這適合開發規模的流量。若是大量正式環境工作負載，請參閱 MastraStorageExporter 儲存 Provider 支援情形。

相關內容

• 儲存空間概觀
• 複合儲存空間
• ClickHouse 儲存空間：正式環境可觀測性 backend
• DuckDB 向量儲存空間：使用相同套件進行向量搜尋
• 可觀測性概觀