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

# DynamoDBストレージ

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

> **Observabilityはサポートされていません:** DynamoDBストレージは**Observabilityドメインをサポートしていません**。`MastraStorageExporter`のトレースをDynamoDBに永続化できず、DynamoDBだけをストレージProviderとして使用すると[Studio](https://mastra.zisheng.pro/ja/docs/studio/overview)のObservability機能も動作しません。Observabilityを有効にするには、[複合ストレージ](https://mastra.zisheng.pro/ja/reference/storage/composite)を使用して、ObservabilityデータをClickHouseなどの対応Providerに振り分けてください。

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

## 機能

- Mastraのあらゆるストレージ要件に対応する効率的なシングルテーブル設計
- 型安全なDynamoDBアクセスを提供するElectroDBを基盤として使用
- 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
```

## 前提条件

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

   ローカルエンドポイントを指定した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`）を指定する

```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`             | 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を使用する場合:**

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

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

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

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

- **DynamoDBネイティブ:** シングルテーブル設計はDynamoDBのキーバリュー機能とクエリ機能に最適化されており、リレーショナルモデルを模倣する場合よりも高いパフォーマンスと容量効率を得られることがよくあります。
- **外部でのテーブル管理:** コードからテーブルを作成するヘルパー関数を提供するアダプターとは異なり、このアダプターは、使用前に**DynamoDBテーブルと関連するGlobal Secondary Index（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テーブル内では、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トランザクションを使用できます。