DynamoDBの設計とキー — あとから条件を足せない

DynamoDBの設計とキー。索引付きのデータカードと鍵、検索を表す虫眼鏡。

DynamoDBは、あとから検索条件を足せません。キー設計で何が決まってしまうのかを、先に確かめます。

前回: RDSとElastiCacheの仕組み — フェイルオーバーで接続が切れる

これは【深掘り】の記事です。本線の順路ではありません。 本線の 1つの表に全部入れると壊れる — テーブル設計と正規化 で覚えた考え方が、 ここでは全部ひっくり返ります。 その理由を掘るのがこの回です。飛ばしても本線は進めます。

このシリーズは、読者にアカウントを作らせません。 触るのは LocalStack と、aws CLI の --endpoint-url だけです。 課金が発生する操作は一切しません。 料金は具体的な金額を書きません(変わるため)。 何に対して課金されるかという構造だけを書き、数字は公式の料金ページを見てください。 コマンドは VM の中(Ubuntu Server)で打ちます。 最後に全部消します。 なお LocalStack は2026年3月23日から1つのイメージに統合され、それ以降の版は起動に auth token(LocalStack のアカウントで取得。無料プランあり)が必要になりました。 この記事では、更新が止まった旧系統の localstack/localstack:3 を固定して使い、アカウントを作らずに進めます。旧イメージの固定は練習用の短期的な手段です(更新が来ず、修正済みの脆弱性が残りうるため)。新しい版を使う場合は、取得した token を LOCALSTACK_AUTH_TOKEN 環境変数に設定します。

✅ 今回は、当たりの回です。 DynamoDB は LocalStack でほぼ完全に動きます。 テーブルを作り、1万件入れ、クエリを投げ、実行時間と消費キャパシティを実測できます。 ただし、再現されないものもあります。 それは出てくるたびに、その場で正直に書きます。


対象レベル: 中級〜上級 / 区分: 発展

目次

私が最初にやったこと(と、そこで止まったこと)

私は MySQL で注文テーブルを作れます。

CREATE TABLE orders (
  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id   BIGINT NOT NULL,
  ordered_at DATETIME NOT NULL,
  amount    INT NOT NULL,
  status    VARCHAR(20) NOT NULL
);

これを書いた時点で、私はまだ何も問いを決めていません。 それでいいのです。

  • 「ユーザー1番の注文を全部出したい」→ WHERE user_id = 1
  • 「今月の合計を出したい」→ WHERE ordered_at >= '2026-10-01'
  • 「キャンセルだけ見たい」→ WHERE status = 'canceled'

表を先に作って、問いはあとから、好きなだけ足せます。 遅ければ索引を足せばいい。 これが私の知っている「データベース設計」でした。


そのつもりで DynamoDB のテーブルを作ろうとして、私は手が止まりました。

create-table のリファレンスを開いても、列を定義する場所がありません。 AttributeDefinitions という項目はあるのに、そこに amount や status を書くと怒られます。

An error occurred (ValidationException) when calling the CreateTable operation:
One or more parameter values were invalid: Some AttributeDefinitions are not used.
AttributeDefinitions: [amount, status, userId], keys: [userId]

「使っていない属性定義がある」

意味が分かりませんでした。 使うに決まっている、と思いました。 amount も status も、これから入れるデータの列です。

違いました。 DynamoDB の AttributeDefinitions は「データの列の一覧」ではありません。 「キーとして使う属性だけ」を書く場所です。

そして、ここで本当のことに気づきました。

DynamoDB は、キー以外の列を、テーブル定義に一切持たない。 つまり、テーブルを作る時点で決まっているのは「どうやって引くか」だけ。

引き方を先に全部決めないと、テーブルが作れないのです。


もう1つ、これを痛感した瞬間があります。

とりあえずテーブルができたので、データを入れて、こう打ちました。

bash
$ aws dynamodb query --table-name Orders \
    --key-condition-expression 'status = :s' ...
An error occurred (ValidationException) when calling the Query operation:
Query condition missed key schema element: userId

「キー以外では引けません」 と言われています。

MySQL なら、索引が無くても遅いだけで結果は返ってきます。 DynamoDB は、遅いのではなく、拒否されます。

そして「じゃあ status にも索引を張ればいい」と思って調べたら、それが GSI で、 GSI を足すと書き込みコストが増えると書いてありました。

私は「速いから DynamoDB」だと思っていました。 速いのは、遅くなる書き方が最初から禁止されているからでした。

この構造を、この記事で全部、手を動かして確かめます。


この記事でわかること

  • 設計の順番が、リレーショナルと真逆。 リレーショナルはデータの形を先に決めて問いはあとから。DynamoDB は問いを先に全部決めないとテーブルが作れない
  • 「あとから条件を足す」ができないのが、最大の代償。 速さの対価はここで払っている。この1点で選ぶか選ばないかが決まる
  • scan を書いた時点で、設計はほぼ間違っている。 件数に比例して遅くなり、費用も比例する。それを自分の手で測って確かめる。ただし例外もあるので、そこも正直に書く
  • DynamoDB で使える「範囲検索」は、ソートキーの1本だけ。 begins_with と between が全て。それ以外の条件は、絞り込みではなく「取ってから捨てる」
  • パーティションキーの選び方を間違えると、台数を増やしても詰まる。 日付をキーにすると、今日の分に全部集中する
  • GSI は結果整合で、書き込みコストがインデックスの数だけ増える。 「索引を足す」感覚で足すものではない
  • 定石は「1つのテーブルに複数の種類のデータを混ぜる」。 そして読みにくい。それが代償で、常に正しいわけでもない
  • 正直な結論として、DynamoDB が向く条件は狭い。 「とりあえず DynamoDB」は、たいてい後悔する

この記事でやること

  1. LocalStack を DynamoDB だけで立てて、aws CLI から本物と同じ API を叩く
  2. パーティションキーだけの単純なテーブルを作り、put-item / get-item / delete-item を打つ
  3. 1万件のデータを入れて、query と scan の実行時間と消費キャパシティを実測して比べる
  4. 複合キー(パーティションキー + ソートキー)で begins_with と between を打ち、範囲検索の正体を見る
  5. わざと偏ったキーでデータを入れて、キーの分布を数え、ホットパーティションを目で見る
  6. GSI を実際に作って、別の切り口で引けるようになるところと、その代償を確かめる
  7. 1つのテーブルに利用者と注文を混ぜて入れ、1回のクエリで両方取れるところまでやる
  8. Streams と TTL を有効にして、全部消す

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
アイテム1件のデータ。リレーショナルの「行」にあたるもの。1件ごとに持つ属性がバラバラでよい
属性アイテムが持つ値。リレーショナルの「列」にあたる。テーブル定義には書かない
パーティションキーデータがどの箱に入るかを決める値。 これが必ず要る。省略できない
ソートキー同じ箱の中での並び順を決める値。これがあるときだけ範囲検索ができる
プライマリキーパーティションキー単独、またはパーティションキー + ソートキーの組。この組で一意
queryキーを指定して引く操作。パーティションキーの完全一致が必須
scanテーブルを最初から最後まで全部読む操作。件数に比例して遅く、高い
キャパシティユニット読み書きの量の単位。DynamoDB の課金と速度制限は、これで数える
ホットパーティション1つの箱にアクセスが集中して詰まる状態。台数では解決しない
GSIあとから足せる別の切り口のインデックス。結果整合。書き込みコストが増える
LSIテーブル作成時にしか作れないインデックス。パーティションキーは変えられない
単一テーブル設計1つのテーブルに複数の種類のデータを混ぜる、DynamoDB の定石
TTL属性に入れた時刻を過ぎたら自動で消えるしくみ

