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

# DynamoDB 存储

DynamoDB 存储实现使用 [ElectroDB](https://electrodb.dev/) 的单表设计模式，为 Mastra 提供高容量、高性能的 NoSQL 数据库解决方案。

> **不支持 Observability:** DynamoDB 存储**不支持 Observability 域**。来自 `MastraStorageExporter` 的 Trace 无法持久化到 DynamoDB；如果 DynamoDB 是你唯一的存储 Provider，[Studio](https://mastra.zisheng.pro/docs/studio/overview) 的 Observability 功能将无法使用。要启用 Observability，请使用[复合存储](https://mastra.zisheng.pro/reference/storage/composite)，将 Observability 数据路由到 ClickHouse 等受支持的 Provider。

> **项目大小限制:** DynamoDB 强制执行**最大 400 KB 的项目大小限制**。存储带有图片等 base64 编码附件的消息时，可能会超出此限制。有关包括将附件上传到外部存储在内的解决方法，请参阅[处理大型附件](https://mastra.zisheng.pro/docs/memory/memory-processors)。

## 功能

- 面向所有 Mastra 存储需求的高效单表设计
- 基于 ElectroDB，提供类型安全的 DynamoDB 访问
- 支持 AWS 凭证、区域和端点
- 兼容用于开发的 AWS DynamoDB Local
- 存储 Thread、Message、Eval 和 Workflow 数据
- 为无服务器环境优化
- 可按实体类型配置 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 表，包括主键和全局二级索引（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（Time To Live）配置。可按实体类型配置：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`            | 对话线程                   |
| `message`           | 线程内的消息                 |
| `trace`             | Observability 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 数据（线程、消息等）都存储在一张 DynamoDB 表中。这是针对 DynamoDB 优化的有意设计选择，不同于关系型数据库的方案。
- \*\*理解 GSI：\*\*熟悉 GSI 的结构（见 `TABLE_SETUP.md`）对于理解数据检索和潜在查询模式很重要。
- \*\*ElectroDB：\*\*此适配器使用 ElectroDB 管理与 DynamoDB 的交互，为原始 DynamoDB 操作提供抽象层和类型安全性。

## 架构方法

此存储适配器使用基于 [ElectroDB](https://electrodb.dev/) 的**单表设计模式**，这是 DynamoDB 中常见且推荐的方案。从架构上看，它不同于关系型数据库适配器（如 `@mastra/pg` 或 `@mastra/libsql`）：后者通常使用多张表，每张表专用于特定实体（线程、消息等）。

此方案的关键方面：

- \*\*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>`，而属于该线程的 `Message` 项目可能使用 `THREAD#<threadId>` 作为分区键，并使用 `MESSAGE#<messageId>` 作为排序键。`TABLE_SETUP.md` 中详述的全局二级索引（GSI）经过策略性设计，以支持这些不同实体的常见访问模式，例如获取某个线程的全部消息或查询与某个 Workflow 关联的 Trace。

### 单表设计的优势

此实现采用了基于 ElectroDB 的单表设计模式，在 DynamoDB 场景下具有以下优势：

1. \*\*成本可能更低：\*\*较少的表可简化读/写容量单位（RCU/WCU）的预配和管理，尤其是在使用按需容量时。
2. \*\*性能更好：\*\*相关数据可以共置，或通过 GSI 高效访问，从而支持对常见访问模式的快速查找。
3. \*\*管理更简便：\*\*需要监控和备份的独立表更少，管理工作也更少。
4. \*\*访问模式复杂度更低：\*\*ElectroDB 有助于管理单表中的项目类型和访问模式的复杂性。
5. \*\*支持事务：\*\*如有需要，DynamoDB 事务可跨同一张表中存储的不同“实体”类型使用。