DynamoDB 存储

DynamoDB 存储实现使用 ElectroDB 的单表设计模式，为 Mastra 提供高容量、高性能的 NoSQL 数据库解决方案。

不支持 Observability

DynamoDB 存储不支持 Observability 域。来自 MastraStorageExporter 的 Trace 无法持久化到 DynamoDB；如果 DynamoDB 是你唯一的存储 Provider，Studio 的 Observability 功能将无法使用。要启用 Observability，请使用复合存储，将 Observability 数据路由到 ClickHouse 等受支持的 Provider。

项目大小限制

DynamoDB 强制执行最大 400 KB 的项目大小限制。存储带有图片等 base64 编码附件的消息时，可能会超出此限制。有关包括将附件上传到外部存储在内的解决方法，请参阅处理大型附件。

功能
功能的直接链接

面向所有 Mastra 存储需求的高效单表设计
基于 ElectroDB，提供类型安全的 DynamoDB 访问
支持 AWS 凭证、区域和端点
兼容用于开发的 AWS DynamoDB Local
存储 Thread、Message、Eval 和 Workflow 数据
为无服务器环境优化
可按实体类型配置 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 表，包括主键和全局二级索引（GSI）。此适配器要求从外部预配 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 以使用本地端点：

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（存活时间）配置
TTL（存活时间）配置的直接链接

DynamoDB TTL 可在指定时间后自动删除项目，适用于以下场景：

成本优化：自动移除旧数据以降低存储成本
数据生命周期管理：实施保留策略以满足合规要求
性能：防止表无限增长
隐私合规：在指定期限后自动清除个人数据

启用 TTL
启用 TTL的直接链接

要使用 TTL，你必须：

在 DynamoDBStore 中配置 TTL（如下所示）
通过 AWS Console 或 CLI 在 DynamoDB 表上启用 TTL，并指定属性名称（默认为 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`	对话线程
`message`	线程内的消息
`trace`	Observability Trace 数据
`eval`	评估结果
`workflow_snapshot`	Workflow 状态快照
`resource`	用户/资源数据
`score`	评分结果

TTL 实体配置
TTL 实体配置的直接链接

每个实体类型均接受以下配置：

enabled:

boolean

是否为此实体类型启用 TTL。

attributeName?:

string

用于 TTL 的 DynamoDB 属性名称。必须与 DynamoDB 表上配置的 TTL 属性匹配。默认为 '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 控制台
选择你的表
前往“Additional settings”选项卡
在“Time to Live (TTL)”下选择“Manage TTL”
启用 TTL 并指定属性名称（默认为 ttl）

备注

DynamoDB 会在项目过期后的 48 小时内删除它们。项目在实际删除前仍可查询。

AWS IAM 权限
AWS IAM 权限的直接链接

执行代码的 IAM 角色或用户需要适当的权限，才能与指定的 DynamoDB 表及其索引交互。以下是示例策略。请将 ${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 存储适配器时请牢记以下要点：

**外部预配表：**此适配器_要求_你在使用前自行创建和配置 DynamoDB 表及其全局二级索引（GSI）。请遵循 TABLE_SETUP.md 中的指南。
**单表设计：**所有 Mastra 数据（线程、消息等）都存储在一张 DynamoDB 表中。这是针对 DynamoDB 优化的有意设计选择，不同于关系型数据库的方案。
**理解 GSI：**熟悉 GSI 的结构（见 TABLE_SETUP.md）对于理解数据检索和潜在查询模式很重要。
**ElectroDB：**此适配器使用 ElectroDB 管理与 DynamoDB 的交互，为原始 DynamoDB 操作提供抽象层和类型安全性。

架构方法
架构方法的直接链接

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

此方案的关键方面：

**DynamoDB 原生：**单表设计针对 DynamoDB 的键值和查询能力进行了优化，与模拟关系模型相比通常可带来更好的性能和容量。
外部管理表：不同于某些提供通过代码创建表的辅助函数的适配器，此适配器要求在使用前从外部预配 DynamoDB 表及其关联的全局二级索引（GSI）。有关使用 AWS CloudFormation 或 CDK 等工具的详细说明，请参阅 TABLE_SETUP.md。此适配器仅负责与预先存在的表结构交互。
**通过接口保持一致性：**尽管底层存储模型不同，此适配器仍遵循与其他适配器相同的 MastraStorage 接口，确保可在 Mastra Memory 组件中互换使用。

单表中的 Mastra 数据
单表中的 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 场景下具有以下优势：

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

功能功能的直接链接

安装安装的直接链接

前提条件前提条件的直接链接

使用方法使用方法的直接链接

基本用法基本用法的直接链接

使用 DynamoDB Local 进行本地开发使用 DynamoDB Local 进行本地开发的直接链接

参数参数的直接链接

id:

config.tableName:

config.region?:

config.endpoint?:

config.credentials?:

config.ttl?:

TTL（存活时间）配置TTL（存活时间）配置的直接链接

启用 TTL启用 TTL的直接链接

支持的实体类型支持的实体类型的直接链接

TTL 实体配置TTL 实体配置的直接链接

enabled:

attributeName?:

defaultTtlSeconds?:

在 DynamoDB 表上启用 TTL在 DynamoDB 表上启用 TTL的直接链接

AWS IAM 权限AWS IAM 权限的直接链接

重要注意事项重要注意事项的直接链接

架构方法架构方法的直接链接

单表中的 Mastra 数据单表中的 Mastra 数据的直接链接

单表设计的优势单表设计的优势的直接链接

功能
功能的直接链接

安装
安装的直接链接

前提条件
前提条件的直接链接

使用方法
使用方法的直接链接

基本用法
基本用法的直接链接

使用 DynamoDB Local 进行本地开发
使用 DynamoDB Local 进行本地开发的直接链接

参数
参数的直接链接

TTL（存活时间）配置
TTL（存活时间）配置的直接链接

启用 TTL
启用 TTL的直接链接

支持的实体类型
支持的实体类型的直接链接

TTL 实体配置
TTL 实体配置的直接链接

在 DynamoDB 表上启用 TTL
在 DynamoDB 表上启用 TTL的直接链接

AWS IAM 权限
AWS IAM 权限的直接链接

重要注意事项
重要注意事项的直接链接

架构方法
架构方法的直接链接

单表中的 Mastra 数据
单表中的 Mastra 数据的直接链接

单表设计的优势
单表设计的优势的直接链接