DynamoDB 儲存空間

DynamoDB 儲存空間實作採用 ElectroDB 單一資料表設計模式，為 Mastra 提供大容量、高效能的 NoSQL 資料庫解決方案。

不支援可觀測性

DynamoDB 儲存空間不支援 observability domain。MastraStorageExporter 的 Trace 無法持久化至 DynamoDB；若 DynamoDB 是唯一的儲存 Provider，Studio 的可觀測性功能也無法運作。若要啟用可觀測性，請使用複合儲存空間，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

項目大小限制

DynamoDB 規定每個項目最大為 400 KB。儲存包含圖片等 base64 編碼附件的訊息時，可能超過此限制。如需包含將附件上傳至外部儲存空間等替代做法，請參閱處理大型附件。

功能
「功能」的直接連結

高效率的單一資料表設計，可滿足所有 Mastra 儲存需求
以 ElectroDB 為基礎，提供型別安全的 DynamoDB 存取
支援 AWS credential、region 與 endpoint
與開發用 AWS DynamoDB Local 相容
儲存 Thread、訊息、評估與 Workflow 資料
針對 serverless 環境最佳化
可為各實體型別設定 TTL（Time To Live），讓資料自動到期

安裝
「安裝」的直接連結

npm
pnpm
Yarn
Bun

npm install @mastra/dynamodb@latest

pnpm add @mastra/dynamodb@latest

yarn add @mastra/dynamodb@latest

bun add @mastra/dynamodb@latest

先決條件
「先決條件」的直接連結

使用此套件前，必須建立具備特定結構的 DynamoDB 資料表，包括 primary key 與 Global Secondary Index（GSI）。此 adapter 預期 DynamoDB 資料表及其 GSI 由外部佈建。

使用 AWS CloudFormation 或 AWS CDK 設定資料表的詳細指示，請參閱 TABLE_SETUP.md。繼續操作前，請確認資料表已依這些指示完成設定。

使用方式
「使用方式」的直接連結

基本用法
「基本用法」的直接連結

import { Memory } from '@mastra/memory'
import { DynamoDBStore } from '@mastra/dynamodb'

// Initialize the DynamoDB storage
const storage = new DynamoDBStore({
  id: 'dynamodb', // Unique identifier for this storage instance
  config: {
    tableName: 'mastra-single-table', // Name of your DynamoDB table
    region: 'us-east-1', // Optional: AWS region, defaults to 'us-east-1'
    // endpoint: "http://localhost:8000", // Optional: For local DynamoDB
    // credentials: { accessKeyId: "YOUR_ACCESS_KEY", secretAccessKey: "YOUR_SECRET_KEY" } // Optional
  },
})

// Example: Initialize Memory with DynamoDB storage
const memory = new Memory({
  storage,
  options: {
    lastMessages: 10,
  },
})

使用 DynamoDB Local 進行本機開發
「使用 DynamoDB Local 進行本機開發」的直接連結

進行本機開發時，可以使用 DynamoDB Local。

執行 DynamoDB Local（例如使用 Docker）：
```
docker run -p 8000:8000 amazon/dynamodb-local
```

設定 DynamoDBStore 使用本機 endpoint：

import { DynamoDBStore } from '@mastra/dynamodb'

const storage = new DynamoDBStore({
  id: 'dynamodb-local',
  config: {
    tableName: 'mastra-single-table', // Ensure this table is created in your local DynamoDB
    region: 'localhost', // Can be any string for local, 'localhost' is common
    endpoint: 'http://localhost:8000',
    // For DynamoDB Local, credentials are not typically required unless configured.
    // If you've configured local credentials:
    // credentials: { accessKeyId: "fakeMyKeyId", secretAccessKey: "fakeSecretAccessKey" }
  },
})

你仍需在本機 DynamoDB 執行個體中建立資料表與 GSI，例如使用指向本機 endpoint 的 AWS CLI。

參數
「參數」的直接連結

id:

string

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

config.tableName:

string

DynamoDB 資料表名稱。

config.region?:

string

AWS region。預設為 'us-east-1'。進行本機開發時，可設為 'localhost' 或類似值。

config.endpoint?:

string

DynamoDB 的自訂 endpoint（例如本機開發使用的 'http://localhost:8000'）。

config.credentials?:

object

包含 accessKeyId 與 secretAccessKey 的 AWS credential 物件。若未提供，AWS SDK 會嘗試從環境變數、IAM role（例如 EC2/Lambda）或共用 AWS credential 檔案取得 credential。

config.ttl?:

object

用於自動讓資料到期的 TTL（Time To Live）設定。依實體型別設定：thread、message、trace、eval、workflow_snapshot、resource、score。各實體設定包括：enabled（boolean）、attributeName（string，預設：'ttl'）、defaultTtlSeconds（number）。

TTL（time to live）設定
「TTL（time to live）設定」的直接連結

