DynamoDB BatchWriteItem mit der AWS CLI

aws dynamodb batch-write-item schreibt oder löscht bis zu 25 Items in einem Befehl. Aus der Shell hat der Befehl zwei scharfe Kanten, die die SDKs abfedern: Jeder Wert ist DynamoDB-JSON, das du korrekt quoten musst, und die CLI hat überhaupt keinen Mechanismus, um UnprocessedItems abzuarbeiten. Die Limits und das Modell für Teilfehler stehen in Batch-Operationen in DynamoDB.

Code

aws dynamodb batch-write-item \
  --request-items '{
    "Music": [
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"PutRequest": {"Item": {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}, "AlbumTitle": {"S": "Danzon"}, "Year": {"N": "1994"}}}},
      {"DeleteRequest": {"Key": {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}}}
    ]
  }'

Gegen DynamoDB Local 3.3.0 ausgeführt gibt das vollständig Folgendes aus:

{
    "UnprocessedItems": {}
}

Erklärung

Eine leere Restmenge ist das einzige Erfolgssignal, das du bekommst. Der Befehl gibt UnprocessedItems aus und sonst nichts — ein Skript, das nur den Exit-Status prüft, hält also einen halb geschriebenen Batch für einen Erfolg. Parse die Map; jq -e '.UnprocessedItems | length == 0' ist die ganze Prüfung.
Es gibt kein Flag, um sie abzuarbeiten. aws dynamodb query help bietet --starting-token, --max-items und --page-size. aws dynamodb batch-write-item help bietet keines davon, denn UnprocessedItems ist kein Paginierungs-Cursor. Es zurückzuspeisen ist eine Shell-Schleife mit einem sleep, und es hat bereits die Form von --request-items.
--condition-expression und --return-values werden hier nicht akzeptiert, und das liegt an der API, nicht an der CLI: An einzelne Put- und Delete-Anfragen lassen sich keine Bedingungen hängen. Jedes PutRequest ersetzt das gespeicherte Item vollständig — ein aus einem unvollständigen Payload gebauter Batch löscht also die Attribute, die er weglässt.
Nimm file:// statt Inline-JSON. --request-items file://writes.json streicht das Shell-Quoting von der Liste möglicher Fehlerquellen, was zählt, weil bei diesem Befehl das meiste am Quoting scheitert.
Ein schlechter Eintrag kostet alle 25. Eine fehlende Tabelle, ein Key, der nicht zum Schema passt, ein Item über 400 KB, mehr als 16 MB insgesamt, ein Partition Key über 2048 Byte oder ein Sort Key über 1024 Byte — jeder davon lässt den gesamten Batch scheitern statt nur den betreffenden Eintrag.

Was der Befehl ausgibt, inklusive der Ablehnungen

Häng --return-consumed-capacity TOTAL an den Block oben, und DynamoDB Local 3.3.0 antwortet:

{
    "UnprocessedItems": {},
    "ConsumedCapacity": [
        {
            "TableName": "Music",
            "CapacityUnits": 3.0
        }
    ]
}

Drei Einheiten für zwei Puts und ein Delete: Der Batch hat einen Round-Trip gespart, keinen Rabatt gebracht. Jeder Eintrag wird als das einzelne PutItem oder DeleteItem abgerechnet, für das er steht, aufgerundet auf 1 KB.

Führe das Delete ein zweites Mal aus, wenn Ella Fitzgerald / Misty schon weg ist, und DynamoDB Local meldet 2.0 Einheiten für dieses eine DeleteRequest. Die BatchWriteItem-Referenz (abgerufen am 2026-07-28) besagt, dass ein Delete auf einem nicht existierenden Item eine Write-Kapazitätseinheit verbraucht, und ein eigenständiges delete-item gegen dieselbe lokale Engine meldet tatsächlich 1.0. Behandle lokale Kapazitätszahlen als Richtwerte. Was so oder so bleibt: Ein Delete, das nichts findet, wird trotzdem abgerechnet.

Zwei Anfragen weist der Dienst rundheraus ab, auf stderr, mit Exit-Status 254:

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

Die zweite lohnt einen genaueren Blick. Sie entstand durch ein PutRequest und ein DeleteRequest auf demselben Key, nicht durch zwei Puts. DynamoDB zählt jede zweite Operation auf einem Item in einem Batch als Duplikat — „lösche die alte Zeile und schreibe die neue" scheitert also als einzelner Batch, obwohl die beiden Einträge nichts miteinander gemein zu haben scheinen.

Diese Wert-Maps in einfachen Anführungszeichen zusammenzubauen, ist der Zeitfresser. Der DynamoDB Expression Builder erzeugt typisierte Maps und kopiert einen lauffähigen Befehl heraus, sodass ein Fehlschlag wenigstens ein echter ist und kein verirrter Backslash.

Um Items massenhaft aus CSV oder JSON zu laden oder zu löschen, ohne irgendetwas davon zu escapen, lade DynoTable herunter.

Referenzen

Zuletzt verifiziert am 2026-07-28 gegen die oben verlinkte offizielle AWS-Dokumentation.

DynamoDB BatchWriteItem mit der AWS CLI

Code

Erklärung

Was der Befehl ausgibt, inklusive der Ablehnungen

Verwandte Beispiele

Referenzen