DynamoDBストレージ

DynamoDBストレージ実装は、ElectroDBによるシングルテーブル設計パターンを使用し、大容量で高性能なNoSQLデータベースソリューションをMastraに提供します。

Observabilityはサポートされていません

DynamoDBストレージはObservabilityドメインをサポートしていません。MastraStorageExporterのトレースをDynamoDBに永続化できず、DynamoDBだけをストレージProviderとして使用するとStudioのObservability機能も動作しません。Observabilityを有効にするには、複合ストレージを使用して、ObservabilityデータをClickHouseなどの対応Providerに振り分けてください。

項目サイズの上限

DynamoDBでは、項目の最大サイズが400 KBに制限されています。画像など、base64でエンコードされた添付ファイルを含むメッセージを保存すると、この上限を超える場合があります。添付ファイルを外部ストレージにアップロードする方法など、回避策については大きな添付ファイルの処理を参照してください。

機能

• Mastraのあらゆるストレージ要件に対応する効率的なシングルテーブル設計
• 型安全なDynamoDBアクセスを提供するElectroDBを基盤として使用
• AWSの認証情報、リージョン、エンドポイントをサポート
• 開発用のAWS DynamoDB Localと互換性あり
• Thread、Message、Eval、Workflowのデータを保存
• サーバーレス環境向けに最適化
• エンティティ型ごとに、データを自動的に期限切れにするTTL（Time To Live）を設定可能

インストール

npm

npm install @mastra/dynamodb@latest

pnpm

pnpm add @mastra/dynamodb@latest

Yarn

yarn add @mastra/dynamodb@latest

Bun

bun add @mastra/dynamodb@latest

前提条件

このパッケージを使用する前に、主キーとGlobal Secondary Index（GSI）を含む特定の構造を持つDynamoDBテーブルを作成する必要があります。このアダプターは、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を使用できます。

1. DynamoDB Localを実行します（例: Dockerを使用）。

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

2. ローカルエンドポイントを使用するように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" }
     },
   })

   ローカルエンドポイントを指定したAWS CLIなどを使用して、ローカルのDynamoDBインスタンスにもテーブルとGSIを作成する必要があります。

パラメーター

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（Time To Live）の設定

DynamoDB TTLを使用すると、次のユースケースで指定期間後に項目を自動削除できます。

• コスト最適化: 古いデータを自動削除してストレージコストを削減
• データライフサイクル管理: コンプライアンスに必要な保持ポリシーを実装
• パフォーマンス: テーブルが無制限に増え続けるのを防止
• プライバシー対応: 指定期間後に個人データを自動消去

TTLを有効にする

TTLを使用するには、次の操作が必要です。

1. DynamoDBStoreでTTLを設定する（以下を参照）
2. 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	会話Thread
message	Thread内のメッセージ
trace	Observabilityトレース
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を使用する場合:

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}を適切な値に置き換えてください。

{
  "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テーブルとGlobal Secondary Index（GSI）を自分で作成、設定する_必要があります_。TABLE_SETUP.mdのガイドに従ってください。
• シングルテーブル設計: Mastraのすべてのデータ（Thread、Messageなど）は、1つのDynamoDBテーブルに保存されます。これはDynamoDB向けに最適化された意図的な設計であり、リレーショナルデータベースの方式とは異なります。
• GSIの理解: データの取得方法と想定されるクエリパターンを理解するには、TABLE_SETUP.mdに記載されたGSIの構造を把握することが重要です。
• ElectroDB: このアダプターはElectroDBを使用してDynamoDBとのやり取りを管理し、生のDynamoDB操作を抽象化して型安全性を提供します。

アーキテクチャ上のアプローチ

このストレージアダプターは、DynamoDBで一般的かつ推奨される手法である、ElectroDBを使ったシングルテーブル設計パターンを採用しています。通常はエンティティ（Thread、Messageなど）ごとに専用テーブルを使用する、@mastra/pgや@mastra/libsqlなどのリレーショナルデータベースアダプターとは、アーキテクチャが異なります。

このアプローチの主な特徴は次のとおりです。

• DynamoDBネイティブ: シングルテーブル設計はDynamoDBのキーバリュー機能とクエリ機能に最適化されており、リレーショナルモデルを模倣する場合よりも高いパフォーマンスと容量効率を得られることがよくあります。
• 外部でのテーブル管理: コードからテーブルを作成するヘルパー関数を提供するアダプターとは異なり、このアダプターは、使用前にDynamoDBテーブルと関連するGlobal Secondary Index（GSI）が外部でプロビジョニングされていることを前提とします。AWS CloudFormationやCDKなどを使用する詳しい手順については、TABLE_SETUP.mdを参照してください。このアダプターは、既存のテーブル構造とのやり取りだけを担います。
• インターフェースによる一貫性: 基盤となるストレージモデルは異なりますが、このアダプターは他のアダプターと同じMastraStorageインターフェースに準拠しているため、MastraのMemoryコンポーネント内で置き換えて使用できます。

シングルテーブル内のMastraデータ

単一のDynamoDBテーブル内では、Thread、Message、Trace、Eval、Workflowなど、さまざまなMastraデータエンティティをElectroDBで管理し、区別します。ElectroDBはエンティティ型ごとに、固有のキー構造と属性を含むモデルを定義します。これにより、同じテーブル内で多様なデータ型を効率よく保存、取得できます。

たとえば、Thread項目の主キーにはTHREAD#<threadId>を使用し、そのThreadに属するMessage項目では、パーティションキーにTHREAD#<threadId>、ソートキーにMESSAGE#<messageId>を使用できます。TABLE_SETUP.mdで詳しく説明しているGlobal Secondary Index（GSI）は、Threadのすべてのメッセージの取得や、Workflowに関連付けられたトレースの照会など、異なるエンティティにまたがる一般的なアクセスパターンをサポートするよう戦略的に設計されています。

シングルテーブル設計の利点

この実装はElectroDBによるシングルテーブル設計パターンを採用し、DynamoDBにおいて次の利点をもたらします。

1. コスト削減（見込まれる場合）: テーブル数が少ないため、特にオンデマンドキャパシティでは、Read/Write Capacity Unit（RCU/WCU）のプロビジョニングと管理を簡素化できます。
2. パフォーマンス向上: 関連データを同じ場所に配置するか、GSIを介して効率的にアクセスできるため、一般的なアクセスパターンで高速に検索できます。
3. 管理の簡素化: 監視、バックアップするテーブルが少なくなり、管理対象を削減できます。
4. アクセスパターンの複雑さを軽減: ElectroDBは、単一テーブル上の項目型とアクセスパターンの複雑さを管理します。
5. トランザクションのサポート: 必要に応じて、同じテーブルに保存された異なる「エンティティ」型にまたがってDynamoDBトランザクションを使用できます。