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

# DynamoDB 儲存空間

DynamoDB 儲存空間實作採用 [ElectroDB](https://electrodb.dev/) 單一資料表設計模式，為 Mastra 提供大容量、高效能的 NoSQL 資料庫解決方案。

> **不支援可觀測性:** DynamoDB 儲存空間**不支援 observability domain**。`MastraStorageExporter` 的 Trace 無法持久化至 DynamoDB；若 DynamoDB 是唯一的儲存 Provider，[Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) 的可觀測性功能也無法運作。若要啟用可觀測性，請使用[複合儲存空間](https://mastra.zisheng.pro/zh-TW/reference/storage/composite)，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

> **項目大小限制:** DynamoDB 規定**每個項目最大為 400 KB**。儲存包含圖片等 base64 編碼附件的訊息時，可能超過此限制。如需包含將附件上傳至外部儲存空間等替代做法，請參閱[處理大型附件](https://mastra.zisheng.pro/zh-TW/docs/memory/memory-processors)。

## 功能

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

## 安裝

**npm**:

```bash
npm install @mastra/dynamodb@latest
```

**pnpm**:

```bash
pnpm add @mastra/dynamodb@latest
```

**Yarn**:

```bash
yarn add @mastra/dynamodb@latest
```

**Bun**:

```bash
bun add @mastra/dynamodb@latest
```

## 先決條件

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

使用 AWS CloudFormation 或 AWS CDK 設定資料表的詳細指示，請參閱 [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)。繼續操作前，請確認資料表已依這些指示完成設定。

## 使用方式

### 基本用法

```typescript
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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html)。

1. **執行 DynamoDB Local（例如使用 Docker）：**

   ```bash
   docker run -p 8000:8000 amazon/dynamodb-local
   ```

2. **設定 `DynamoDBStore` 使用本機 endpoint：**

   ```typescript
   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）設定

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

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

### 啟用 TTL

若要使用 TTL，必須：

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

```typescript
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`             | 評分結果                 |

### TTL 實體設定

每種實體型別接受下列設定：

**enabled** (`boolean`): 是否為此實體型別啟用 TTL。

**attributeName** (`string`): 用於 TTL 的 DynamoDB attribute 名稱。必須與 DynamoDB 資料表上設定的 TTL attribute 相符。預設為 'ttl'。

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

### 在 DynamoDB 資料表上啟用 TTL

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

**使用 AWS CLI：**

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

**使用 AWS Console：**

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

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

## AWS IAM 權限

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

```json
{
  "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](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) 中的指南。
- **單一資料表設計：** 所有 Mastra 資料（thread、訊息等）都儲存在一個 DynamoDB 資料表中。這是刻意針對 DynamoDB 最佳化的設計選擇，與關聯式資料庫方式不同。
- **瞭解 GSI：** 熟悉 GSI 的結構（依 `TABLE_SETUP.md`）對於瞭解資料擷取與可能的查詢模式很重要。
- **ElectroDB：** 此 adapter 使用 ElectroDB 管理與 DynamoDB 的互動，為原始 DynamoDB 操作提供抽象層與型別安全。

## 架構方式

此儲存 adapter 搭配 [ElectroDB](https://electrodb.dev/) 使用**單一資料表設計模式**，這是 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](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)。此 adapter 只專注於與現有資料表結構互動。
- **透過介面維持一致性：** 雖然底層儲存模型不同，此 adapter 仍遵循與其他 adapter 相同的 `MastraStorage` 介面，確保可在 Mastra `Memory` 元件中互換使用。

### 單一資料表中的 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 情境中提供多項優點：

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