DynamoDB BatchWriteItem con la AWS CLI

aws dynamodb batch-write-item inserisce o elimina fino a 25 Item in un solo comando. Dalla shell ha due spigoli vivi che gli SDK smussano: ogni valore è JSON DynamoDB che devi quotare correttamente, e la CLI non ha alcun meccanismo per svuotare UnprocessedItems. I limiti e il modello di fallimento parziale sono in operazioni batch in DynamoDB.

Codice

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"}}}}
    ]
  }'

Eseguito su DynamoDB Local 3.3.0 stampa, per intero:

{
    "UnprocessedItems": {}
}

Spiegazione

Una mappa dei resti vuota è l'unico segnale di successo che ottieni. Il comando stampa UnprocessedItems e nient'altro, quindi uno script che controlla solo lo stato di uscita chiamerà successo un batch scritto a metà. Analizza la mappa; jq -e '.UnprocessedItems | length == 0' è tutto il controllo.
Non c'è alcun flag per svuotarla. aws dynamodb query help offre --starting-token, --max-items e --page-size. aws dynamodb batch-write-item help non ne offre nessuno, perché UnprocessedItems non è un cursore di paginazione. Reimmetterla è un loop di shell con uno sleep, ed è già nella forma di --request-items.
--condition-expression e --return-values non sono accettati qui, ed è l'API, non la CLI: le condizioni non possono essere attaccate alle singole richieste di put ed elimina. Ogni PutRequest sostituisce l'intero Item memorizzato, quindi un batch costruito da un payload parziale elimina gli attributi che ha lasciato fuori.
Usa file://, non JSON inline. --request-items file://writes.json toglie il quoting della shell dall'elenco delle cose che possono andare storte, e conta perché la maggior parte di ciò che va storto in questo comando è il quoting.
Una sola voce sbagliata costa tutte e 25. Una tabella mancante, una chiave che non corrisponde allo schema, un Item da oltre 400 KB, un totale oltre i 16 MB, una chiave di partizione sopra i 2048 byte o una chiave di ordinamento sopra i 1024 byte: ciascuno rifiuta l'intero batch invece della voce colpevole.

Cosa stampa il comando, rifiuti compresi

Aggiungi --return-consumed-capacity TOTAL al blocco qui sopra e DynamoDB Local 3.3.0 risponde:

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

Tre unità per due put e un delete: il batch ha comprato un round trip, non uno sconto. Ogni voce è fatturata come il PutItem o il DeleteItem individuale che rappresenta, arrotondato a 1 KB.

Esegui il delete una seconda volta, quando Ella Fitzgerald / Misty è già sparito, e DynamoDB Local riporta 2.0 unità per quel singolo DeleteRequest. Il riferimento di BatchWriteItem (recuperato il 2026-07-28) dice che un delete su un Item inesistente consuma una unità di capacità di scrittura, e un delete-item autonomo sullo stesso motore locale riporta effettivamente 1.0. Tratta i numeri di capacità locali come indicativi. Il punto che resta valido in entrambi i casi è che un delete che non trova nulla viene comunque fatturato.

Due richieste che il servizio rifiuta di netto, su stderr, stato di uscita 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

Sulla seconda vale la pena soffermarsi. È stata prodotta da un PutRequest e un DeleteRequest sulla stessa chiave, non da due put. DynamoDB conta come duplicato qualsiasi seconda operazione su un Item nello stesso batch, quindi «elimina la vecchia riga e scrivi quella nuova» fallisce come singolo batch anche se le due voci non si somigliano affatto.

Assemblare quelle mappe di valori dentro apici singoli è dove se ne va il tempo. Il DynamoDB Expression Builder produce mappe tipizzate e copia un comando eseguibile, così un fallimento è almeno un fallimento vero e non un backslash di troppo.

Per caricare in blocco o svuotare Item da CSV o JSON senza fare escape di nulla, scarica DynoTable.

Esempi correlati

DynamoDB BatchWriteItem in Node.js — la stessa scrittura batch con AWS SDK v3.
Scrittura batch DynamoDB in Python — il batch_writer() di boto3 fa il loop di retry al posto tuo.
DynamoDB PutItem con la AWS CLI — la scrittura del singolo Item che questa raggruppa.
Operazioni batch in DynamoDB — limiti, fallimento parziale e quando il batching conviene.
"Too many items requested for the BatchWriteItem call" — più di 25 richieste di put/elimina in un solo batch.
"Provided list of item keys contains duplicates" — due richieste che toccano la stessa chiave in un solo batch.

Riferimenti

Ultima verifica 2026-07-28 rispetto alla documentazione ufficiale AWS collegata sopra.