AWS CLI での DynamoDB BatchGetItem

aws dynamodb batch-get-item は、1 つのコマンドで プライマリキー指定のアイテムを最大 100 件 取得します。コマンドラインで query や scan と違うのは 2 点です。キーはシェルのクォートをくぐり抜けさせなければならないネストした DynamoDB JSON であること、そして CLI が UnprocessedKeys を代わりに汲み出してくれないことです。上限と部分結果のルールは DynamoDB のバッチ操作にあります。

コード

aws dynamodb batch-get-item \
  --request-items '{
    "Music": {
      "Keys": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}
      ]
    }
  }'

省略した形では、出力は各テーブルに、見つかったアイテムと残ったキーを対応づけます。逐語のフル実行結果はこのページの下のほうにあります。

{
    "Responses": {
        "Music": [
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
        ]
    },
    "UnprocessedKeys": {}
}

解説

このコマンドに CLI のページネーション機構はありません。aws dynamodb query help は --starting-token、--max-items、--page-size を並べますが、aws dynamodb batch-get-item help はそのどれも並べません。UnprocessedKeys はページネーショントークンではなく、CLI はこの呼び出しを一発ものとして扱うので、汲み出しはフラグではなく自分のシェルループの仕事です。
残りのマップは、そのまま入力形式になっています。空でない UnprocessedKeys は形を変えずに --request-items に戻して渡せます。だからこそ bash の while ループが我慢できるものになります。試行の間はスリープしましょう。すぐに再実行すると同じスロットリング中のパーティションに当たります。
ProjectionExpression と ConsistentRead はテーブルごとのオブジェクトの中、"Keys" の隣に置きます。これらを --request-items のトップレベルに置くのが、ここで最もよくある形の誤りです。
マップはファイルに置きましょう。--request-items file://keys.json ならシェルのクォートを完全に回避でき、キーが数個を超えたら正気を保てる唯一の選択肢です。同時に、気づかないうちに 100 キーの上限に達する道でもあります。

このコマンドが実際に出力するもの

上のフェンスを、3 曲すべてが存在する DynamoDB Local 3.3.0 に対して逐語で実行した結果です（aws-cli/2.36.9）。

{
    "Responses": {
        "Music": [
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "A Mis Abuelos"}
            },
            {
                "Artist": {"S": "Ella Fitzgerald"},
                "AlbumTitle": {"S": "Ella in Berlin"},
                "Year": {"N": "1960"},
                "SongTitle": {"S": "Misty"}
            },
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "Cubano Chant"}
            }
        ]
    },
    "UnprocessedKeys": {}
}

（属性マップはそれぞれ 1 行に畳んでいます。それ以外は出力されたままです。）コマンドは Cubano Chant を最初に要求しましたが、返ってきたのは最後でした。レスポンスに位置の意味は一切ないので、.Responses.Music[0] を添字で読む jq の式は、サービスがたまたま最初に返す気になったアイテムを読んでいることになります。代わりにキー属性でフィルターしましょう。

きっぱり拒否されるリクエストが 2 つあります。標準エラー出力に表示され、終了ステータスは 254 です。

aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Provided list of item keys contains duplicates
aws: [ERROR]: An error occurred (ValidationException) when calling the BatchGetItem operation: Too many items requested for the BatchGetItem call

aws: [ERROR]: という接頭辞は CLI v2 のラッパーによるもので、その後ろのテキストはサービス自身のメッセージです。ゼロ以外の終了をすべてスロットリングとみなすリトライループは、このどちらでも永久に空回りします。バックオフする前にメッセージで分岐しましょう。

このネストした JSON をシングルクォートの中で手書きすることが、エラーの大半の発生源です。DynamoDB Expression Builder は型付きのキーマップを組み立て、そのまま実行できるコマンドをコピーさせてくれるので、少なくともクォートを容疑者リストから外せます。

キーの集合を読み戻して、JSON を往復させずにアイテムを見るには、DynoTable をダウンロードしてください。

参考資料

最終検証日 2026-07-28、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

AWS CLI での DynamoDB BatchGetItem

コード

解説

このコマンドが実際に出力するもの

関連する例

参考資料