DynamoDB Query con la AWS CLI

aws dynamodb query lee una partición, opcionalmente acotada por la clave de ordenación (Query vs Scan cubre cuándo es la decisión correcta, y expresiones de condición de clave lista todos los operadores válidos). Lo que la CLI añade encima es una capa de paginación propia, y es el origen de casi todas las sorpresas de este comando.

Código

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)' \
  --expression-attribute-names '{"#hashKey":"Artist","#rangeKey":"SongTitle"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"},":rangeKeyValue":{"S":"C"}}'

Los alias #hashKey/#rangeKey se resuelven a Artist/SongTitle a través de --expression-attribute-names, que es lo que impide que una palabra reservada rompa el comando. Añade --no-scan-index-forward para orden descendente de clave de ordenación; el ascendente es el predeterminado.

Paginación

Por defecto la CLI pagina automáticamente — sigue el LastEvaluatedKey internamente e imprime el resultado combinado. Para paginar a mano (por ejemplo con conjuntos de resultados grandes), contrólalo con:

aws dynamodb query \
  --table-name 'Music' \
  --key-condition-expression '#hashKey = :hashKeyValue' \
  --expression-attribute-names '{"#hashKey":"Artist"}' \
  --expression-attribute-values '{":hashKeyValue":{"S":"Arturo Sandoval"}}' \
  --page-size 100 \
  --max-items 50
# The output includes a "NextToken"; pass it back with --starting-token to continue.

Explicación

La CLI esconde la paginación, incluso de la cifra de coste. Sembramos una partición con 30 Items de ~60 KB cada uno, unos 1,8 MB y por tanto dos páginas de servicio, y luego ejecutamos la misma consulta de tres formas con --return-consumed-capacity TOTAL:

default (auto-paginate)  Count: 30   CapacityUnits: 132.0   LastEvaluatedKey: null
--no-paginate            Count: 18   CapacityUnits: 132.0   LastEvaluatedKey: {…S017}
--max-items 3            Count: 18   items printed: 3       NextToken: eyJFeGNsdXNpdmVTdGFydEtleSI6…

Paginar a mano mostró el coste real: la página 1 fueron 18 Items a 132,0 unidades, la página 2 fueron 12 Items a 88,0, así que la consulta consumió en realidad 220,0 unidades de lectura. La ejecución con paginación automática hizo las dos llamadas, devolvió los 30 Items e informó de 132,0. La CLI fusiona Items y Count entre páginas pero no ConsumedCapacity, así que el número impreso subestima esta consulta en un 40%. Si dimensionas capacidad a partir de la salida de la CLI, pagina a mano o dimensionarás para una sola página.

--max-items es un límite de impresión. No es un Limit. La tercera ejecución de arriba imprimió tres Items y aun así informó de Count: 18 y ScannedCount: 18, porque la página de servicio que truncó tenía 18 Items y aproximadamente 1 MB. Pagaste por todo. El parámetro de DynamoDB que sí acota la lectura es Limit, y la CLI lo expone como --page-size.

Así que las dos opciones hacen trabajos que no tienen nada que ver. --page-size se convierte en el Limit de la API y cambia lo que lee cada llamada al servicio; --max-items solo decide cuánto del resultado fusionado llega a tu terminal, y emite un NextToken para el resto. Ese token es un blob en base64 de la contabilidad interna de la CLI, no el LastEvaluatedKey de DynamoDB, y vuelve a entrar por --starting-token.

No hay --limit ni --exclusive-start-key. Mira aws dynamodb query help en 2.36.9 y ninguno aparece en la sinopsis: la CLI elimina los dos parámetros de paginación de DynamoDB y sustituye por los tres suyos. Así que el bucle natural, coger el LastEvaluatedKey de una llamada y pasárselo a la siguiente, no tiene ninguna opción a la que pasárselo. El camino de vuelta a la API cruda es --cli-input-json, que toma la petición literal:

--cli-input-json with "Limit": 5 and an "ExclusiveStartKey"
  → Count: 5   CapacityUnits: 37.0   LastEvaluatedKey: {"Artist":…,"SongTitle":"S007"}

Fíjate en que esto además apagó el paginador: la ejecución devolvió una página y un LastEvaluatedKey real incluso sin --no-paginate. Si escribes un bucle de shell sobre una partición grande, --cli-input-json es la forma honesta y --no-paginate la rápida.

--query se ejecuta después de gastar el dinero. La opción global --query es JMESPath aplicado a la respuesta en tu shell. Una expresión JMESPath como Items[?Year > '2010'] parece un filtro y no lo es: cada Item se leyó, se transfirió y se facturó antes de que JMESPath lo viera. --filter-expression al menos evita que los datos se transfieran, pero AWS es explícito en que "is applied after the items have already been read; the process of filtering does not consume any additional read capacity units" (consultado el 2026-07-28). Eso corta por los dos lados, porque significa que el filtro tampoco las reduce. La única forma de leer menos es una condición de clave más estrecha o un índice.

Una página son 1 MB, pidas lo que pidas. "A single Query operation will read up to the maximum number of items set (if using the Limit parameter) or a maximum of 1 MB of data" (consultado el 2026-07-28). Una partición más ancha que eso siempre pagina, que es por lo que la consulta de 30 Items de arriba nunca fue una sola llamada.

Consultar un índice requiere una opción más. --index-name cambia la condición de clave a las claves de ese índice; un índice secundario global además rechaza --consistent-read. Mira Consultar un GSI con la AWS CLI.

Hazlo visualmente

Acertar con la condición de clave, los dos mapas de marcadores y el bucle de paginación en un solo comando es toda la dificultad aquí. El Generador de consultas de DynamoDB gratuito compone la petición, índice y paginación incluidos, y la emite como un comando ejecutable de la CLI.

Para ejecutar consultas contra tus propias tablas — formulario de condición de clave, una cuadrícula que pagina mientras te desplazas, copiar la petición de vuelta como comando de la CLI — descarga DynoTable.

Guías relacionadas

Query vs. Scan — por qué query es el valor por defecto correcto.
Paginación — LastEvaluatedKey, ExclusiveStartKey y por qué Limit no es un tamaño de página.
"Query condition missed key schema element" — la condición de clave nombra el atributo equivocado o se salta la clave de partición.
"Query key condition not supported" — un operador que la condición de clave no puede usar, como contains o una segunda condición sobre la clave de ordenación.

Referencias

Medido el 2026-07-28 con aws-cli/2.36.9 contra DynamoDB Local (amazon/dynamodb-local) en el puerto 9000, sobre una partición de 30 Items de ~60 KB cada uno. Los recuentos, los tokens y las lecturas de capacidad de arriba son salida capturada. DynamoDB Local calcula la capacidad con las reglas de redondeo documentadas; toma las cifras absolutas como una demostración de la forma, y mide tus propias tablas contra el servicio antes de dimensionar.