DynamoDB TTL 可在指定期間後自動刪除項目，適用於下列使用情境：

成本最佳化：自動移除舊資料，降低儲存成本
資料生命週期管理：實作符合規範的保留政策
效能：避免資料表無限制增長
隱私合規：在指定期間後自動清除個人資料

啟用 TTL
「啟用 TTL」的直接連結

若要使用 TTL，必須：

在 DynamoDBStore 中設定 TTL（如下所示）
透過 AWS Console 或 CLI 在 DynamoDB 資料表上啟用 TTL，並指定 attribute 名稱（預設：ttl）

import { DynamoDBStore } from '@mastra/dynamodb'

const storage = new DynamoDBStore({
  name: 'dynamodb',
  config: {
    tableName: 'mastra-single-table',
    region: 'us-east-1',
    ttl: {
      // Messages expire after 30 days
      message: {
        enabled: true,
        defaultTtlSeconds: 30 * 24 * 60 * 60, // 30 days
      },
      // Threads expire after 90 days
      thread: {
        enabled: true,
        defaultTtlSeconds: 90 * 24 * 60 * 60, // 90 days
      },
      // Traces expire after 7 days with custom attribute name
      trace: {
        enabled: true,
        attributeName: 'expiresAt', // Custom TTL attribute
        defaultTtlSeconds: 7 * 24 * 60 * 60, // 7 days
      },
      // Workflow snapshots don't expire
      workflow_snapshot: {
        enabled: false,
      },
    },
  },
})

支援的實體型別
「支援的實體型別」的直接連結

可為下列實體型別設定 TTL：

實體	說明
`thread`	對話 thread
`message`	Thread 中的訊息
`trace`	可觀測性 Trace
`eval`	評估結果
`workflow_snapshot`	Workflow 狀態 snapshot
`resource`	使用者／資源資料
`score`	評分結果

enabled:

boolean

是否為此實體型別啟用 TTL。

attributeName?:

string

用於 TTL 的 DynamoDB attribute 名稱。必須與 DynamoDB 資料表上設定的 TTL attribute 相符。預設為 'ttl'。

defaultTtlSeconds?:

number

從項目建立時間起算的預設 TTL（秒）。經過此期間後，DynamoDB 會自動刪除項目。

在 DynamoDB 資料表上啟用 TTL
「在 DynamoDB 資料表上啟用 TTL」的直接連結

在程式碼中設定 TTL 後，必須在 DynamoDB 資料表本身啟用 TTL：

使用 AWS CLI：

aws dynamodb update-time-to-live \
  --table-name mastra-single-table \
  --time-to-live-specification "Enabled=true, AttributeName=ttl"

使用 AWS Console：

前往 DynamoDB console
選取資料表
前往「Additional settings」分頁
在「Time to Live (TTL)」下選取「Manage TTL」
啟用 TTL 並指定 attribute 名稱（預設：ttl）

備註

DynamoDB 會在項目到期後 48 小時內刪除。實際刪除前，項目仍可供查詢。

AWS IAM 權限
「AWS IAM 權限」的直接連結

執行程式碼的 IAM role 或使用者需要適當權限，才能與指定的 DynamoDB 資料表及其索引互動。以下是範例 policy。請將 ${YOUR_TABLE_NAME} 替換為實際資料表名稱，並將 ${YOUR_AWS_REGION} 與 ${YOUR_AWS_ACCOUNT_ID} 替換為適當的值。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeTable",
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query",
        "dynamodb:Scan",
        "dynamodb:BatchGetItem",
        "dynamodb:BatchWriteItem"
      ],
      "Resource": [
        "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}",
        "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}/index/*"
      ]
    }
  ]
}

重要注意事項
「重要注意事項」的直接連結

在深入探討架構細節前，使用 DynamoDB 儲存 adapter 時請記住下列重點：

外部資料表佈建： 使用此 adapter 前，_必須_自行建立並設定 DynamoDB 資料表及其 Global Secondary Index（GSI）。請遵循 TABLE_SETUP.md 中的指南。
單一資料表設計： 所有 Mastra 資料（thread、訊息等）都儲存在一個 DynamoDB 資料表中。這是刻意針對 DynamoDB 最佳化的設計選擇，與關聯式資料庫方式不同。
瞭解 GSI： 熟悉 GSI 的結構（依 TABLE_SETUP.md）對於瞭解資料擷取與可能的查詢模式很重要。
ElectroDB： 此 adapter 使用 ElectroDB 管理與 DynamoDB 的互動，為原始 DynamoDB 操作提供抽象層與型別安全。

架構方式
「架構方式」的直接連結

此儲存 adapter 搭配 ElectroDB 使用單一資料表設計模式，這是 DynamoDB 常見且建議的方式。其架構不同於通常使用多個資料表、且每個資料表專用於特定實體（thread、訊息等）的關聯式資料庫 adapter（例如 @mastra/pg 或 @mastra/libsql）。

