DynamoDB BatchGetItem con la AWS CLI

aws dynamodb batch-get-item recupera hasta 100 elementos por clave principal en un solo comando. Dos cosas lo separan de query y scan en la línea de comandos: las claves son JSON de DynamoDB anidado que tiene que sobrevivir al entrecomillado del shell, y la CLI no vacía UnprocessedKeys por ti. Los límites y las reglas de resultados parciales están en operaciones por lotes en DynamoDB.

Código

aws dynamodb batch-get-item \
  --request-items '{
    "Music": {
      "Keys": [
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}},
        {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "A Mis Abuelos"}},
        {"Artist": {"S": "Ella Fitzgerald"}, "SongTitle": {"S": "Misty"}}
      ]
    }
  }'

Abreviada, la salida asigna a cada tabla los elementos encontrados más los que hayan quedado pendientes. La ejecución literal completa está más abajo en la página:

{
    "Responses": {
        "Music": [
            {"Artist": {"S": "Arturo Sandoval"}, "SongTitle": {"S": "Cubano Chant"}, ...}
        ]
    },
    "UnprocessedKeys": {}
}

Explicación

La CLI no tiene mecanismo de paginación para este comando. aws dynamodb query help lista --starting-token, --max-items y --page-size; aws dynamodb batch-get-item help no lista ninguno de los tres. UnprocessedKeys no es un token de paginación y la CLI trata la llamada como una sola, así que vaciarlo es tu bucle de shell, no un flag.
El mapa de pendientes ya viene en el formato de entrada. Un UnprocessedKeys no vacío puede volver a pasarse tal cual como --request-items sin remodelarlo, que es lo que hace tolerable un bucle while en bash. Espera entre intentos; una reejecución inmediata golpea la misma partición limitada.
ProjectionExpression y ConsistentRead van dentro del objeto de cada tabla, junto a "Keys". Ponerlos en el nivel superior de --request-items es el error de forma más habitual aquí.
Guarda el mapa en un archivo. --request-items file://keys.json evita por completo el entrecomillado del shell, y es la única opción sensata en cuanto pasas de un puñado de claves. También es la forma de alcanzar el techo de 100 claves sin darte cuenta.

Qué imprime realmente el comando

El bloque de arriba, ejecutado literalmente contra DynamoDB Local 3.3.0 con las tres canciones presentes (aws-cli/2.36.9):

{
    "Responses": {
        "Music": [
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "A Mis Abuelos"}
            },
            {
                "Artist": {"S": "Ella Fitzgerald"},
                "AlbumTitle": {"S": "Ella in Berlin"},
                "Year": {"N": "1960"},
                "SongTitle": {"S": "Misty"}
            },
            {
                "Artist": {"S": "Arturo Sandoval"},
                "AlbumTitle": {"S": "Danzon"},
                "Year": {"N": "1994"},
                "SongTitle": {"S": "Cubano Chant"}
            }
        ]
    },
    "UnprocessedKeys": {}
}

(Cada mapa de atributos plegado en una sola línea; todo lo demás es tal cual se imprimió.) El comando pidió Cubano Chant primero y lo recibió último. Nada en la respuesta es posicional, así que una expresión jq que indexe .Responses.Music[0] está leyendo el elemento que al servicio le apeteciera devolver primero. Filtra por los atributos de clave en su lugar.

Dos peticiones las rechaza de plano, impresas en stderr con estado de salida 254:

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

El prefijo aws: [ERROR]: viene del wrapper de la CLI v2; el texto que le sigue es el mensaje del propio servicio. Un bucle de reintentos que trate cualquier salida distinta de cero como una limitación girará para siempre con cualquiera de los dos, así que ramifica según el mensaje antes de aplicar backoff.

Escribir a mano ese JSON anidado entre comillas simples es de donde vienen la mayoría de los errores. El DynamoDB Expression Builder monta mapas de clave tipados y copia un comando listo para ejecutar, lo que al menos quita el entrecomillado de la lista de sospechosos.

Para leer de vuelta un conjunto de claves y ver los elementos sin pasar por el JSON, descarga DynoTable.

Ejemplos relacionados

DynamoDB BatchGetItem en Node.js — la misma lectura por lotes con AWS SDK v3.
DynamoDB BatchGetItem en Python — la misma lectura por lotes con boto3.
DynamoDB GetItem con la AWS CLI — la lectura de un solo elemento que esto agrupa.
Operaciones por lotes en DynamoDB — límites, fallos parciales y cuándo compensa agrupar.
"Too many items requested for the BatchGetItem call" — más de 100 claves en una sola petición.
"Provided list of item keys contains duplicates" — la misma clave dos veces en un lote.

Referencias

Verificado por última vez el 2026-07-28 contra la documentación oficial de AWS enlazada arriba.