① 設計の順番が、逆になる

先に山場をやります。 ここが腹に落ちれば、残りは全部その帰結です。

2つのデータベースで、決める順番を並べる

リレーショナル(MySQL など)DynamoDB
最初に決めるものデータの形(どんな列があるか)問いの一覧(どうやって引くか)
テーブル定義に書くもの全部の列と型キーに使う属性だけ
問いを足すとき✅ WHERE を書き換えるだけ。定義は触らないインデックスを足すか、キー設計をやり直す
索引が無い条件で引くと遅いが、結果は返る拒否される、または全件読みになる
列を足すときALTER TABLE(テーブル全体が止まりうる)✅ 何もしなくてよい。入れた瞬間から入る
結合(JOIN)✅ できる無い。アプリで2回引くか、最初から一緒に入れておく
集計(SUM/COUNT)✅ SQLでできる無い。全部読んで自分で足すか、書くたびに数を更新する
速さの保証データ量が増えると遅くなりうる✅ キーで引く限り、件数が増えても速さが変わらない
設計をやり直すコスト索引を足す。多くは即日データを全部入れ直すことがある

この表の1行だけ覚えるなら、ここです

リレーショナルは「あとから問いを足せる」。DynamoDB は「足せない」。 DynamoDB の速さは、この自由を捨てた対価です。

「速いから使う」のではありません。 「引き方が最初から1通りに決まっている仕事だから使う」のです。

なぜ「足せない」のか — 中で何をしているか

DynamoDB は、パーティションキーの値をハッシュ関数に通して、どのサーバー(箱)に置くかを決めます。 ハッシュ表そのものです。

PK "USER#0042" ──[ハッシュ]──> 箱3 ──> その中でソートキー順に並ぶ
PK "USER#0043" ──[ハッシュ]──> 箱1
PK "USER#0044" ──[ハッシュ]──> 箱3
  • ✅ PK が分かっていれば、1回の計算でどの箱か分かる。 箱がいくつあっても、データが何億件あっても、同じ速さ
  • PK が分からない条件(status = 'paid' など)では、どの箱か分からない。 全部の箱を開けるしかない。それが scan

これは実装の都合ではなく、速さの正体そのものです。 「あとで条件を足せるようにしておく」ことが、原理的にできません。


② 準備 — LocalStack を DynamoDB だけで立てる

作業場所を作ります。 最後にフォルダごと消します。

bash
$ mkdir -p ~/awslab/ddb
$ cd ~/awslab/ddb
$ nano docker-compose.yml
services:
  localstack:
    image: localstack/localstack:3
    ports:
      - "4566:4566"
    environment:
      - SERVICES=dynamodb,dynamodbstreams
      - DEBUG=0
    volumes:
      - "./volume:/var/lib/localstack"

SERVICES を絞っています。 前回の RDS などと混ぜると起動が遅くなるので、分けます。

bash
$ docker compose up -d
$ docker compose ps
NAME         IMAGE                     STATUS                  PORTS
localstack   localstack/localstack:3   Up 14 seconds (healthy)  0.0.0.0:4566->4566/tcp

(healthy) になるまで待ちます。 starting のまま打つと繋がりません。

CLI の設定をします。

bash
$ aws configure set aws_access_key_id test
$ aws configure set aws_secret_access_key test
$ aws configure set region ap-northeast-1
$ alias awsl='aws --endpoint-url=http://localhost:4566'

本物のアクセスキーを絶対にここに入れないでください。 LocalStack は認証情報を検査しません。test で通ります。 本物の鍵を打つと、間違えて本物に向けたときに課金が発生します。

あとで使う道具も入れておきます。

bash
$ sudo apt update
$ sudo apt install -y jq python3

繋がったか確認します。

bash
$ awsl dynamodb list-tables
{
    "TableNames": []
}

✅ 空の配列が返れば成功です。

[スクリーンショット: 01_localstack-dynamodb-healthy.png] docker compose ps が (healthy) になっていて、list-tables が空配列を返しているところ。


③ パーティションキーだけのテーブルを作って、1件ずつ触る

一番単純な形から始めます。 キーは1本だけです。

作る

bash
$ awsl dynamodb create-table \
    --table-name Users \
    --attribute-definitions AttributeName=userId,AttributeType=S \
    --key-schema AttributeName=userId,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

この4行の意味を、1つずつ読みます。

指定意味
--attribute-definitionsキーに使う属性の宣言だけ。 AttributeType=S は文字列(N は数値、B はバイナリ)
--key-schemaどれをキーにするか。 KeyType=HASH がパーティションキー(RANGE がソートキー)
--billing-mode PAY_PER_REQUESTオンデマンド。 事前に速度の上限を決めなくてよい(詳しくは⑧)

HASH という名前が分かりにくいです。 「ハッシュキー」は昔の呼び名で、 いまのドキュメントでは「パーティションキー」と書かれます。CLI のパラメータ名だけ昔のままです。

「使っていない属性定義がある」を、わざと再現する

冒頭で私が詰まったエラーを、ここで出してみます。

bash
$ awsl dynamodb create-table \
    --table-name Broken \
    --attribute-definitions AttributeName=userId,AttributeType=S AttributeName=amount,AttributeType=N \
    --key-schema AttributeName=userId,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST
An error occurred (ValidationException) when calling the CreateTable operation:
One or more parameter values were invalid: Number of attributes in KeySchema does not
exactly match number of attributes defined in AttributeDefinitions

amount を書いた瞬間に拒否されます。

AttributeDefinitions は列の定義ではありません。 キーに使うものだけを書く場所です。キー以外の属性は、テーブル定義に一切登場しません。

入れる

bash
$ awsl dynamodb put-item --table-name Users \
    --item '{"userId":{"S":"u001"},"name":{"S":"sato"},"age":{"N":"32"},"plan":{"S":"free"}}'

何も出力されなければ成功です。

{"S":"..."} {"N":"..."} という書き方が独特です。 これは DynamoDB の型付きJSON で、 S は文字列、N は数値、BOOL は真偽値、L はリスト、M は入れ子のオブジェクトを表します。

数値も、クオートで囲んで文字列として書きます。 {"N":"32"} です。{"N":32} はエラーになります。 JSON の数値の精度でズレるのを避けるため、送るときは文字列で送る仕様になっています。

もう1件、わざと違う形で入れます。

bash
$ awsl dynamodb put-item --table-name Users \
    --item '{"userId":{"S":"u002"},"name":{"S":"suzuki"},"tags":{"L":[{"S":"vip"},{"S":"beta"}]}}'

age も plan も入っていません。かわりに tags があります。 それでもエラーになりません。

同じテーブルの中で、アイテムごとに属性がバラバラでよい。 これがリレーショナルとの2つ目の大きな違いです。 ということは、「必ずある」と保証してくれる人がいません。 アプリが保証するしかない (スキーマは消えずにアプリへ移る — NoSQLとMongoDB と同じ話です)

取る

