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

# DynamoDB 儲存

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

> **不支援可觀測性:** DynamoDB 儲存**不支援可觀測性領域**。來自 `MastraStorageExporter` 的 Trace 無法持久化至 DynamoDB，而當 DynamoDB 是唯一的儲存 Provider 時，[Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 的可觀測性功能亦無法運作。如要啟用可觀測性，請使用[複合儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/composite)，將可觀測性資料路由至 ClickHouse 等受支援的 Provider。

> **項目大小限制:** DynamoDB 強制執行 **400 KB 的項目大小上限**。儲存包含圖片等 base64 編碼附件的訊息時，可能會超出此限制。請參閱[處理大型附件](https://mastra.zisheng.pro/zh-HK/docs/memory/memory-processors)，了解包括將附件上載至外部儲存空間在內的解決方法。

## 功能

- 高效的單一資料表設計，滿足 Mastra 的所有儲存需要
- 以 ElectroDB 為基礎，提供型別安全的 DynamoDB 存取
- 支援 AWS 憑證、區域及端點
- 與供開發使用的 AWS DynamoDB Local 相容
- 儲存 Thread、Message、Eval 及 Workflow 資料
- 針對無伺服器環境最佳化
- 可按實體類型設定 TTL（存留時間），讓資料自動過期

## 安裝

**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 資料表，包括主索引鍵及全域次要索引（GSI）。此配接器要求 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` 使用本機端點：**

   ```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，例如使用指向本機端點的 AWS CLI。

## 參數

**id** (`string`): 此儲存執行個體的唯一識別碼。

**config.tableName** (`string`): DynamoDB 資料表的名稱。

**config.region** (`string`): AWS 區域。預設為 'us-east-1'。進行本機開發時，可設為 'localhost' 或類似值。

**config.endpoint** (`string`): DynamoDB 的自訂端點（例如供本機開發使用的 'http\://localhost:8000'）。

**config.credentials** (`object`): 包含 accessKeyId 及 secretAccessKey 的 AWS 憑證物件。如未提供，AWS SDK 會嘗試從環境變數、IAM 角色（例如供 EC2/Lambda 使用），或共用 AWS 憑證檔案取得憑證。

**config.ttl** (`object`): 用於讓資料自動過期的 TTL（存留時間）設定。可按實體類型設定：thread、message、trace、eval、workflow\_snapshot、resource、score。每個實體設定包括：enabled（boolean）、attributeName（string，預設：'ttl'）、defaultTtlSeconds（number）。

## TTL（存留時間）設定

DynamoDB TTL 可讓你在指定時限後自動刪除項目，適用於以下使用情境：

- **成本最佳化**：自動移除舊資料，以降低儲存成本
- **資料生命週期管理**：實施保留政策以符合法規要求
- **效能**：防止資料表無限增長
- **私隱合規**：在指定時限後自動清除個人資料

### 啟用 TTL

如要使用 TTL，你必須：

1. **在 DynamoDBStore 中設定 TTL**（如下所示）
2. 透過 AWS Console 或 CLI **在 DynamoDB 資料表上啟用 TTL**，並指定屬性名稱（預設：`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 狀態快照 |
| `resource`          | 使用者／資源資料      |
| `score`             | 評分結果          |

### TTL 實體設定

每種實體類型均接受以下設定：

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

**attributeName** (`string`): 用於 TTL 的 DynamoDB 屬性名稱。必須與 DynamoDB 資料表上設定的 TTL 屬性相符。預設為 '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 主控台
2. 選取你的資料表
3. 前往「Additional settings」分頁
4. 在「Time to Live (TTL)」下選取「Manage TTL」
5. 啟用 TTL 並指定屬性名稱（預設：`ttl`）

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

## AWS IAM 權限

執行程式碼的 IAM 角色或使用者需要具備適當權限，才能與指定的 DynamoDB 資料表及其索引互動。以下是政策範例。請將 `${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 儲存配接器時請留意以下重點：

- **外部資料表佈建：** 此配接器\_要求\_你在使用前自行建立及設定 DynamoDB 資料表及其全域次要索引（GSI）。請按照 [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) 中的指南操作。
- **單一資料表設計：** 所有 Mastra 資料（Thread、Message 等）均儲存於一個 DynamoDB 資料表中。這是針對 DynamoDB 最佳化的刻意設計選擇，與關聯式資料庫的方式不同。
- **了解 GSI：** 熟悉 GSI 的結構（如 `TABLE_SETUP.md` 所述），對了解資料擷取及潛在查詢模式非常重要。
- **ElectroDB：** 此配接器使用 ElectroDB 管理與 DynamoDB 的互動，在原始 DynamoDB 操作之上提供抽象層及型別安全保障。

## 架構方式

此儲存配接器配合 [ElectroDB](https://electrodb.dev/) 採用**單一資料表設計模式**，這是 DynamoDB 常見且建議使用的方式。其架構有別於關聯式資料庫配接器（例如 `@mastra/pg` 或 `@mastra/libsql`）；後者通常使用多個資料表，每個資料表專門供特定實體（Thread、Message 等）使用。

此方式的主要特點包括：

- **DynamoDB 原生設計：** 單一資料表設計針對 DynamoDB 的鍵值及查詢能力最佳化；與模擬關聯式模型相比，通常能帶來更佳效能及容量。
- **外部資料表管理：** 部分配接器可能會提供輔助函式，以透過程式碼建立資料表，但此配接器**要求在使用前於外部佈建 DynamoDB 資料表及其相關全域次要索引（GSI）**。如需使用 AWS CloudFormation 或 CDK 等工具的詳細指示，請參閱 [TABLE\_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md)。此配接器只負責與預先存在的資料表結構互動。
- **透過介面保持一致：** 儘管底層儲存模型不同，此配接器仍遵循與其他配接器相同的 `MastraStorage` 介面，確保它可在 Mastra `Memory` 元件中互換使用。

### 單一資料表中的 Mastra 資料

在單一 DynamoDB 資料表中，不同 Mastra 資料實體（例如 Thread、Message、Trace、Eval 及 Workflow）會使用 ElectroDB 管理及區分。ElectroDB 為每種實體類型定義特定模型，包括獨特的索引鍵結構及屬性。這讓配接器可在同一資料表中高效儲存及擷取不同資料類型。

例如，`Thread` 項目的主索引鍵可能類似 `THREAD#<threadId>`，而屬於該 Thread 的 `Message` 項目可能會使用 `THREAD#<threadId>` 作為分割區索引鍵，並使用 `MESSAGE#<messageId>` 作為排序索引鍵。`TABLE_SETUP.md` 詳述的全域次要索引（GSI）經過策略性設計，可支援這些不同實體的常見存取模式，例如擷取某個 Thread 的所有訊息，或查詢與某個 Workflow 相關的 Trace。

### 單一資料表設計的優點

此實作配合 ElectroDB 採用單一資料表設計模式，在 DynamoDB 的使用情境中具備多項優點：

1. **成本可能較低：** 較少的資料表可簡化讀取／寫入容量單位（RCU/WCU）的佈建及管理，使用隨需容量時尤其如此。
2. **效能更佳：** 相關資料可放置在一起，或透過 GSI 高效存取，讓常見存取模式能夠快速查找。
3. **簡化管理：** 需要監察及備份的獨立資料表較少，管理工作亦相應減少。
4. **降低存取模式的複雜程度：** ElectroDB 有助管理單一資料表上的項目類型及存取模式所帶來的複雜性。
5. **支援交易：** 如有需要，DynamoDB 交易可跨同一資料表內儲存的不同「實體」類型使用。