dynamodbでテーブル設計する際に気にしておくことを整理

RDBMS のように「テーブルを正規化して JOIN」するのではなく、アクセスパターンに応じて非正規化したり、項目を集約して保存する設計を行うのが基本となる。

RDBMSのテーブルを例に考える (例: ゲームプロダクトにありそうなテーブル)

users テーブル (AIが作成)

CREATE TABLE IF NOT EXISTS `users` (
  `id` VARCHAR(255) PRIMARY KEY COMMENT 'ユーザーID',
  `provider_id` VARCHAR(255) PRIMARY KEY COMMENT '外部の認証サービスで払い出されるユーザを特定するための一意のID',
  `username` VARCHAR(255) COMMENT 'ユーザー名',
  `email` VARCHAR(255) COMMENT 'ユーザーのメールアドレス',
  `role` ENUM('general', 'admin', 'beta_tester') NOT NULL COMMENT 'ユーザーの権限',
  `status` ENUM('active', 'inactive', 'banned') NOT NULL COMMENT 'ユーザーのステータス',
  `rank` SMALLINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '現在のユーザーランク',
  `exp` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '累積経験値',
  `stamina_max` SMALLINT UNSIGNED NOT NULL DEFAULT 100 COMMENT '最大スタミナ',
  `stamina_current` SMALLINT UNSIGNED NOT NULL DEFAULT 100 COMMENT '現在のスタミナ',
  `team_slot_limit` TINYINT UNSIGNED NOT NULL DEFAULT 5 COMMENT 'ユーザーが保有できるチーム数上限',
  `last_login_at` DATETIME NOT NULL COMMENT '最終ログイン日時',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX `idx_email` (`email`),
  INDEX `idx_role` (`role`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

アクセスパターンをまとめると以下のようなイメージになる

各カラムのアクセスパターン

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-design.html
https://aws.amazon.com/jp/builders-flash/202404/learn-dynamodb-primary-key/

まずざっくり両者の違い

プライマリーキー:

• データを一意に識別するキーのこと。
• パーティションキー単独でもPKになるし、パーティションキーとソートキーの組み合わせでもPKとすることができる。
  • 単一キーの場合: user_id
  • 複合キーの場合: user_id & timestamp (2025-07-18T10:00:00)

パーティションキー:

• データを物理的にどのパーティション（ストレージ）に保存するかを決めるキー
• 内部ではこのキーをhashして分散配置される。
• 同じパーティションキーのレコードは同じ物理パーティションに保存されるイメージ

整理するとこのようなイメージ

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey

When you create a table, in addition to the table name, you must specify the primary key of the table. The primary key uniquely identifies each item in the table, so that no two items can have the same key.

• テーブル作成時には、テーブル名に加えてプライマリキーの指定が必須。
• プライマリキーはアイテムを一意に識別する役割を持ち、同じキーのアイテムは複数存在できない。

プライマリキーの種類

単一プライマリーキーと複合プライマリーキーの2種類が存在。

アクセスやクエリの柔軟性

• 単一キーテーブル:
  • パーティションキー（例: user_id）を指定すれば直接アクセス可能。
• 複合キーテーブル:
  • パーティションキー（例: artist_id）とソートキー（例: song_title）の組み合わせでアクセス。
  • artist_id だけ指定 → そのアーティストのすべての曲が取得可能
  • artist_id + song_title の範囲指定 → 曲の一部を絞り込んで取得可能

補足事項

Each primary key attribute must be a scalar (meaning that it can hold only a single value). The only data types allowed for primary key attributes are string, number, or binary. There are no such restrictions for other, non-key attributes.

• プライマリーキーの属性はスカラ値（単一値）のみ設定が可能。

• 利用可能な型としては以下

  • string: 文字列
  • number: 数値
  • binary: バイト列（いわゆる文字列ではない生のデータ、Goだと[]byte、Javaなら
  • ByteBuffer、JSONではBase64エンコードされた文字列）

• 非キー属性はプライマリーキーでは使用できない。

  • List, Map, Boolean, Null, Set

jsonのイメージ

{
  "user_id": "123", // プライマリキー（String型）
  "profile": {
    "name": "Alice",
    "age": 30,
    "hobbies": ["tennis", "reading"],
    "address": {
      "city": "Tokyo",
      "zip": "123-4567"
    }
  }
}

ソートキーについて

• パーティションキーと組み合わせてアイテムを一意に識別できるようにすることを目的として利用されるキーのこと。
• 例えば、チャットテーブル等を例にした場合、以下のように user_id と timestamp の 2つでアイテムが一意になる。※timestamp がソートキーになる。

※本番だと誰が誰に送ったか、等の情報も必要だが便宜上簡単なテーブルにしている

ソートキーの役割や利点を整理すると以下のようなイメージになる。

ソートキーを生かした検索を行う際の Query 例は以下のようなイメージになる。

case1: 1人のユーザの全メッセージを取得する

PartitionKey = 'user123'

→ user123 の全メッセージが ソートキー順（つまり日時順）で取得できる

case2: 特定期間のデータだけ取得（日時の範囲指定）

PartitionKey = 'user123'
AND SortKey BETWEEN '2025-07-01' AND '2025-07-31'

→ user123 のメッセージのうち、2025年7月中のメッセージのみを取得できる。

Query 使用可能なソートキーを用いた条件指定は以下

※between や > などの条件は、ISO8601形式（YYYY-MM-DDTHH:MM:SSZ）だと文字列比較でも時系列順で動作する模様。※日付 → 時 → 分 → 秒 と先頭から順番に並んでいるので、文字列比較がそのまま時系列比較になるのかも？
※ begins_with は 前方一致 で、"2025-07" のように年月単位でまとめて取得するのに便利。

ソートキーについて整理

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-sort-keys.html

Well-designed sort keys have two key benefits:
They gather related information together in one place where it can be queried efficiently. Careful design of the sort key lets you retrieve commonly needed groups of related items using range queries with operators such as begins_with, between, >, <, and so on.
Composite sort keys let you define hierarchical (one-to-many) relationships in your data that you can query at any level of the hierarchy.

• 関連データを同一パーティション内に集約させることができれば、begins_with、between、>、< などの演算子で効率的にアイテムを取得できるようになる。
• begins_with() クエリは文字列ベースで範囲検索ができるため、
  文字列階層を「#」などのセパレータで構築することで、任意の粒度で柔軟な検索が可能になる（1対多関係のような階層構造の表現が可能）

• 各プレイヤーが個別のパーティション（pk）を持つ
• sk に階層構造を保持しつつ、分散性能も確保できる

query例

1. プレイヤー1234のキャラ01のインベントリアイテムを全部取得

pk = "player#1234"
begins_with(sk, "char#01#inventory")

2. プレイヤー1234のキャラ01の剣（sword001）の強化履歴を取得

pk = "player#1234"
begins_with(sk, "char#01#enhance#sword001")

3. プレイヤー1234のメタ情報やキャラクター情報をまとめて取得

pk = "player#1234"
(sk = "metadata" OR begins_with(sk, "char#"))

4. プレイヤー1234のキャラ01に関するすべての情報を取得

pk = "player#1234"
begins_with(sk, "char#01")

• プレイヤーごとにパーティションキーが割り当てられ、個別のパーティションで管理
• sk に階層構造や種類を含めてデータを分類
• メタ情報やキャラクター情報、装備や強化履歴などを柔軟に取得可能

query例

1. プレイヤー1234のメタ情報を取得

pk = "player#1234"
sk = "metadata"

2. プレイヤー1234のキャラクター一覧を取得

pk = "player#1234"
begins_with(sk, "char#")

3. プレイヤー1234のキャラ01の装備（インベントリ）を全部取得

pk = "player#1234"
begins_with(sk, "char#01#inventory")

4. プレイヤー1234のキャラ01の剣（sword001）の強化履歴を取得

pk = "player#1234"
sk = "char#02"

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-uniform-load.html

The partition key portion of a table's primary key determines the logical partitions in which a table's data is stored. This in turn affects the underlying physical partitions. A partition key design that doesn't distribute I/O requests effectively can create "hot" partitions that result in throttling and use your provisioned I/O capacity inefficiently.

• 各パーティションへのアクセスが偏り過ぎないように設計する必要あり。
• dynamodb はデータを複数のパーティションに分けて保存するため、一部のデータばかりにアクセスが集中するとレイテンシの原因となる。
• よって、どのデータにも均一にアクセスされるような主キーをまずは検討するところから始まる。

• 1つのパーティションで1秒間に処理できる作業量が決まっている。
• 以下は比較的少量のデータ（1~4KB程度）の場合の制限
  • 読み取り: 1秒間に最大3,000回
  • 書き込み: 1秒間に最大1,000回

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-partition-key-uniform-load.html

偏ったパーティションキーになってしまった場合（つまり一部のパーティションばかりに頻繁にアクセスされる状態にしてしまった場合）は以下のようなケースが考えられる。

• その物理パーティションだけにリクエストが集中してしまう。
• スロットリング（処理制限）が発生しやすくなってしまう。
• 結果的に、用意したプロビジョン済みスループット（またはオンデマンドの能力）を無駄にしてしまう。※DynamoDB全体としてはまだ余裕があるにも関わらず、一部のパーティションだけが詰まってしまい処理できなくなる（スロットルされる）という状況

凡例（パーティションが4つに分かれているとした場合）

[全体スループット]      [使われ方]
------------------    --------------------------
最大書き込み能力       Aパーティション：1000 WCU ← ✕ 上限到達でスロットル
  = 4000 WCU          Bパーティション：200 WCU
                      Cパーティション：50 WCU
                      Dパーティション：0 WCU

極端な例で、例えばテーブルが4つの物理パーティションに分割されていることを前提として、全ユーザーのレコードが以下のような形で保存されているとした場合

{
  "status_code": "active",       // パーティションキー
  "user_id": "user_12345",
  ...
}

結果として起き得ること

活性化したプロダクトの場合、ユーザの多くは active が大半を占めることになるため、リクエストが active という1つのパーティションキーに集中する。
→その1つの物理パーティションだけが高負荷になり、最大スループットの1,000WCUに即座に到達してしまう。
※ほか3つの物理パーティションはほとんど使われずにいる状態。

想定シナリオ

• アプリに 100 万人のユーザがいて、それぞれがプロフィールデータを持つ。
• パーティションキーは user_id

分散される理由

• 各 user_id がユニークであり、アクセスも均等に分散されやすいため、リクエストが物理パーティション全体にバランスよく分散される。
• 特定ユーザだけが爆発的にアクセスされない限り「ホットパーティション」になりにくい構成になる。

terraform でテーブル定義するとこのような形式になる

resource "aws_dynamodb_table" "users" {
  name           = "Users"
  billing_mode   = "PAY_PER_REQUEST"
  hash_key       = "user_id"

  attribute {
    name = "user_id"
    type = "N"  # 数値型
  }

  tags = {
    Environment = "dev"
    Project     = "GameBackend"
  }
}

データ形式

{
  "Item": {
    "user_id": { "N": "100001" },
    "name": { "S": "Alice" },
    "email": { "S": "alice@example.com" }
  }
}

想定シナリオ

• IoTデバイス（例えば温度センサなど）が1分毎にデータ送信される。
• 特定の device_id にアクセスが集中してスループットが偏るのを防ぐ必要がある。
• device_id#ランダム文字列 にすることでパーティションキーを設計することで回避できる。

分散される理由

• 本来、device-abc 1個に集中するアクセスが、device-abc#1, device-abc#2, device-abc#3 のように異なるキーに分かれることで物理パーティションにも分散されやすくなる。
• 注意点として、クエリで取得する際には、begins_with(device_id, "device-abc") 等でデータアクセスする工夫が必要。

terraform でテーブル定義するとこのような形式になる

resource "aws_dynamodb_table" "device_temperature_table" {
  name           = "DeviceTemperature"
  billing_mode   = "PAY_PER_REQUEST"
  hash_key       = "partition_key"

  attribute {
    name = "partition_key"
    type = "S"
  }
}

データ形式

{
  "partition_key": { "S": "device-abc#1" },
  "timestamp": { "S": "2025-07-17T00:01:00" },
  "temperature": { "N": "24.3" }
}

想定シナリオ

• ユーザが予約操作を行うたびにイベントが記録される。
• 書き込みが「ある時間帯」に集中しやすいので、created_at 単独だとホットパーティションになる。
• そこで created_at#user_id をパーティションキーにすることで偏りが出ないようにする。

分散される理由:

• 単なる 2025-07-17T09 だけでは1つのパーティションに全てのリクエストが集中してしまう。
• #user_id をつけることで、同一時間帯でもアクセスが複数のキーに分散され、ホットパーティションを防ぐことができる。

terraform でテーブル定義するとこのような形式になる

resource "aws_dynamodb_table" "reservation_table" {
  name           = "Reservation"
  billing_mode   = "PAY_PER_REQUEST"
  hash_key       = "created_at"
  range_key      = "user_id"

  attribute {
    name = "created_at"
    type = "S"
  }

  attribute {
    name = "user_id"
    type = "N"
  }
}

データ形式

{
  "created_at": { "S": "2025-07-17T09" },
  "user_id": { "N": "100001" },
  "reservation_id": { "S": "R001" },
  "status": { "S": "booked" }
}

共通点

LSIの特徴

GSIの特徴

相違点

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html

インデックスの種別

dynamodb には3種類のインデックスが存在。

LSI と GSI 構造上の違いについて

LSI の場合

• 用途としては、同一PK内のソート順を変えたいときに用いられる。
  → 例: あるプレイヤーのキャラクターを、強化した日時で並び替えたい時などに最適

• テーブルと物理的に同じパーティションで管理されるため、GSIと比較して処理時間やトランザクション面で利点。

• 一方で、インデックスの設定がテーブル作成時しか定義できなかったり、1テーブルにつき最大5つまでしか設定できないなどの制約があるため、使いどころは中々難しい。

GSI の場合

• 用途としては別テーブルのように管理される自由度の高いインデックス として用いられる。
  → 例：キャラクター一覧を全プレイヤー横断で取得したいときなどに最適

• テーブル作成後でも、パーティションキー、ソートキーともに自由に追加できるためアクセスパターンに応じて最適な選択が可能になるのが利点。

• 一方で、データ自体が保存されているパーティションとは別のパーティションにデータが保存されることになるため、結果整合性（Eventually Consisten）を許容できないプロダクトの場合は取り扱いが難しい。ほか、書き込み時にGSIに対しての更新処理も行われるため、コスト面においてもLSIと比較して高くつくのが難点。

LSI のメリット・デメリット

GSI のメリット・デメリット

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.Writes

DynamoDB automatically synchronizes each global secondary index with its base table. When an application writes or deletes items in a table, any global secondary indexes on that table are updated asynchronously, using an eventually consistent model. Applications never write directly to an index. However, it is important that you understand the implications of how DynamoDB maintains these indexes.

→アプリケーションがテーブルに書き込みをした際、そのテーブルは結果整合性モデルを使用して非同期的に GSI にも反映する。※アプリが直接 GSI にデータを書き込むことはない。

https://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/GSI.html#GSI.ThroughputConsiderations

Write capacity units
When an item in a table is added, updated, or deleted, and a global secondary index is affected by this, the global secondary index consumes provisioned write capacity units for the operation. The total provisioned throughput cost for a write consists of the sum of write capacity units consumed by writing to the base table and those consumed by updating the global secondary indexes. If a write to a table does not require a global secondary index update, no write capacity is consumed from the index.

→テーブルに何らか書き込み操作が GSI にも影響がある場合、テーブルだけでなく、GSI でも書き込みコスト（WCU）を消費する。つまり、書き込みに要するコストは テーブルとそのテーブルを更新した際に影響を受けるGSIのそれぞれのWCUの合計値となる。※テーブルを更新するもGSIに影響がない場合はテーブル更新時のみのWCUが消費コストとなる。

インデックス選定早見表

• dynamodb では「インデックス ≒ クエリのための設計」
• アクセスパターンを洗い出し、インデックスが不要な形にまず設計するのが理想。
• 必要に応じて GSI（横断検索）、LSI（時系列） を導入を検討する。

セカンダリインデックスは、ベーステーブルにある全ての属性を自動的に保持するわけではない。
検索を高速化しつつ、ストレージ使用量を最小限に抑えるために、必要な属性のみをindexに設定する必要がある。

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html#LSI.Projections

When you create a secondary index, you need to specify the attributes that will be projected into the index. DynamoDB provides three different options for this:

KEYS_ONLY – Each item in the index consists only of the table partition key and sort key values, plus the index key values. The KEYS_ONLY option results in the smallest possible secondary index.

INCLUDE – In addition to the attributes described in KEYS_ONLY, the secondary index will include other non-key attributes that you specify.

ALL – The secondary index includes all of the attributes from the source table. Because all of the table data is duplicated in the index, an ALL projection results in the largest possible secondary index.

射影に選択できる種別

ユースケース別に考えた際に選択する射影

選択した射影の種類に応じて、ストレージや課金にどのような作用があるのか

1点注意しておくべき点として、GSIの場合、セカンダリインデックスはベーステーブルとは異なる領域に保持する構造であるため、射影種別を ALL にした場合 GSI の読み書き容量・ストレージも個別に課金対象 となる点を認識しておく必要がある。
※LSIの場合はベーステーブルと同じ領域に保持されるため別課金にはならない模様

When you choose the attributes to project into a global secondary index, you must consider the tradeoff between provisioned throughput costs and storage costs:

If you need to access most of the non-key attributes on a frequent basis, you can project these attributes—or even the entire base table— into a global secondary index. This gives you maximum flexibility. However, your storage cost would increase, or even double.

ALL の処理フロー

INCLUDE の処理フロー

KEYS_ONLY の処理フロー

投影種別の判断軸

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transactions.html

Amazon DynamoDB transactions simplify the developer experience of making coordinated, all-or-nothing changes to multiple items both within and across tables. Transactions provide atomicity, consistency, isolation, and durability (ACID) in DynamoDB, helping you to maintain data correctness in your applications.

You can use the DynamoDB transactional read and write APIs to manage complex business workflows that require adding, updating, or deleting multiple items as a single, all-or-nothing operation. For example, a video game developer can ensure that players’ profiles are updated correctly when they exchange items in a game or make in-game purchases.

• 複数のアイテムに跨る変更はトランザクション用の読み書きAPIを使用することで all-or-nothing（原子性を保証しながら一括で変更、失敗した場合は変更しない） のオペレーションが可能。

With the transaction write API, you can group multiple Put, Update, Delete, and ConditionCheck actions. You can then submit the actions as a single TransactWriteItems operation that either succeeds or fails as a unit. The same is true for multiple Get actions, which you can group and submit as a single TransactGetItems operation.

• TransactWriteItems: Put、Update、Delete、ConditionCheck の複数アクションを一つにまとめて、全体として成功または失敗させることが可能。
• TransactGetItems: 複数の Get 操作をまとめて実行することが可能。

There is no additional cost to enable transactions for your DynamoDB tables. You pay only for the reads or writes that are part of your transaction. DynamoDB performs two underlying reads or writes of every item in the transaction: one to prepare the transaction and one to commit the transaction. These two underlying read/write operations are visible in your Amazon CloudWatch metrics.

• トランザクションの利用による追加コストはなく、通常の読み書きした分が課金対象となる。
• ただし、少々ややこしいのがトランザクション実行時には各アイテムに対して、トランザクションの準備フェーズとコミットフェーズの2段階の処理が行われるため、通常の単一アイテムの読み書きの2倍のリソースを消費することになる。
  • 参考1: Amazon DynamoDB の料金の概要
  • 参考2: DynamoDBのトランザクションについてFAQ形式で答えてみる #reinvent

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html

TransactWriteItems API について

TransactWriteItems is a synchronous and idempotent write operation that groups up to 100 write actions in a single all-or-nothing operation. These actions can target up to 100 distinct items in one or more DynamoDB tables within the same AWS account and in the same Region. The aggregate size of the items in the transaction cannot exceed 4 MB. The actions are completed atomically so that either all of them succeed or none of them succeeds.

• 同期的、且つ冪等性を担保する書き込み処理のこと。
• 最大で100件の書き込み処理（Put/Update/Delete/ConditionCheck）を1つのトランザクションにまとめて全て成功するか全て失敗するかの原子操作を実行する。※ConditionCheck: アイテムの存在確認/属性条件の検証等
• トランザクション内の対象アイテムは1つ以上のテーブルに跨っていても良い（ただし、同じAWSアカウント且つ、同一リージョン内に限定される）
• 合計データサイズは4MBまで。

注意点

A TransactWriteItems operation differs from a BatchWriteItem operation in that all the actions it contains must be completed successfully, or no changes are made at all. With a BatchWriteItem operation, it is possible that only some of the actions in the batch succeed while the others do not.

Transactions cannot be performed using indexes.

You can't target the same item with multiple operations within the same transaction. For example, you can't perform a ConditionCheck and also an Update action on the same item in the same transaction.

• BatchWriteItem API は一部成功を容認するためこのオペレーションとは異なることを認識しておく必要がある。
• セカンダリインデックス（LSIとGSI）に対してはトランザクション操作を行うことはできない。※セカンダリインデックスはベーステーブルの属性を自動的に反映する構造になっているので、ユーザ側で明示的に変更することはできないのかと
• 同一トランザクション内で同じアイテムに複数の操作を行うことはできない。※例えば delete してから Update する操作はできないということ

トランザクション完了後の処理について

When a transaction completes in DynamoDB, its changes start propagating to global secondary indexes (GSIs), streams, and backups. This propagation occurs gradually: stream records from the same transaction might appear at different times and could be interleaved with records from other transactions. Stream consumers shouldn't assume transaction atomicity or ordering guarantees.

• トランザクション処理が完了した後、変更は段階的に GSI や DynamoDB Stream 等に伝搬される仕組みになっている。

• Stream のレコードは順不同となるため、トランザクションの原始性や順序性は保証されないことに注意する必要がある。※Stream のコンシューマーの設計はその前提で行う必要がある。

• イメージとしては以下

TransactWriteItems
- Put item A
- Update item B
- Delete item C

この時、DynamoDB Stream 上では、

• item B の更新イベントが先に届く。
• item A の作成イベントがその次に届く。
• item C の削除イベントがその次に届く。

といった順番でイベントが流れてくるので、コンシューマ側ではイベントが流れてきたら際にはまず状態チェックのような機構を設ける必要があるということ。

You can optionally include a client token when you make a TransactWriteItems call to ensure that the request is idempotent. Making your transactions idempotent helps prevent application errors if the same operation is submitted multiple times due to a connection time-out or other connectivity issue.

• TransactWriteItems は、クライアントトークンを任意で指定することで、リクエストの冪等性を保証することが可能。
• クライアントトークンは dynamodb の api を実行する際に、リクエストに含めることができる。
• ユーザ側で任意の値を生成して実行することが可能。※Go製のプログラム例を後述

Important points about idempotency
A client token is valid for 10 minutes after the request that uses it finishes. After 10 minutes, any request that uses the same client token is treated as a new request. You should not reuse the same client token for the same request after 10 minutes.

If you repeat a request with the same client token within the 10-minute idempotency window but change some other request parameter, DynamoDB returns an IdempotentParameterMismatch exception.

• クライアントトークンの有効期限は10分。
• 最初のリクエストが完了してから10分以内であれば、同じトークンを使った再送リクエストは変更を加えず成功として返される。
• 10分を過ぎると、そのリクエストは新しいリクエストとして扱われる。※つまり更新処理が行われることになる
• 10分以内に、同じクライアントトークンで再リクエストしたとしても、リクエストのパラーメータが一部変わっていたりすると IdempotentParameterMismatch という例外を返す模様。※例えば post リクエストの一部のパラメータ変えてたりした場合がこれにあたる

dynamodb のトランザクション処理でクライアントトークンを含めた状態でリクエストする例

// dynamodb のクライアント生成
func createDynamoDBClient(ctx context.Context) (*dynamodb.Client, error) {
	cfg, err := config.LoadDefaultConfig(ctx)
	if err != nil {
		return nil, err
	}
	return dynamodb.NewFromConfig(cfg), nil
}

// 冪等性のためのクライアントトークンを生成 ※これのこと
func generateClientToken() string {
	return uuid.New().String()
}

// トランザクションに含める操作（例: ユーザーのステータス更新）を構築
func buildTransactItems(tableName, userID, newStatus string) []types.TransactWriteItem {
	return []types.TransactWriteItem{
		{
			Update: &types.Update{
				TableName: aws.String(tableName),
				Key: map[string]types.AttributeValue{
					"user_id": &types.AttributeValueMemberS{Value: userID},
				},
				UpdateExpression: aws.String("SET #status = :newStatus"),
				ExpressionAttributeNames: map[string]string{
					"#status": "status",
				},
				ExpressionAttributeValues: map[string]types.AttributeValue{
					":newStatus": &types.AttributeValueMemberS{Value: newStatus},
				},
			},
		},
	}
}

// トランザクションを実行
func executeTransaction(ctx context.Context, client *dynamodb.Client, items []types.TransactWriteItem, token string) error {
	input := &dynamodb.TransactWriteItemsInput{
		TransactItems:       items,
		ClientRequestToken:  aws.String(token), // 実際に dynamodb の api 実行する際に、事前に生成しておいたクライアントトークンを含めた状態で実行する
		ReturnConsumedCapacity: types.ReturnConsumedCapacityTotal,
	}

	output, err := client.TransactWriteItems(ctx, input)
	if err != nil {
		return err
	}

	fmt.Printf("Consumed capacity: %+v\n", output.ConsumedCapacity)
	return nil
}

他トランザクションと競合が発生した場合

When a TransactWriteItems request conflicts with an ongoing TransactWriteItems operation on one or more items in the TransactWriteItems request. In this case, the request fails with a TransactionCanceledException.

• 同じアイテムに対して同時に別のトランザクションが実行されていると、競合が起きて TransactionCanceledException で失敗する。
• 冪等性トークンの使用や、リトライ処理（指数バックオフなど）などの考慮が必要。

プロビジョニングされたキャパシティが不足している場合

When there is insufficient provisioned capacity for the transaction to be completed.

• 特にプロビジョンモードでのスループット上限値を越えてしまった場合など。
• プロビジョニング設定を増強、またはオンデマンド設定に切り替える等の検討が必要。※オンデマンド設定の場合はユーザ側で RCU/WCU は設定せず、書き込み、読み込みリクエストをdynamodb 側が自動で処理するので

アイテムサイズやインデックスサイズが制限を超えた場合

When an item size becomes too large (larger than 400 KB), or a local secondary index (LSI) becomes too large, or a similar validation error occurs because of changes made by the transaction.

• アイテムが400KB以上、またはLSIのサイズが制限を超えた場合など。
• データ構造の見直しや、既存の項目をバイナリで圧縮する等の代替策の検討が必要。

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-isolation

Serializable（直列化可能）

Serializable isolation ensures that the results of multiple concurrent operations are the same as if no operation begins until the previous one has finished.

• もっとも強い分離レベルであり、すべての操作が1つずつ順番に実行されたように見える状態。
• つまり、同時に複数の操作が走っていても、結果はまるで1つずつ順番に処理されたかのように整合性を保つ仕組みのこと。

以下のようなイメージ

• 状況:

  • userA, userB が同一商品の在庫を同タイミングで以下のように変更しようとする。
    • userA:「在庫を5減らす」
    • userB: 「在庫を10減らす」

• 非Serializable（弱い整合性）の場合:

  • どちらの操作が先に実行された（処理された）かにより、不安定な結果になってしまう。
  • よくある在庫の整合性が合わなくなってしまう問題。

• Serializable（直列化可能）の場合:

  • たとえ同時に実行していたとしても、内部的には「どちらかを先に、どちらかを後に」実行したように扱うので、不整合の事態を回避することができるようになる。

非Serializable の例（整合性が崩れる可能性）

Serializable の例（整合性が保証される）

Read-Committed（コミット済み読み取り）

Read-committed isolation ensures that read operations always return committed values for an item - the read will never present a view to the item representing a state from a transactional write which did not ultimately succeed. Read-committed isolation does not prevent modifications of the item immediately after the read operation.

• 「読み取り時点での正しい状態を返す」といった保証はあるが、「読み取り直後もその状態が変わらないことまでは保証しない」ということ。

以下のようなイメージ

• userA は「商品Aの在庫数」を参照した。
• この時点で読み取った在庫数は、その瞬間にコミットされている最新の値（コミットされたのは1秒前かもしれないし、昨日かもしれないし、1年前かもしれない）
• ただし、その読み取り操作を行った直後に、別のユーザ、またはバッチ処理が商品Aの在庫数を変更することはあるので、userA が参照した情報は古い情報になるかもしれない、ということ。

トランザクションと単一操作間、バッチ操作間の分離レベル

単一操作間では Serializable な分離レベル が保証される。

ただし、以下のような「バッチ系の操作」全体とは Serializable ではない。

分離レベルの特性比較

• dynamodb のトランザクション操作（TransactWriteItems, TransactGetItems）は基本的には、Serializable なレベルで処理を行う。※つまり他の処理と順序が入れ替わっても結果が変わらないということ
• パフォーマンス重視で、整合性はそこまで重要視されてない場合は Query や BatchGetItem でも良いが、整合性が重要な機能を扱う場合は基本的には TransactWriteItems, TransactGetItems を選択しておくのが良い。

https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html#transaction-best-practices

Avoid using transactions for ingesting data in bulk. For bulk writes, it is better to use BatchWriteItem.

大量のデータを一括で書き込む場合は、極力トランザクション操作は行わず、BatchWriteItem を使用することが推奨されている。

https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html
https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html
https://notes.paulswail.com/public/DynamoDB+BatchWriteItem+vs+TransactWriteItems

dynamodb のトランザクションはオーバーヘッドが大きく、bulk insert には不向きな模様。

• 内部的に各アイテムに対して、トランザクションの準備フェーズとコミットフェーズの2段階の処理が行われるため処理が重くなりがち。※これに加えて RCU/WCU の消費量が2倍になるのも痛い。
• 整合性確保するために、直列性を強制することも理由に挙がるが、そもそもスケーラビリティを視野に入れた使い方をすることが多いはずで、並列実行の恩恵を受けにくくするのはややアンチパターンに近い。※RDBMSのほうが向いている