bash
$ awsl dynamodb get-item --table-name Users --key '{"userId":{"S":"u001"}}'
{
    "Item": {
        "userId": {"S": "u001"},
        "plan": {"S": "free"},
        "name": {"S": "sato"},
        "age": {"N": "32"}
    }
}

get-item は、キーが完全に分かっているときしか使えません。

試しに、名前で引こうとしてみます。

bash
$ awsl dynamodb get-item --table-name Users --key '{"name":{"S":"sato"}}'
An error occurred (ValidationException) when calling the GetItem operation:
The provided key element does not match the schema

get-item は「検索」ではありません。 「この住所のものを持ってこい」という命令です。 住所が分からないときには、そもそも使えません。

無いキーを取ると、エラーにならない

bash
$ awsl dynamodb get-item --table-name Users --key '{"userId":{"S":"u999"}}'
{}

空の JSON が返ります。エラーではありません。 アプリ側で Item が無いことを見て判断します。 ここを見落とすと、undefined を触って落ちます。

消す

bash
$ awsl dynamodb delete-item --table-name Users --key '{"userId":{"S":"u002"}}'
$ awsl dynamodb scan --table-name Users --select COUNT
{
    "Count": 1,
    "ScannedCount": 1,
    "ConsumedCapacity": null
}

✅ 1件になりました。

無いキーを消しても、エラーになりません。 これも仕様です。 「消えたかどうか」を知りたいなら、--return-values ALL_OLD を付けます。

bash
$ awsl dynamodb delete-item --table-name Users \
    --key '{"userId":{"S":"u999"}}' --return-values ALL_OLD
{}

Attributes が返ってこない = そもそも無かった、と判断できます。


④ Query と Scan の差を、1万件で実測する

ここが、この記事で一番手を動かすところです。

実測用のテーブルを作る(複合キー)

PK と SK の2本立てにします。 意味は⑤で詳しくやるので、ここでは「2本ある」とだけ思ってください。

bash
$ awsl dynamodb create-table \
    --table-name Orders \
    --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
    --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
    --billing-mode PAY_PER_REQUEST
bash
$ awsl dynamodb describe-table --table-name Orders --query 'Table.TableStatus'
"ACTIVE"

1万件のデータを作る

batch-write-item は1回に25件までです。 なので 400ファイルに分けて生成します。

