DynamoDB クエリビルダー
テーブル、インデックス、キー条件、フィルター、プロジェクション、Limit、ソート順、整合性のある読み取り、ページネーションまで、Query または Scan リクエスト全体を組み立て、AWS SDK v3、DocumentClient、CLI、boto3、Java、Go、.NET、Rust、Kotlin、PHP、Ruby、DynamoDB-Toolbox の実行可能なプログラム、または PartiQL ステートメントとしてコピーできます。
dynamodb-expression-builder は、このツールの基盤となるオープンソース（MIT）ライブラリです。
アクセスパターンから実行可能なリクエストへ
式だけで仕事が終わることはめったにありません。本番の Query は、どのインデックスを読むか、リクエストごとに何件評価するか、ソートキーをどちら向きにたどるか、読み取りに強い整合性が必要か、そしてレスポンスが LastEvaluatedKey を伴って返ってきたらどうするかも決めます。これらのリクエストレベルのパラメータは式の文字列の外側にあり — コピペしたスニペットが狂うのはたいていそこです。
このビルダーはリクエストを作業の単位として扱います。式ビルダーと同じ型付きで予約語に安全なモデルの上にキー条件・フィルタ・射影を組み立て、その横でリクエストオプションを設定します。出力は断片ではなく、実行できるプログラムです — import、クライアント初期化、呼び出しそのもの、そして「全ページを取得」を有効にすれば、結果の全ページを汲み尽くす ExclusiveStartKey のループまで。
生成コードはターゲットごとに正直です。AWS CLI は自動でページネーションするため Limit は --page-size になり、単一リクエスト実行には --no-paginate が付きます。PartiQL はステートメントではなく ExecuteStatement API に属するパラメータをお断りします。降順の Query は、表現できる場面ではソートキーへの ORDER BY になります。
必要なのは式そのものだけ — 6 つの操作いずれかの条件式・フィルタ式・更新式とそのプレースホルダーマップ — ですか？ DynamoDB 式ビルダーはまさにそのために作られています。 まず 2 つの読み取り操作のどちらにするか迷っていますか？ Query と Scan の比較 では、それぞれが正解になる場面を解説しています。
よくある質問
DynamoDB 式ビルダーとは何が違いますか？
両者は意図的に役割を分けています。式ビルダーは式の構文が主題です — 6 つの操作すべてにわたるキー条件、フィルタ、更新式・条件式と、その ExpressionAttributeNames/Values マップ — そしてコマンド単体を出力します。クエリビルダーは完全な Query / Scan リクエストが主題です。テーブルとインデックス、キー条件、フィルタ、射影に加え、式ツールが扱わないリクエストレベルのパラメータ（Limit、ソート順、ConsistentRead、ExclusiveStartKey）まで含めて、クライアント初期化と任意のページネーションループを備えた実行可能なプログラムを出力します。
Query や Scan で Limit は実際に何を制限しますか？
Limit はリクエストごとに DynamoDB が評価するアイテム数の上限であり、返ってくる一致アイテム数ではありません。フィルタは読み取りの後に適用されるため、Limit 25 と FilterExpression を持つ Query は 25 件未満 — あるいは 0 件 — を返しつつ、評価したすべての読み取りキャパシティを消費し、ページネーションは LastEvaluatedKey から続きます。自動でページネーションする AWS CLI では、同じパラメータを --page-size で設定します。
DynamoDB のページネーション（LastEvaluatedKey）はどう動きますか？
続きのデータがある Query または Scan のレスポンスには LastEvaluatedKey（最後に読み取った項目のプライマリキー）が含まれます。それを次のリクエストで ExclusiveStartKey として渡し、LastEvaluatedKey を含まないレスポンスが返るまで繰り返します。「すべてのページを取得」をオンにすると、生成される SDK v3、boto3、Java、.NET のプログラムにはそのループがそのまま含まれます。Go、Rust、Kotlin、PHP、Ruby と DocumentClient は各 SDK 標準のページネーターを使い、AWS CLI は --no-paginate を渡さない限り自動でページをたどります。
強い整合性の読み取りはいつ使えますか？
ConsistentRead はベーステーブルとローカルセカンダリインデックスで機能しますが、グローバルセカンダリインデックスでは使えません — ConsistentRead を設定した GSI への Query は拒否されます。強い整合性の読み取りは、結果整合性の読み取りの 2 倍の読み取りキャパシティも消費します。これは PartiQL ステートメント本文ではなく API のパラメータなので、PartiQL タブは正直にお断りします。
ここに入力した内容はどこかにアップロードされますか？
いいえ。これは静的なページです。リクエストの組み立てとコード生成はすべてブラウザ内で行われるため、テーブル名・キー値・フィルタがサーバーに届くことはありません。「リンクをコピー」はリクエスト全体を URL に詰め込みます — 入力内容がページの外に出る唯一の経路はそのリンクの共有であり、それはあなたの手の中にあります。