此方式的主要特點：

DynamoDB 原生： 單一資料表設計針對 DynamoDB 的 key-value 與查詢功能最佳化，相較於模擬關聯式模型，通常可提供更好的效能與容量。
外部資料表管理： 與可能提供 helper function 透過程式碼建立資料表的某些 adapter 不同，此 adapter 預期 DynamoDB 資料表及其相關 Global Secondary Index（GSI）在使用前由外部佈建。使用 AWS CloudFormation 或 CDK 等工具的詳細指示，請參閱 TABLE_SETUP.md。此 adapter 只專注於與現有資料表結構互動。
透過介面維持一致性： 雖然底層儲存模型不同，此 adapter 仍遵循與其他 adapter 相同的 MastraStorage 介面，確保可在 Mastra Memory 元件中互換使用。

單一資料表中的 Mastra 資料
「單一資料表中的 Mastra 資料」的直接連結

在單一 DynamoDB 資料表中，不同 Mastra 資料實體（例如 Thread、訊息、Trace、評估與 Workflow）會透過 ElectroDB 管理與區分。ElectroDB 會為每種實體型別定義特定模型，包括唯一的 key 結構與 attribute，讓 adapter 能在同一資料表中有效率地儲存與擷取多種資料型別。

例如，Thread 項目的 primary key 可能是 THREAD#<threadId>，而屬於該 thread 的 Message 項目可能使用 THREAD#<threadId> 作為 partition key，並以 MESSAGE#<messageId> 作為 sort key。TABLE_SETUP.md 詳述的 Global Secondary Index（GSI）經過策略性設計，可支援不同實體間的常見存取模式，例如擷取某個 thread 的所有訊息，或查詢與 Workflow 關聯的 Trace。

單一資料表設計的優點
「單一資料表設計的優點」的直接連結

此實作搭配 ElectroDB 使用單一資料表設計模式，在 DynamoDB 情境中提供多項優點：

成本可能較低： 較少的資料表可簡化 Read/Write Capacity Unit（RCU/WCU）的佈建與管理，使用隨需容量時尤其如此。
效能更佳： 相關資料可共置，或透過 GSI 有效率地存取，讓常見存取模式能快速查詢。
簡化管理： 需要監控與備份的個別資料表較少，管理負擔也較低。
降低存取模式的複雜度： ElectroDB 有助於管理單一資料表上的項目型別與存取模式複雜度。
交易支援： 如有需要，DynamoDB 交易可跨同一資料表中儲存的不同「實體」型別使用。

功能「功能」的直接連結

安裝「安裝」的直接連結

先決條件「先決條件」的直接連結

使用方式「使用方式」的直接連結

基本用法「基本用法」的直接連結

使用 DynamoDB Local 進行本機開發「使用 DynamoDB Local 進行本機開發」的直接連結

參數「參數」的直接連結

id:

config.tableName:

config.region?:

config.endpoint?:

config.credentials?:

config.ttl?:

TTL（time to live）設定「TTL（time to live）設定」的直接連結

啟用 TTL「啟用 TTL」的直接連結

支援的實體型別「支援的實體型別」的直接連結

TTL 實體設定「TTL 實體設定」的直接連結

enabled:

attributeName?:

defaultTtlSeconds?:

在 DynamoDB 資料表上啟用 TTL「在 DynamoDB 資料表上啟用 TTL」的直接連結

AWS IAM 權限「AWS IAM 權限」的直接連結

重要注意事項「重要注意事項」的直接連結

架構方式「架構方式」的直接連結

單一資料表中的 Mastra 資料「單一資料表中的 Mastra 資料」的直接連結

單一資料表設計的優點「單一資料表設計的優點」的直接連結

功能
「功能」的直接連結

安裝
「安裝」的直接連結

先決條件
「先決條件」的直接連結

使用方式
「使用方式」的直接連結

基本用法
「基本用法」的直接連結

使用 DynamoDB Local 進行本機開發
「使用 DynamoDB Local 進行本機開發」的直接連結

參數
「參數」的直接連結

TTL（time to live）設定
「TTL（time to live）設定」的直接連結

啟用 TTL
「啟用 TTL」的直接連結

支援的實體型別
「支援的實體型別」的直接連結

TTL 實體設定
「TTL 實體設定」的直接連結

在 DynamoDB 資料表上啟用 TTL
「在 DynamoDB 資料表上啟用 TTL」的直接連結

AWS IAM 權限
「AWS IAM 權限」的直接連結

重要注意事項
「重要注意事項」的直接連結

架構方式
「架構方式」的直接連結

單一資料表中的 Mastra 資料
「單一資料表中的 Mastra 資料」的直接連結

單一資料表設計的優點
「單一資料表設計的優點」的直接連結