DynamoDB BatchWriteItem avec l'AWS CLI

aws dynamodb batch-write-item écrit ou supprime jusqu'à 25 éléments en une seule commande. Depuis le shell, elle a deux arêtes vives que les SDK adoucissent : chaque valeur est du JSON DynamoDB qu'il faut quoter correctement, et la CLI n'a aucun mécanisme pour vider UnprocessedItems. Les limites et le modèle d'échec partiel sont dans les opérations batch dans 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"}}}}
    ]
  }'

Exécutée contre DynamoDB Local 3.3.0, elle affiche, en tout et pour tout :

{
    "UnprocessedItems": {}
}

Explication

Une map de restes vide est le seul signal de succès que tu obtiens. La commande affiche UnprocessedItems et rien d'autre : un script qui ne vérifie que le statut de sortie déclarera réussi un batch à moitié écrit. Analyse la map ; jq -e '.UnprocessedItems | length == 0' suffit comme contrôle.
Il n'existe aucun flag pour la vider. aws dynamodb query help propose --starting-token, --max-items et --page-size. aws dynamodb batch-write-item help n'en propose aucun, parce que UnprocessedItems n'est pas un curseur de pagination. La réinjecter, c'est une boucle shell avec un sleep, et elle est déjà à la forme de --request-items.
--condition-expression et --return-values ne sont pas acceptés ici, et c'est l'API qui le veut, pas la CLI : les conditions ne peuvent pas être attachées aux requêtes put et delete individuelles. Chaque PutRequest remplace l'élément stocké en entier : un batch construit à partir d'une charge partielle supprime donc les attributs qu'il a omis.
Utilise file://, pas du JSON inline. --request-items file://writes.json retire le quoting du shell de la liste des choses qui peuvent mal tourner, ce qui compte parce que l'essentiel de ce qui rate dans cette commande, c'est justement le quoting.
Une seule mauvaise entrée coûte les 25. Une table manquante, une clé qui ne correspond pas au schéma, un élément de plus de 400 KB, un total de plus de 16 MB, une clé de partition de plus de 2048 octets ou une clé de tri de plus de 1024 octets rejettent chacun le batch entier plutôt que l'entrée fautive.

Ce que la commande affiche, rejets compris

Ajoute --return-consumed-capacity TOTAL au bloc ci-dessus et DynamoDB Local 3.3.0 répond :

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

Trois unités pour deux puts et un delete : le batch a acheté un aller-retour réseau, pas une remise. Chaque entrée est facturée comme le PutItem ou le DeleteItem individuel qu'elle représente, arrondi au supérieur à 1 KB.

Relance le delete une deuxième fois, alors que Ella Fitzgerald / Misty a déjà disparu, et DynamoDB Local annonce 2.0 unités pour ce seul DeleteRequest. La référence de BatchWriteItem (consultée le 2026-07-28) indique qu'un delete sur un élément inexistant consomme une unité de capacité d'écriture, et un delete-item isolé contre le même moteur local annonce bien 1.0. Traite les chiffres de capacité en local comme indicatifs. Ce qui reste vrai dans les deux cas, c'est qu'un delete qui ne trouve rien est facturé quand même.

Deux requêtes que le service refuse d'emblée, sur stderr, statut de sortie 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

La seconde mérite qu'on s'y arrête. Elle a été produite par un PutRequest et un DeleteRequest sur la même clé, pas par deux puts. DynamoDB compte toute deuxième opération sur un même élément dans un même batch comme un doublon : « supprimer l'ancienne ligne et écrire la nouvelle » échoue donc en un seul batch, même si les deux entrées n'ont rien à voir l'une avec l'autre.

Assembler ces maps de valeurs entre guillemets simples, c'est là que le temps passe. Le DynamoDB Expression Builder produit des maps typées et copie une commande exécutable, pour qu'un échec soit au moins un vrai échec plutôt qu'un antislash égaré.

Pour charger en masse ou vider des éléments depuis un CSV ou un JSON sans rien échapper, télécharge DynoTable.

Exemples liés

DynamoDB BatchWriteItem en Node.js — la même écriture batch avec l'AWS SDK v3.
Écriture batch DynamoDB en Python — le batch_writer() de boto3 fait la boucle de reprise pour toi.
DynamoDB PutItem avec l'AWS CLI — l'écriture d'un seul élément que celle-ci regroupe.
Les opérations batch dans DynamoDB — limites, échec partiel, et quand le batch est rentable.
"Too many items requested for the BatchWriteItem call" — plus de 25 requêtes put/delete dans un seul batch.
"Provided list of item keys contains duplicates" — deux requêtes touchant la même clé dans un seul batch.

Références

Dernière vérification le 2026-07-28 par rapport à la documentation officielle AWS liée ci-dessus.