AWS CLI ile DynamoDB BatchWriteItem

aws dynamodb batch-write-item, tek bir komutta 25'e kadar öğeyi yazar ya da siler. Kabuktan bakıldığında SDK'ların yumuşattığı iki keskin kenarı vardır: her değer, doğru tırnaklamanız gereken DynamoDB JSON'udur ve CLI'nin UnprocessedItems'i boşaltmak için hiçbir mekanizması yoktur. Sınırlar ve kısmi başarısızlık modeli DynamoDB'de toplu işlemler sayfasındadır.

Kod

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

DynamoDB Local 3.3.0'a karşı çalıştırıldığında tam olarak şunu yazdırır:

{
    "UnprocessedItems": {}
}

Açıklama

Boş bir artakalan eşlemesi, elinize geçen tek başarı sinyalidir. Komut UnprocessedItems yazdırır ve başka bir şey yazmaz; dolayısıyla yalnızca çıkış durumunu kontrol eden bir betik, yarısı yazılmış bir toplu işleme başarılı der. Eşlemeyi ayrıştırın; kontrolün tamamı jq -e '.UnprocessedItems | length == 0''dır.
Onu boşaltacak bir bayrak yoktur. aws dynamodb query help, --starting-token, --max-items ve --page-size sunar. aws dynamodb batch-write-item help bunların hiçbirini sunmaz, çünkü UnprocessedItems bir sayfalama imleci değildir. Onu geri beslemek, sleep içeren bir kabuk döngüsüdür ve zaten --request-items biçimindedir.
--condition-expression ve --return-values burada kabul edilmez ve bu CLI'nin değil API'nin kuralıdır: koşullar tek tek put ve delete isteklerine iliştirilemez. Her PutRequest saklanan öğenin tamamını değiştirir; dolayısıyla kısmi bir yükten kurulan bir toplu işlem, dışarıda bıraktığı öznitelikleri siler.
Satır içi JSON değil, file:// kullanın. --request-items file://writes.json, yanlış gidebilecek şeyler listesinden kabuk tırnaklamasını çıkarır; bu da önemlidir, çünkü bu komutta ters giden şeylerin çoğu tırnaklamadır.
Tek bir kötü girdi 25'inin de bedelini ödetir. Eksik bir tablo, şemaya uymayan bir anahtar, 400 KB'ı aşan bir öğe, 16 MB'ı aşan toplam, 2048 baytı aşan bir bölüm anahtarı ya da 1024 baytı aşan bir sıralama anahtarı — her biri sorunlu girdiyi değil toplu işlemin tamamını reddeder.

Komutun ne yazdırdığı, reddedilenler dahil

Yukarıdaki bloğa --return-consumed-capacity TOTAL ekleyin; DynamoDB Local 3.3.0 şu yanıtı verir:

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

İki put ve bir delete için üç birim: toplu işlem bir gidiş-dönüş satın aldı, indirim değil. Her girdi, temsil ettiği tekil PutItem ya da DeleteItem olarak, 1 KB'a yuvarlanarak faturalanır.

Delete'i, Ella Fitzgerald / Misty çoktan gitmişken ikinci kez çalıştırın; DynamoDB Local o tek DeleteRequest için 2,0 birim bildirir. BatchWriteItem referansı (2026-07-28 tarihinde alındı), var olmayan bir öğe üzerindeki bir silmenin bir yazma kapasite birimi tükettiğini söyler ve aynı yerel motora karşı tek başına bir delete-item gerçekten de 1,0 bildirir. Yerel kapasite sayılarını yönlendirici olarak görün. Her iki durumda da ayakta kalan nokta şudur: hiçbir şey bulamayan bir silme yine de faturalanır.

Hizmetin doğrudan reddettiği iki istek, stderr'de, çıkış durumu 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

İkincisine dikkatle bakmakta fayda var. Onu üreten şey, iki put değil, aynı anahtar üzerindeki bir PutRequest ve bir DeleteRequest'ti. DynamoDB, tek bir toplu işlemde tek bir öğe üzerindeki ikinci işlemi yinelenen sayar; dolayısıyla "eski satırı sil ve yenisini yaz" tek bir toplu işlem olarak başarısız olur — iki girdi birbirine hiç benzemese bile.

O değer eşlemelerini tek tırnak içinde kurmak zamanın gittiği yerdir. DynamoDB Expression Builder, tipli eşlemeler üretir ve çalıştırılabilir bir komut kopyalar; böylece bir başarısızlık en azından kaçak bir ters eğik çizgi değil, gerçek bir başarısızlık olur.

Öğeleri CSV ya da JSON'dan hiçbirini kaçışlamadan toplu yüklemek ya da temizlemek için DynoTable'ı indirin.

İlgili örnekler

Node.js'te DynamoDB BatchWriteItem — AWS SDK v3 ile aynı toplu yazma.
Python'da DynamoDB toplu yazma — boto3'ün batch_writer()'ı yeniden deneme döngüsünü sizin için yapar.
AWS CLI ile DynamoDB PutItem — bunun topladığı tek öğelik yazma.
DynamoDB'de toplu işlemler — sınırlar, kısmi başarısızlık ve toplu işlem ne zaman kazandırır.
"Too many items requested for the BatchWriteItem call" — tek toplu işlemde 25'ten fazla put/delete isteği.
"Provided list of item keys contains duplicates" — tek toplu işlemde aynı anahtara dokunan iki istek.

Kaynaklar

En son 2026-07-28 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.