DynamoDBのバッチ操作
DynamoDBのバッチAPIは、多くの項目操作を単一のリクエストに畳み込みます。読み込みは
BatchGetItem、書き込みはBatchWriteItemです。バッチはトランザクションではありません。
DynamoDBのバッチ操作とは?
DynamoDBのバッチ操作は、多くの項目の読み書きを単一のリクエストに畳み込みます。BatchGetItemは最大100項目を取得し、BatchWriteItemは最大25項目をputまたはdeleteします。それぞれ16 MBが上限です。往復を節約しますが、キャパシティーは節約しません。決定的に、バッチはトランザクションではありません。項目は独立して成功または失敗し、ロールバックはありません。
BatchGetItemは、1つ以上のテーブルにまたがって最大100項目(または16 MB)を 1回の呼び出しで取得します。BatchWriteItemは、最大25件のput/delete操作(または16 MB)を受け付けます。更新はなく、更新にはBatchExecuteStatementでPartiQLのUPDATEをバッチ化します。- 部分的な失敗は正常です。 スロットリングされた項目は
UnprocessedItems/UnprocessedKeysで返ってきて、自分でバックオフ付きで再試行します。 - 個別呼び出しと同じキャパシティーコスト。 バッチ化は往復を節約するのであって、キャパシティーユニットを節約するのではありません。
DynoTableは一括削除とその再試行を代わりに実行します(手順)。
問題:多くの項目、1回の往復
サポートデスクを運営しているとしましょう。ダッシュボードはキューを描画するために 50件のチケットをIDで読み込む必要があり、夜間ジョブは解決済みの1,000件のチケットをアーカイブします。それを1項目ずつやると50回(または1,000回)の逐次往復になります。レイテンシーが積み上がり、ジョブは這うように進みます。
バッチ化はそれらをひと握りの呼び出しに畳みます:
| パターン | キー数 | 呼び出し数 | メモ |
|---|---|---|---|
直列 GetItem | 50 | 50 | いちばん単純なコード。テールレイテンシーは最悪 |
1回の BatchGetItem | 50 | 1 | 50回の Get と同じ RCU 合計 |
| 2回のバッチ | 120 | 2 | 2回目のバッチが20キーを運ぶ |
キャパシティーコストは変わりません。書き込みなら、1,000件の削除をバッチあたり25件でまとめると、個別削除1,000回ではなく最低でもBatchWriteItem40回で済みます(再試行は別)。
バッチAPIの仕組み
BatchGetItemは(1つ以上のテーブルにまたがる)プライマリキーの集合を取り、一致する項目を返します。読めなかったものは、呼び出し全体を失敗させるのではなく
UnprocessedKeysで返ってきます。
リクエストマップのテーブルのエントリにConsistentRead: trueを設定しない限り、読み込みは結果整合性です。強力な整合性のある読み込みのコストは2倍で、各テーブルエントリが自分のフラグを持つので、1回の呼び出しで混ぜることができます。
BatchWriteItemはPutRequest / DeleteRequest操作のリストを取ります。
更新はありません。バッチ書き込みは項目まるごとを置き換える(put)か、それを削除する(delete)かのどちらかです。書けなかった項目はUnprocessedItemsで返ってきます。
多くの項目の一部の属性を変更するには、BatchExecuteStatementの呼び出しごとに最大25件の
PartiQLステートメントを送ります。それぞれがUPDATE "Tickets" SET status = 'archived' WHERE PK = '…' AND SK = '…'です。
各ステートメントはアトミックですがバッチはそうではなく、失敗したステートメントは
Responsesの自分のエントリでエラーを報告します。
呼び出しごとの上限
件数の上限はすぐに失敗します。100キーを超えるとValidationException
("Too many items requested for the BatchGetItem call")が返り、25件を超える書き込みリクエストは"Too many items requested for the BatchWriteItem call"を返します。
下のループのように、ジョブは自分でチャンクに分けましょう。
16 MBの上限が先に効くことはめったにありません。BatchGetItemがそれに当たるのは、項目の平均が約164 KB(16,384 KB ÷ 100)を超えるときだけです。AWSの例では300 KBの項目を100件要求し、エラーではなく52件とUnprocessedKeysが返ってきます。
BatchWriteItemの16 MBについて、AWSは2通りに書いています。制約のページは"the total size of all the items written"を数え、APIリファレンスは"The total request size"を数えます。
DynamoDB Localは、型タグと属性名を含むシリアライズ後のリクエストを数えます。上限の400 KB近くの項目25件でもたいていは収まるので、実質的にどのジョブでも25リクエストの上限が先に効きます。ただし、タグの多い項目はシリアライズ後に項目サイズをはるかに超えることがあります。それぞれが
1文字の属性40,000個から成るマップである約240 KBの項目25件は、シリアライズ後に18 MBになり、
DynamoDB Localはそのバッチを拒否しました。こうした項目は、シリアライズ後のサイズでもチャンクに分けましょう(JSONマーシャリング)。
バッチはトランザクションではない
アーカイブジョブのバッチが途中でスループット上限にぶつかると、一部のチケットは削除され、一部はされません。DynamoDBは成功した削除をそのまま残し、残りはあなたが再試行します。
オールオアナッシングのセマンティクス(「チケットをアーカイブ済みに移動しかつ未対応チケットのカウンターを減らす、さもなくばどちらもしない」)が必要なら、それは
TransactWriteItemsです。上限は100アクションと4 MBで、各書き込みは2倍で課金されます。
| 必要なこと | API | 呼び出しあたりの最大 | 失敗時 |
|---|---|---|---|
| ベストエフォートの一括put/delete | BatchWriteItem | 25リクエスト、16 MB | UnprocessedItemsを再試行 |
| 一括での部分的な更新 | BatchExecuteStatement (PartiQL) | 25ステートメント | ステートメントごとのエラー |
| 既知の多数キーを読む | BatchGetItem | 100キー、16 MB | UnprocessedKeysを再試行 |
| オールオアナッシングの書き込み、または別項目の確認 | TransactWriteItems (ConditionCheck) | 100アクション、4 MB | トランザクション全体がキャンセル |
未処理項目の扱い
正しいバッチの呼び出し元は、常に未処理の集合をチェックして再試行します。
DynamoDBは、呼び出しは受理されたが一部の項目を処理できなかったとき(典型的には一時的なスロットリング)にUnprocessedItems/UnprocessedKeysを返します。
項目が1つも処理できなかった場合は、代わりに呼び出しが
ProvisionedThroughputExceededExceptionまたはThrottlingExceptionを投げます。
AWS SDKはそれらを自動で再試行します。
未処理の項目だけを、指数バックオフとジッターを付けて再送し、試行回数に上限を設けて、引っかかった項目が永遠にループしないようにします。 AWS SDK for JavaScript v3では:
import {BatchWriteItemCommand, DynamoDBClient} from '@aws-sdk/client-dynamodb';
const client = new DynamoDBClient({});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// requests: [{DeleteRequest: {Key: {...}}}, {PutRequest: {Item: {...}}}, ...]
async function batchWrite(table, requests, maxAttempts = 8) {
for (let i = 0; i < requests.length; i += 25) {
let pending = {[table]: requests.slice(i, i + 25)};
for (let attempt = 0; Object.keys(pending).length > 0; attempt++) {
if (attempt === maxAttempts) {
throw new Error(`gave up with ${pending[table].length} unprocessed items`);
}
if (attempt > 0) await sleep(Math.random() * 50 * 2 ** attempt); // full jitter
const res = await client.send(
new BatchWriteItemCommand({RequestItems: pending, ReturnConsumedCapacity: 'TOTAL'})
);
pending = res.UnprocessedItems ?? {};
const units = res.ConsumedCapacity?.[0]?.CapacityUnits ?? 0;
console.log(
`chunk ${i / 25}: ${units} write units, ${pending[table]?.length ?? 0} unprocessed`
);
}
}
}ループが諦めたら、残ったキーを捨てずにログに残すか永続化しましょう。バッチを撃ちっぱなしとして扱うと、ひそかに書き込みが落ち、数か月後にデータ欠損として表面化する類のバグになります。
ReturnConsumedCapacity: 'TOTAL'は各レスポンスにテーブルごとのConsumedCapacity
エントリを加え、ループはそれを残数の横にログします。バックフィル中に増え続ける残数は、ジョブが止まる前にスロットリングを警告してくれます。
DynoTableでのバッチ書き込み
DynoTableでは、編集をローカルにステージングして、コミットする前にレビューします。コミットは最大100項目の条件付きTransactWriteItemsのチャンクとして送られます。チャンクが失敗するとコミットはそこで止まり、それより前のチャンクは適用されたまま残ります。
⌘⇧⌫は選択した行を、25件ずつのBatchWriteItem呼び出しとして直接削除し、未処理項目の再試行も代わりに処理します。クエリに一致するすべての項目については、一括編集と一括削除が最大10,000項目をステージングまたはコミットするか、上限なしで直接書き込みます。直接実行は一致した項目をページ送りしながら書き込みのペースを調整し、任意で最大書き込み数/秒の上限を設けられます。

落とし穴と次のステップ
UnprocessedItems/UnprocessedKeysは常にバックオフと上限付きで再試行しましょう。それらは例外ではなく想定内です。- 部分的失敗のロールバックはありません。 アトミック性が必要ですか?トランザクションを使いましょう。
- バッチ書き込みに更新はありません。 PartiQLの
UPDATEをBatchExecuteStatementで送るか、項目ごとにUpdateItemを使いましょう。 - まず請求額を見積もりましょう。 バッチは束ねる個別の書き込みと同じキャパシティーを消費します。DynamoDB料金計算機でその規模を算出できます。
- フィクスチャから種まきしますか? プレーンJSONの項目を
DynamoDB JSONコンバータでDynamoDB JSONに変換し、それぞれを
PutRequestで包みましょう。
再試行ループをスクリプト化せずに一括の読み込みと削除を実行したいですか? DynoTableをダウンロードして、自分のテーブルで作業しましょう。