bash
$ cd ~/awslab/ddb
$ python3 - <<'PY'
  import json, os, random
  random.seed(42)
  os.makedirs('batches', exist_ok=True)
  items = []
  for u in range(1, 201):
      pk = "USER#%04d" % u
      for i in range(50):
          m = random.randint(1, 12)
          d = random.randint(1, 28)
          items.append({"PutRequest": {"Item": {
              "PK":     {"S": pk},
              "SK":     {"S": "ORDER#2026-%02d-%02d#%04d" % (m, d, i)},
              "amount": {"N": str(random.randint(500, 30000))},
              "status": {"S": random.choice(["paid", "shipped", "canceled"])},
              "note":   {"S": "x" * 100},
          }}})
  items.sort(key=lambda x: (x["PutRequest"]["Item"]["PK"]["S"],
                            x["PutRequest"]["Item"]["SK"]["S"]))
  for n in range(0, len(items), 25):
      with open("batches/b%04d.json" % (n // 25), "w") as f:
          json.dump({"Orders": items[n:n+25]}, f)
  print(len(items), "items,", (len(items) + 24) // 25, "files")
  PY
10000 items, 400 files

投入します。 400回 CLI を起動するので、3〜6分かかります。

bash
$ time (for f in batches/*.json; do
$   awsl dynamodb batch-write-item --request-items file://$f > /dev/null
$ done)
real    4m52.311s
user    3m40.902s
sys     0m28.114s

この5分は DynamoDB が遅いのではありません。 aws コマンドの起動が400回あるだけです。 本物のアプリなら SDK を使うので、この時間はかかりません。

入ったか数えます。

bash
$ awsl dynamodb scan --table-name Orders --select COUNT --query 'Count'
10000

✅ 1万件入りました。

測る(1)— query:キーで引く

ユーザー1人分(50件)を引きます。

bash
$ time awsl dynamodb query --table-name Orders \
    --key-condition-expression 'PK = :pk' \
    --expression-attribute-values '{":pk":{"S":"USER#0042"}}' \
    --select COUNT \
    --return-consumed-capacity TOTAL
{
    "Count": 50,
    "ScannedCount": 50,
    "ConsumedCapacity": {
        "TableName": "Orders",
        "CapacityUnits": 0.5
    }
}
real    0m1.284s

注目するのは ScannedCount です。 50件しか読んでいません。

測る(2)— scan:全部読む

同じ50件を、scan に条件を付けて取ってみます。

bash
$ time awsl dynamodb scan --table-name Orders \
    --filter-expression 'PK = :pk' \
    --expression-attribute-values '{":pk":{"S":"USER#0042"}}' \
    --select COUNT \
    --return-consumed-capacity TOTAL
{
    "Count": 50,
    "ScannedCount": 10000,
    "ConsumedCapacity": {
        "TableName": "Orders",
        "CapacityUnits": 168.5
    }
}
real    0m9.657s

[スクリーンショット: 02_query-vs-scan.png] query と scan の ScannedCount と CapacityUnits が並んでいるところ。

この2つを並べる

queryscan
返ってきた件数5050
読んだ件数(ScannedCount)5010000
消費キャパシティ0.5168.5
かかった時間約1.3秒約9.7秒

同じ結果を得るのに、200倍のデータを読み、300倍以上のコストを払っています。 そして、この差はデータが増えるほど開きます。

「フィルタは絞り込みではない」

私はここを完全に誤解していました。

--filter-expression は、読む量を減らしません。 全部読んでから、返す前に捨てているだけです。

証拠が ScannedCount: 10000 です。 課金も速度制限も、ScannedCount のほうで数えます。

Count と ScannedCount の意味は、こうです。

項目意味
Count返した件数。これは請求に関係しない
ScannedCount読んだ件数。ここが費用と時間
CapacityUnits読んだ「量」。件数ではなくバイト数で決まる

CapacityUnits が件数と一致しないのは、1ユニットが「4KBまで」だからです。 小さいアイテムなら複数件で1ユニット、大きいアイテムなら1件で複数ユニットになります。

件数を倍にすると、どうなるか

2000件だけの小さいテーブルでも同じことをやると、差が縮みます。

テーブルの件数query の ScannedCountscan の ScannedCount
1,000501,000
10,0005010,000
1,000,000501,000,000

query は件数が増えても変わりません。scan は完全に比例します。 開発中のテーブルは小さいので、scan でも一瞬で返ります。 だから、本番で初めて壊れます。 これが一番よくある事故です。

言い切ります: scan を書いた時点で、設計が間違っています

アプリの処理の中に scan があるなら、そのテーブルのキー設計は要件に合っていません。 「とりあえず scan で作って、あとで直そう」は、直せません。 キー設計を変えるということは、データを全部入れ直すということだからです。

ただし、例外は本当にあります

正直に書きます。scan を使ってよい場面が、いくつかあります。

場面なぜ許されるか
1日1回のバッチ集計人が待っていない。 時間がかかってよい。--total-segments で並列にもできる
データの移行・エクスポートどのみち全部読む。 そもそも scan が正しい操作
数百件で頭打ちの管理用テーブル設定値の一覧など、増えないもの。 増えないと確信できるなら可
開発中の中身の確認手で覗くだけ。 アプリに残さない
本番の分析本来は scan ではなく、S3 にエクスポートして分析する

共通しているのは「利用者のリクエストの中で実行されない」ことです。 画面を開いた人が待っている処理の中に scan があったら、それは間違いです。

そして、バッチで scan するときも上限を付けます。

bash
$ awsl dynamodb scan --table-name Orders \
    --select COUNT --max-items 100 --return-consumed-capacity TOTAL

aws CLI は scan を勝手にページングして最後まで読みます。 --max-items を付けないと、確認のつもりが全件読みになります。


⑤ 複合キー — DynamoDB で唯一使える「範囲検索」

ソートキーは、箱の中の並び順

PK が「どの箱か」、SK が「箱の中の何番目か」です。

箱(PK = USER#0042)
  ├── SK = ORDER#2026-01-05#0031
  ├── SK = ORDER#2026-01-19#0007   ← SKの文字列順で必ず並んでいる
  ├── SK = ORDER#2026-02-03#0044
  ├── ...
  └── SK = ORDER#2026-12-24#0012

並んでいるから、範囲で切り出せます。 そしてこれが、DynamoDB で唯一の範囲検索です。

begins_with — 前方一致で切り出す

ユーザー0042の、2026年10月の注文だけを取ります。

bash
$ awsl dynamodb query --table-name Orders \
    --key-condition-expression 'PK = :pk AND begins_with(SK, :sk)' \
    --expression-attribute-values '{":pk":{"S":"USER#0042"},":sk":{"S":"ORDER#2026-10"}}' \
    --select COUNT \
    --return-consumed-capacity TOTAL
{
    "Count": 4,
    "ScannedCount": 4,
    "ConsumedCapacity": {
        "TableName": "Orders",
        "CapacityUnits": 0.5
    }
}

ScannedCount が 4 です。 50件のうち4件だけを読んでいます。

--filter-expression のときは10000件読みました。ここでは4件です。 これが「絞り込み」と「取ってから捨てる」の違いです。

between — 期間で切り出す

bash
$ awsl dynamodb query --table-name Orders \
    --key-condition-expression 'PK = :pk AND SK BETWEEN :from AND :to' \
    --expression-attribute-values '{
      ":pk":{"S":"USER#0042"},
      ":from":{"S":"ORDER#2026-04-01"},
      ":to":{"S":"ORDER#2026-06-30#zzzz"}
    }' \
    --select COUNT --return-consumed-capacity TOTAL
{
    "Count": 13,
    "ScannedCount": 13,
    "ConsumedCapacity": {"TableName": "Orders", "CapacityUnits": 0.5}
}

:to の末尾に #zzzz を付けているのが、この記事で一番細かい罠です。

BETWEEN は文字列の比較です。 ORDER#2026-06-30 で切ると、ORDER#2026-06-30#0012 は 「ORDER#2026-06-30 より後ろ」なので、範囲から漏れます。 6月30日の注文が全部消えます。

これは私が実際にやった間違いです。 「最終日の分だけ入っていない」という形で出ます。

新しい順に取る

bash
$ awsl dynamodb query --table-name Orders \
    --key-condition-expression 'PK = :pk' \
    --expression-attribute-values '{":pk":{"S":"USER#0042"}}' \
    --no-scan-index-forward --max-items 3 \
    --query 'Items[].SK.S'
[
    "ORDER#2026-12-24#0012",
    "ORDER#2026-12-18#0026",
    "ORDER#2026-12-11#0003"
]

--no-scan-index-forward で逆順になります。 ソート処理は入っていません。並んでいるものを後ろから読むだけです。

だから「並べ替え」は、SK に組み込んだ1通りしかできません。 金額順に並べたい、と後から言われても、SK が日付なら不可能です。 これが「あとから条件を足せない」の具体例です。

ソートキーで使える条件は、これだけ

条件書き方使えるか
等しいSK = :v✅
より大きい・小さいSK > :v SK <= :v✅
範囲SK BETWEEN :a AND :b✅
前方一致begins_with(SK, :v)✅
部分一致(後方・中間)contains(SK, :v)キー条件では使えない
否定SK <> :vキー条件では使えない
複数の値のどれかSK IN (...)キー条件では使えない

パーティションキーは = しか使えません。 PK > :v は書けません。 ハッシュで箱を決めているので、「PKがこれより大きいもの」という順序が存在しないからです。

そして重要な帰結です。

DynamoDB には、部分一致検索がありません。 「名前に『佐藤』を含む人」は、原理的に引けません。 必要なら、別の道具(全文検索エンジン)を横に置きます (部分一致は索引が効かない — 全文検索とMeilisearch)


⑥ ホットパーティション — 日付をキーにすると詰まる

何が起きるのか

DynamoDB は、PK のハッシュで箱を決めます。 1つの箱には、速度の上限があります。

テーブル全体の上限に余裕があっても、1つの箱が上限に達したら、そこだけ詰まります。 サーバーを増やしても解決しません。「全部の仕事が同じ箱に入っている」からです。

典型例が、これです。

PK = "2026-10-07"   ← 今日の分が、全部この1個の箱に入る
PK = "2026-10-06"   ← 昨日の箱は、もう誰も触らない
PK = "2026-10-05"   ← 一昨日の箱も、誰も触らない

「今日」が常に1つの箱です。 書き込みも読み込みも、全部そこに集中します。

実際に偏らせて、分布を数える

わざと日付を PK にしたテーブルを作ります。

bash
$ awsl dynamodb create-table \
    --table-name Events \
    --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
    --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
    --billing-mode PAY_PER_REQUEST

2000件入れます。9割を「今日」にします。

bash
$ cd ~/awslab/ddb
$ python3 - <<'PY'
  import json, os, random
  random.seed(7)
  os.makedirs('ev', exist_ok=True)
  items = []
  for i in range(2000):
      if random.random() < 0.9:
          day = "2026-10-07"
      else:
          day = "2026-10-%02d" % random.randint(1, 6)
      items.append({"PutRequest": {"Item": {
          "PK": {"S": day},
          "SK": {"S": "EVENT#%06d" % i},
          "kind": {"S": random.choice(["view", "click", "buy"])},
      }}})
  for n in range(0, len(items), 25):
      with open("ev/e%04d.json" % (n // 25), "w") as f:
          json.dump({"Events": items[n:n+25]}, f)
  print(len(items), "items,", (len(items) + 24) // 25, "files")
  PY
2000 items, 80 files
bash
$ for f in ev/*.json; do
$   awsl dynamodb batch-write-item --request-items file://$f > /dev/null
$ done

キーの分布を数えます。

bash
$ awsl dynamodb scan --table-name Events \
    --projection-expression 'PK' --output json \
    | jq -r '.Items[].PK.S' | sort | uniq -c | sort -rn
   1804 2026-10-07
     39 2026-10-03
     36 2026-10-01
     35 2026-10-05
     31 2026-10-04
     29 2026-10-02
     26 2026-10-06

[スクリーンショット: 03_hot-partition-distribution.png] uniq -c の出力で、1日だけが極端に多くなっているところ。

1804 対 39 です。 箱の1つに9割が入っています。 本物の DynamoDB なら、この箱だけが上限に当たり、ProvisionedThroughputExceededException が出ます。

比較のために、⑤で作った Orders の分布も見ます。

bash
$ awsl dynamodb scan --table-name Orders \
    --projection-expression 'PK' --output json \
    | jq -r '.Items[].PK.S' | sort | uniq -c | sort -rn | head -3
     50 USER#0200
     50 USER#0199
     50 USER#0198

✅ 200個の箱に、きれいに50件ずつです。 これが健全な形です。

LocalStack は、詰まりを再現しません。 偏っていても普通に返ってきます。 だから「分布を数える」という形でしか、ここでは確かめられません。 エミュレータで動いた=本番で動く、ではない典型例です。

対策1 — そもそも偏らないキーを選ぶ

「今日のイベント一覧が欲しい」から日付を PK にしたのが間違いでした。

変える前変えた後
PK = 2026-10-07PK = USER#0042
SK = EVENT#000123SK = EVENT#2026-10-07T10:23:11#000123

利用者ごとに箱が分かれるので、利用者が増えるほど箱が増えます。 「1人分のイベントを日付順に」も、begins_with(SK, "EVENT#2026-10-07") で取れます。

ただし、これで「全員の今日のイベント」は取れなくなりました。 問いを1つ捨てています。 これが DynamoDB の設計です。

対策2 — キーにサフィックスを足して、わざと分散させる

どうしても日付で引きたいときは、箱を人工的に割ります。

bash
$ awsl dynamodb put-item --table-name Events \
    --item '{"PK":{"S":"2026-10-08#03"},"SK":{"S":"EVENT#900001"},"kind":{"S":"buy"}}'

#03 の部分が「何番目の箱か」です。 書くときは 0〜9 からランダムに選びます。

効果代償
書き込み✅ 10個の箱に分散するどの箱に入れたか、書いた側は覚えていない
読み込み—query を10回投げて、自分でつなげる必要がある

これは「シャーディング」と呼ばれる、DynamoDB では定番の手です。 ただし、読むほうが確実に面倒になります。 10個に割ったら、読むときは10回引きます (考え方は レプリカを足しても書き込みは速くならない — システム設計深掘り と同じです)

偏りは、キーだけの問題ではない

もう1つ、私が見落としていた偏りがあります。

箱がたくさんあっても、「特定の1件」に読みが集中したら、同じことが起きます。 例: セール中の1商品。PK は商品ごとに分かれているのに、その1つだけが叩かれる。 これは DAX などのキャッシュか、アプリ側のキャッシュで受けます。 キー設計だけでは解けない偏りが、確かにあります。


⑦ セカンダリインデックス — LSI と GSI

まず表で違いを押さえる

LSI(ローカル)GSI(グローバル)
作れるタイミングテーブル作成時のみ。あとから追加も削除もできない✅ いつでも追加・削除できる
パーティションキー元のテーブルと同じもの固定✅ 自由に選べる
ソートキー✅ 別の属性を選べる✅ 自由。省略もできる
整合性✅ 強い整合性で読める結果整合。元より遅れる
キャパシティテーブルと共有インデックス専用に別で消費する
個数の上限テーブルあたり5個テーブルあたり20個(緩和申請可)
1パーティションの容量制限同じPKの合計に10GBの上限が付く無し
迷ったら—✅ GSI。LSI を選ぶ理由はかなり少ない

LSI の最大の問題は「あとから作れない」ことです。 テーブルを作った瞬間に、LSI の有無が確定します。 必要になったら、テーブルを作り直してデータを移します。

LSI が作れないことを、実際に確かめる

bash
$ awsl dynamodb update-table --table-name Orders \
    --local-secondary-index-updates '[]'
usage: aws [options] <command> <subcommand> [parameters]
Unknown options: --local-secondary-index-updates

オプションそのものが存在しません。 「あとから変える手段が用意されていない」ということです。

参考までに、作成時なら書けます(このテーブルは今回は使いません)。

bash
$ awsl dynamodb create-table --table-name WithLsi \
    --attribute-definitions AttributeName=PK,AttributeType=S \
        AttributeName=SK,AttributeType=S AttributeName=amount,AttributeType=N \
    --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
    --local-secondary-indexes '[{
      "IndexName": "ByAmount",
      "KeySchema": [{"AttributeName":"PK","KeyType":"HASH"},
                    {"AttributeName":"amount","KeyType":"RANGE"}],
      "Projection": {"ProjectionType":"KEYS_ONLY"}
    }]' \
    --billing-mode PAY_PER_REQUEST

KeySchema の HASH が PK のままなのが分かりますか。 ここは変えられません。

GSI を実際に作る

いま Orders は「ユーザーごと」にしか引けません。 「発送済みの注文だけ見たい」を可能にします。

bash
$ awsl dynamodb update-table --table-name Orders \
    --attribute-definitions AttributeName=PK,AttributeType=S \
        AttributeName=SK,AttributeType=S AttributeName=status,AttributeType=S \
    --global-secondary-index-updates '[{
      "Create": {
        "IndexName": "StatusIndex",
        "KeySchema": [{"AttributeName":"status","KeyType":"HASH"},
                      {"AttributeName":"SK","KeyType":"RANGE"}],
        "Projection": {"ProjectionType":"ALL"}
      }
    }]'

--attribute-definitions に、既存の PK と SK も書き直す必要があります。 片方だけ書くと、こう怒られます。

An error occurred (ValidationException) when calling the UpdateTable operation:
One or more parameter values were invalid: Some index key attributes are not defined
in AttributeDefinitions.

できるまで待ちます。

bash
$ awsl dynamodb describe-table --table-name Orders \
    --query 'Table.GlobalSecondaryIndexes[0].[IndexName,IndexStatus,ItemCount]'
[
    "StatusIndex",
    "ACTIVE",
    10000
]

✅ 1万件が、インデックスにも入りました。

新しい切り口で引く

bash
$ time awsl dynamodb query --table-name Orders \
    --index-name StatusIndex \
    --key-condition-expression '#s = :v' \
    --expression-attribute-names '{"#s":"status"}' \
    --expression-attribute-values '{":v":{"S":"shipped"}}' \
    --select COUNT --return-consumed-capacity TOTAL
{
    "Count": 3339,
    "ScannedCount": 3339,
    "ConsumedCapacity": {
        "TableName": "Orders",
        "CapacityUnits": 42.0
    }
}

#s という書き方が出てきました。 status は DynamoDB の予約語なので、そのままでは使えません。

An error occurred (ValidationException) when calling the Query operation:
Invalid KeyConditionExpression: Attribute name is a reserved keyword; reserved keyword: status

status name size count timestamp あたりは全部予約語です。 #別名 に逃がして、--expression-attribute-names で対応付けます。 これは覚えるものではなく、エラーが出たら逃がす、で構いません。

さっきの scan と比べます。

やり方ScannedCountCapacityUnits
scan + フィルタで shipped を取る10000168.5
GSI で query333942.0

✅ 返す3339件しか読んでいません。

GSI の代償その1 — 結果整合

GSI は、元のテーブルより遅れます。 書き込んだ直後に GSI を引くと、まだ入っていないことがあります。

これは「バグ」ではなく仕様です。 (同じ話を 書いた直後に読むと無い — レプリケーションとCAP でやりました)

--consistent-read は、GSI に対しては使えません。

bash
$ awsl dynamodb query --table-name Orders --index-name StatusIndex \
    --key-condition-expression '#s = :v' \
    --expression-attribute-names '{"#s":"status"}' \
    --expression-attribute-values '{":v":{"S":"paid"}}' \
    --consistent-read --select COUNT
An error occurred (ValidationException) when calling the Query operation:
Consistent reads are not supported on global secondary indexes

「強く読む」という選択肢が、そもそも存在しません。

LocalStack は GSI の遅延を再現しません。 書いた瞬間に GSI に入ります。 手元で動いたコードが、本物で「たまに無い」になります。 ここは実測できないので、仕様として覚えるしかありません。

GSI の代償その2 — 書き込みが増える

1回 put-item すると、GSI の数だけ書き込みが発生します。 GSI を3本張ったテーブルは、1回の書き込みで4回書いています。

GSI の数1回の put-item で発生する書き込み
0本1
1本2
3本4
5本6

ProjectionType: ALL にすると、GSI にアイテム全体のコピーが載ります。 保管量も増えます。

ProjectionType何が載るか使いどころ
KEYS_ONLYキーだけ✅ 一番安い。あとで get-item する前提
INCLUDEキー + 指定した属性✅ 一覧に出す項目だけ載せる。実務ではこれが多い
ALL全部のコピー1回で完結するが、費用は最大

「SQL の索引を足す」感覚で GSI を足すと、書き込み費用が静かに倍になります。 索引を足す判断の考え方自体は 索引を張ったのに使われない — SQL深掘り と同じですが、 DynamoDB では「読みが速くなる代わりに、書きが高くなる」がもっと露骨です。

そして、いま作った GSI 自体が悪い例です

status は paid shipped canceled の3種類しかありません。

bash
$ awsl dynamodb scan --table-name Orders \
    --projection-expression '#s' --expression-attribute-names '{"#s":"status"}' \
    --output json | jq -r '.Items[].status.S' | sort | uniq -c
   3352 canceled
   3309 paid
   3339 shipped

GSI のパーティションキーが3種類 = 箱が3個です。 ⑥でやったホットパーティションそのものです。

説明のために作りましたが、本物ではこの設計はしません。 実務なら status#2026-10 のように、日付を混ぜて箱を割ります。 「値の種類が少ない属性を、GSI の PK にしない」が原則です。


⑧ 単一テーブル設計 — 1つのテーブルに全部混ぜる

これが DynamoDB の定石です

リレーショナルなら、こう作ります。

users テーブル  ── id, name, plan
orders テーブル ── id, user_id, ordered_at, amount

そして JOIN で繋ぎます。 DynamoDB に JOIN はありません。

だから、こうします。 1つのテーブルに、利用者も注文も、全部入れる。 PK を同じにしておけば、1回の query で両方まとめて取れる。

作って、混ぜて入れる

bash
$ awsl dynamodb create-table \
    --table-name AppData \
    --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
    --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
    --billing-mode PAY_PER_REQUEST
bash
$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#1"}, "SK":{"S":"PROFILE"},
    "type":{"S":"user"}, "name":{"S":"sato"}, "plan":{"S":"pro"}
  }'

$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#1"}, "SK":{"S":"ADDRESS#home"},
    "type":{"S":"address"}, "city":{"S":"sapporo"}
  }'

$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#1"}, "SK":{"S":"ORDER#2026-10-01#001"},
    "type":{"S":"order"}, "amount":{"N":"12800"}
  }'

$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#1"}, "SK":{"S":"ORDER#2026-10-05#002"},
    "type":{"S":"order"}, "amount":{"N":"4300"}
  }'

$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#2"}, "SK":{"S":"PROFILE"},
    "type":{"S":"user"}, "name":{"S":"suzuki"}, "plan":{"S":"free"}
  }'

形の違うものが、同じテーブルに5件入りました。

1回のクエリで、利用者とその注文が両方取れる

bash
$ awsl dynamodb query --table-name AppData \
    --key-condition-expression 'PK = :pk' \
    --expression-attribute-values '{":pk":{"S":"USER#1"}}' \
    --return-consumed-capacity TOTAL \
    --output json | jq '{n: .Count, cu: .ConsumedCapacity.CapacityUnits,
                         rows: [.Items[] | {sk: .SK.S, type: .type.S}]}'
{
  "n": 4,
  "cu": 0.5,
  "rows": [
    {"sk": "ADDRESS#home",            "type": "address"},
    {"sk": "ORDER#2026-10-01#001",    "type": "order"},
    {"sk": "ORDER#2026-10-05#002",    "type": "order"},
    {"sk": "PROFILE",                 "type": "user"}
  ]
}

[スクリーンショット: 04_single-table-one-query.png] 1回の query で、プロフィールと住所と注文が同時に返っているところ。

✅ リレーショナルなら3テーブルへの3回のアクセス(または JOIN)が要ったものが、 ✅ 1回の query、消費キャパシティ 0.5 で終わっています。 これが単一テーブル設計の目的です。「クエリの回数を減らすこと」であって、他の理由はありません。

注文だけ欲しいなら、SK で切る

bash
$ awsl dynamodb query --table-name AppData \
    --key-condition-expression 'PK = :pk AND begins_with(SK, :sk)' \
    --expression-attribute-values '{":pk":{"S":"USER#1"},":sk":{"S":"ORDER#"}}' \
    --query 'Items[].[SK.S, amount.N]' --output text
ORDER#2026-10-01#001    12800
ORDER#2026-10-05#002    4300

✅ SK の頭に種類を書いておくと、種類ごとに切り出せます。 これが ORDER# の意味です。

代償 — 死ぬほど読みにくい

中身を全部見ると、こうなります。

bash
$ awsl dynamodb scan --table-name AppData --output json \
    | jq -r '.Items[] | [.PK.S, .SK.S, .type.S] | @tsv'
USER#1  ADDRESS#home            address
USER#1  ORDER#2026-10-01#001    order
USER#1  ORDER#2026-10-05#002    order
USER#1  PROFILE                 user
USER#2  PROFILE                 user

テーブルを開いても、何のデータか分かりません。 これが最大の代償です。

失われるもの具体的に
見て分かることPK SK type という列名しかない。中身を読まないと何のテーブルか分からない
管理画面の使いやすさAWSのコンソールで眺めても、意味が読み取れない
新しく入った人への説明SK の命名規則を書いた資料が無いと、誰も触れない
「ちょっと集計したい」SQL のように打てない。全件読むしかない
設計変更SK の形を変えると、既存データが全部引けなくなる

単一テーブル設計は、常に正しくありません

正直に書きます。

単一テーブル設計は「クエリの回数を減らすため」の最適化です。 クエリの回数が問題になっていないなら、やる理由がありません。

こういうときは、やるこういうときは、やらない
✅ 1画面で複数種類のデータを必ず一緒に出す種類ごとに使う場面がバラバラ
✅ アクセスパターンが完全に固まっているこれから要件が変わりそう
✅ レイテンシが1桁ミリ秒で要る数十ミリ秒で困らない
✅ チームが DynamoDB に慣れている人が入れ替わる。引き継ぐ必要がある

テーブルを分けても DynamoDB は動きます。 Users と Orders に分けて、2回引いてもいい。 「定石だから」で選ぶと、読めないテーブルだけが残ります。


⑨ キャパシティ・Streams・TTL

オンデマンドとプロビジョンド

オンデマンド(PAY_PER_REQUEST)プロビジョンド(PROVISIONED)
事前に決めるもの✅ 何も決めない1秒あたりの読み書きの上限
急にアクセスが増えたら✅ 勝手に追従する上限を超えた分は失敗する
使っていないとき✅ リクエスト0なら、保管料だけ確保した分だけ課金され続ける
1リクエストあたりの単価高い安い
Auto Scaling不要設定できるが、追従に数分かかる
切り替え✅ 相互に変更できる(回数制限あり)✅ 同上
迷ったら✅ こちら。特に学習と個人開発量が読めて、常に一定のときだけ

プロビジョンドで上限を低く設定していると、アクセスが増えた瞬間にエラーが出ます。 ProvisionedThroughputExceededException という名前で返ります。 「DBが落ちる」のではなく「拒否される」のが、DynamoDB の壊れ方です。

金額は変わるので、公式の料金ページで確かめてください。 課金される軸だけ書いておきます。

課金の軸何で数えるか
書き込み1KBごと。GSI の数だけ倍になる
読み込み4KBごと。強い整合性で読むと2倍
保管入っているデータの量。GSI の分も含む
Streams の読み取り読んだリクエストの回数
バックアップ・復元量と回数
リージョン間の転送出ていく量

DynamoDB Streams — 変更を後続に流す

「注文が入ったら通知を送る」を、アプリに書かずに済ませたい。 それがこれです。

bash
$ awsl dynamodb update-table --table-name AppData \
    --stream-specification StreamEnabled=true,StreamViewType=NEW_AND_OLD_IMAGES \
    --query 'TableDescription.LatestStreamArn'
"arn:aws:dynamodb:ap-northeast-1:000000000000:table/AppData/stream/2026-10-07T04:11:52.883"
StreamViewType流れてくるもの
KEYS_ONLYキーだけ
NEW_IMAGE変更後の姿
OLD_IMAGE変更前の姿
NEW_AND_OLD_IMAGES✅ 両方。差分が見たいならこれ

中身を覗きます。

bash
$ STREAM_ARN=$(awsl dynamodb describe-table --table-name AppData \
    --query 'Table.LatestStreamArn' --output text)

$ awsl dynamodbstreams describe-stream --stream-arn "$STREAM_ARN" \
    --query 'StreamDescription.[StreamStatus,StreamViewType,length(Shards)]'
[
    "ENABLED",
    "NEW_AND_OLD_IMAGES",
    1
]

✅ ENABLED で、シャードが1本できています。

実際に1件書いてから、流れてきたものを読みます。

bash
$ awsl dynamodb put-item --table-name AppData --item '{
    "PK":{"S":"USER#2"}, "SK":{"S":"ORDER#2026-10-07#003"},
    "type":{"S":"order"}, "amount":{"N":"9800"}
  }'

$ SHARD=$(awsl dynamodbstreams describe-stream --stream-arn "$STREAM_ARN" \
    --query 'StreamDescription.Shards[0].ShardId' --output text)

$ ITER=$(awsl dynamodbstreams get-shard-iterator --stream-arn "$STREAM_ARN" \
    --shard-id "$SHARD" --shard-iterator-type TRIM_HORIZON \
    --query 'ShardIterator' --output text)

$ awsl dynamodbstreams get-records --shard-iterator "$ITER" \
    --query 'Records[].[eventName, dynamodb.Keys.SK.S]' --output text
INSERT  ORDER#2026-10-07#003

✅ 書き込みが、イベントとして流れてきました。

eventName は INSERT MODIFY REMOVE の3つです。 本番では、ここに Lambda を繋いで自動で処理させます (待っている時間に課金されない — サーバーレスとLambda)。 LocalStack のコミュニティ版でも Lambda との連携は動きますが、SERVICES に lambda を足す必要があります。 この記事では describe-stream と get-records までにしておきます。

Streams で気をつけること。

項目内容
保持期間24時間。それを過ぎたイベントは消える
順番✅ 同じパーティションキーの中では、書いた順に届く
重複同じイベントが2回届くことがある。受け側が「2回来ても平気」に作る
有効化の前の変更流れない。有効にした時点以降だけ

TTL — 期限が来たら自動で消える

セッションや一時データに使います。

bash
$ awsl dynamodb create-table --table-name Sessions \
    --attribute-definitions AttributeName=sid,AttributeType=S \
    --key-schema AttributeName=sid,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST

$ awsl dynamodb update-time-to-live --table-name Sessions \
    --time-to-live-specification 'Enabled=true,AttributeName=expiresAt'
{
    "TimeToLiveSpecification": {
        "Enabled": true,
        "AttributeName": "expiresAt"
    }
}

60秒後に切れるセッションを入れます。

bash
$ awsl dynamodb put-item --table-name Sessions --item "{
    \"sid\":{\"S\":\"s001\"},
    \"expiresAt\":{\"N\":\"$(($(date +%s) + 60))\"}
  }"

$ awsl dynamodb scan --table-name Sessions --query 'Count'
1

expiresAt は「UNIX時刻の秒」で、型は N(数値)です。 ミリ秒で入れると、5万年後になって永久に消えません。 これは実際にやりました。

TTL について、正直に書いておくこと。

項目内容
消えるまでの時間本物でも「通常は数日以内」としか書かれていない。即時ではない
期限切れでも読める消えるまでの間、query に出てくる。アプリ側でも期限を見る必要がある
✅ 削除の費用TTL による削除には書き込み費用がかからない
Streams には流れるREMOVE イベントが出る。ゴミ掃除の連鎖に使える
LocalStack では時間の進み方が本物と違う。「いつ消えるか」の実測はできない

正直な結論 — DynamoDB を選ぶかどうかの判断表

状況判断
問いが完全に固定されていて、これから増えない✅ DynamoDB が向く
キーで1件引く、または1人分の一覧、しかやらない✅ 向く。これが最も得意な形
アクセス量が読めない。急に100倍になりうる✅ 向く。オンデマンドで勝手に伸びる
セッション・カート・IoTの記録・イベントログ✅ 典型的な適材
「たぶんこういう検索も要るようになる」やめる。あとから足せない
管理画面で自由に絞り込みたいやめる。SQL のほうが100倍楽
集計・レポートを出すやめる。SUM も GROUP BY も無い
データの種類が3つ以上あって、関係が複雑やめる。JOIN が無い痛みが効いてくる
チームに DynamoDB の経験者がいないやめる。設計を間違えると入れ直しになる
とりあえずモダンな方を使いたい絶対にやめる

「とりあえず DynamoDB」は、たいてい後悔します。 後悔するタイミングは、たいてい「新しい機能を足そうとしたとき」です。 そのとき、テーブルを作り直してデータを移すか、GSI を積むか、scan を書くか、の三択になります。 どれも高いか、遅いか、間違っています。

逆に言うと、こうです。

✅ 問いが1通りしかないと言い切れるなら、DynamoDB ほど楽な道具はありません。 サーバーの台数も、レプリカも、索引の再構築も、バージョンアップも、一切考えなくていい。 選び方の全体像は SQLiteはおもちゃではない — 用途で選ぶデータベース にまとめてあります。


つまずいたところ

AttributeDefinitions に全部の列を書こうとした。 「使っていない属性定義がある」というエラーの意味が、30分分からなかった。キーにする属性だけを書く場所だと分かったとき、DynamoDB が「列」という概念を持っていないことに初めて気づきました。エラーメッセージは正しいことを言っていて、私の前提のほうが間違っていました。

{"N":32} と書いてエラーになった。 数値もクオートで囲みます。 {"N":"32"} です。「型が N なのに文字列で書く」のが気持ち悪くて、何度も間違えました。 JSON の数値精度でズレるのを避けるための仕様だと知ってから、やっと納得しました。

--filter-expression を「絞り込み」だと思っていた。 これが一番大きい勘違いでした。 ScannedCount が 10000 と出て初めて、全部読んでから捨てているだけだと分かりました。手元では一瞬で返るので、測るまで気づけません。 --return-consumed-capacity TOTAL を付ける習慣が無かったら、本番まで気づきませんでした。

BETWEEN で最終日のデータが漏れた。 ORDER#2026-06-30 で切ると、ORDER#2026-06-30#0012 は範囲の外でした。「6月の売上が少しだけ合わない」という形で出て、原因を探すのに時間がかかりました。文字列比較なので、末尾に #zzzz のような番人を置きます。

status で query を書いて予約語エラーになった。 status name size count timestamp は全部予約語です。#s に逃がして --expression-attribute-names で対応付けます。最初は「なぜ普通の単語が使えないのか」と思いましたが、逃がす書き方を1回覚えれば済む話でした。

GSI を足したら書き込みが遅くなった気がした。 気のせいではなく、書き込みが GSI の数だけ増えています。 ProjectionType: ALL にしていたので、保管量も倍でした。「索引を足す」感覚で足すものではありませんでした。

GSI のパーティションキーに status を選んだ。 値が3種類しかないので、箱が3個です。 説明のために作りましたが、本物ならホットパーティションで詰まります。 uniq -c で数えるまで、自分でその罠を踏んでいることに気づきませんでした。

LocalStack で GSI が即座に反映されて安心した。 本物は結果整合で遅れます。 手元で動いたから大丈夫、が通じない部分です。 「エミュレータで再現されないもの」を先に調べておくべきでした。

TTL の時刻をミリ秒で入れた。 UNIX時刻の「秒」です。 ミリ秒で入れると5万年後になり、永久に消えません。 date +%s の出力をそのまま使えば間違えません。

単一テーブル設計にしたら、自分で読めなくなった。 1週間後に scan して、何のデータか分かりませんでした。 SK の命名規則を書いた資料が無いと、書いた本人ですら触れません。 「定石だから」で選んだのが間違いでした。


後片づけ

ここまでで作ったものを、全部消します。

まず、何があるか見ます。

bash
$ awsl dynamodb list-tables
{
    "TableNames": ["AppData", "Events", "Orders", "Sessions", "Users", "WithLsi"]
}

1つずつ消します。

bash
$ for t in AppData Events Orders Sessions Users WithLsi; do
$   awsl dynamodb delete-table --table-name "$t" --query 'TableDescription.TableName' --output text
$ done
AppData
Events
Orders
Sessions
Users
WithLsi

空になったか確認します。

bash
$ awsl dynamodb list-tables
{
    "TableNames": []
}

delete-table は非同期です。 すぐに list-tables を打つと、まだ DELETING で残って見えることがあります。

LocalStack ごと落として、ボリュームも消します。

bash
$ cd ~/awslab/ddb
$ docker compose down -v
[+] Running 2/2
 ✔ Container localstack   Removed
 ✔ Network ddb_default    Removed

-v が重要です。 付けないとボリュームが残り、次に立てたときにテーブルが残っています。

生成した1万件分のJSONも消します。

bash
$ cd ~
$ rm -rf ~/awslab/ddb
$ ls ~/awslab

何も残っていなければ完了です。

bash
$ docker ps -a | grep localstack
$ docker volume ls | grep ddb

どちらも何も出なければ、きれいになっています。

✅ 今回は本物の AWS に一切触れていないので、消し忘れによる課金はありません。 ただし、本物でやったときは delete-table だけでは足りません。 オンデマンドバックアップ、ポイントインタイムリカバリのスナップショット、S3へのエクスポートは、 テーブルを消しても別に残り、保管料がかかり続けます。 消すときは、それも一緒に確認します。


まとめ — 理解できたこと

  • DynamoDB は、設計の順番がリレーショナルと真逆。 リレーショナルはデータの形から、DynamoDB は問いの一覧から始める。問いが決まらないとテーブルが作れない
  • AttributeDefinitions は列の定義ではない。 キーに使う属性だけを書く場所で、キー以外の属性はテーブル定義に一切出てこない
  • get-item は検索ではなく「この住所のものを持ってこい」という命令。 住所が分からないときは使えない。無いキーを引いてもエラーにならず、空が返る
  • --filter-expression は読む量を減らさない。 全部読んでから捨てているだけで、課金も速度制限も ScannedCount のほうで数える。1万件で query の ScannedCount が50、scan が10000、消費キャパシティは 0.5 対 168.5 だった
  • query は件数が増えても速さが変わらず、scan は完全に比例する。 開発中は小さいので scan でも動いてしまい、本番で初めて壊れる
  • 利用者が待っている処理の中に scan があったら、設計が間違っている。 ただし1日1回のバッチ集計・移行・増えない小さな表・手での確認は例外として正しい
  • DynamoDB で使える範囲検索は、ソートキーの1本だけ。 = > < BETWEEN begins_with が全部で、部分一致も否定も IN もキー条件では使えない。パーティションキーは = のみ
  • BETWEEN は文字列比較なので、#zzzz のような番人を置かないと最終日が漏れる
  • 並べ替えは SK に組み込んだ1通りしかできない。 「金額順にも並べたい」は、あとからは足せない
  • パーティションキーが偏ると、台数を増やしても詰まる。 日付を PK にすると「今日」の箱に全部集中する。実際に数えたら 1804 対 39 だった。対策は偏らないキーを選ぶか、サフィックスで箱を割る(読むときは回数が増える)
  • LSI はテーブル作成時にしか作れず、パーティションキーも変えられない。 迷ったら GSI
  • GSI は結果整合で、--consistent-read が使えない。 そして1回の書き込みが GSI の数だけ増える。ProjectionType を ALL にすると保管量も増える。値の種類が少ない属性を GSI の PK にしてはいけない
  • 単一テーブル設計の目的は「クエリの回数を減らすこと」だけ。 1回の query でプロフィールと住所と注文が 消費キャパシティ 0.5 で取れた代わりに、テーブルを開いても何のデータか分からなくなる。クエリ回数が問題でないなら、やらなくていい
  • キャパシティは迷ったらオンデマンド。 プロビジョンドは上限を超えると落ちるのではなく拒否される
  • Streams は24時間しか保持されず、同じイベントが2回届きうる。 TTL は「秒」で入れ、消えるまでは読めてしまう
  • LocalStack で再現されないものが3つあった。 ホットパーティションの詰まり・GSI の遅延・TTL の削除タイミング。エミュレータで動いた=本番で動く、ではない
  • 正直な結論として、DynamoDB が向く条件は狭い。 問いが固定で、規模が読めないものに向く。「とりあえず DynamoDB」は、新しい機能を足そうとした瞬間に後悔する

参考リンク


次に読む

この記事は 【深掘り】AWS の 11 / 16 本目です。

記事
← 前の記事RDSとElastiCacheの仕組み — フェイルオーバーで接続が切れる
→ 次の記事Lambdaとコールドスタート — 最初の1回だけ3秒かかる

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

AWS›AWS — DynamoDB
  • 問いを先に決めないとテーブルが作れない
  • Scan を書いた時点で設計が間違っている

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次