DynamoDB Scan con la AWS CLI

aws dynamodb scan pagina automáticamente, lo cual es cómodo y hace que el único número con el que juzgarías el daño esté equivocado por defecto. Mira Query vs. Scan para saber cuándo evitar la operación por completo.

Código

aws dynamodb scan \
  --table-name 'Music' \
  --filter-expression '#filter0 >= :filterValue0' \
  --expression-attribute-names '{"#filter0":"Year"}' \
  --expression-attribute-values '{":filterValue0":{"N":"2010"}}'

--return-consumed-capacity informa de una página, no del escaneo

El juego de datos son 600 canciones de aproximadamente 3,9 KB cada una, de las cuales coinciden 8. Añade --return-consumed-capacity TOTAL a ese comando y la CLI imprime:

{ "Count": 8, "ScannedCount": 600, "CU": 128.5 }

El escaneo costó en realidad 284,5 unidades de lectura repartidas en tres páginas. Count y ScannedCount se sumaron a lo largo de las tres; ConsumedCapacity se tomó de la primera y el resto se descartó. Eso no es tanto un bug como una regla declarada: la configuración del paginador de DynamoDB en botocore lista Count y ScannedCount como claves de resultado y ConsumedCapacity como clave no agregable.

La señal es que la cifra se mueve cuando el trabajo no. Misma tabla, mismos 600 Items leídos, una opción de más:

--page-size 50  ->  { "Count": 8, "ScannedCount": 600, "CU": 24.0 }

Si dimensionas una tabla a partir de un scan desde la CLI, suma tú las páginas con --page-size más --starting-token, o lee la capacidad de CloudWatch.

--max-items no detiene el escaneo

--max-items 3 se lee como una muestra barata. No lo es:

--max-items 3  ->  { "Count": 8, "ScannedCount": 600 }

La CLI siguió pidiendo páginas hasta tener suficientes coincidencias, lo que con un filtro selectivo significó la tabla entera, y después truncó la lista impresa. Su propio token de reanudación lo dice en voz alta:

{"ExclusiveStartKey": {"Artist": {"S": "Arturo Sandoval"},
 "SongTitle": {"S": "Cubano Chant 0541"}}, "boto_truncate_amount": 3}

boto_truncate_amount es un contador del lado del cliente. Para acotar lo que lee DynamoDB, usa --page-size, que establece el Limit de la API en cada petición subyacente, y reanuda con --starting-token:

aws dynamodb scan \
  --table-name 'Music' \
  --page-size 500 \
  --max-items 100 \
  --starting-token "$NEXT_TOKEN"

Medido el 2026-07-28 contra DynamoDB Local (amazon/dynamodb-local) con aws-cli/2.36.9. El JSON de arriba es salida propia de la CLI, remodelada con --query por cuestión de ancho.

Explicación

• --filter-expression se ejecuta después de la lectura, así que reduce la salida y no la factura. #filter0 da alias a Year a través de --expression-attribute-names porque Year es una palabra reservada.
• --expression-attribute-values quiere el número entrecomillado dos veces: comillas de shell alrededor del JSON, y el valor como cadena JSON. Quitar las comillas interiores no llega nunca a DynamoDB — la CLI lo rechaza localmente con Invalid type for parameter ExpressionAttributeValues.:v.N, value: 2010, type: <class 'int'>, valid types: <class 'str'>.
• --page-size es la opción que cambia la llamada a la API. Se convierte en el Limit de cada petición subyacente, limitando los Items evaluados por página. El resto de la familia de paginación (--max-items, --starting-token) es la CLI gestionando su propia salida.
• El escaneo paralelo necesita --segment N --total-segments M por trabajador, y cada trabajador mantiene su propio --starting-token. Compra tiempo de reloj, no capacidad.

Hazlo visualmente

El Generador de expresiones de DynamoDB emite el filtro y los dos mapas JSON ya escapados para el shell, lo que elimina la capa de entrecomillado que hace que las expresiones de la CLI fallen antes de que DynamoDB llegue a verlas.

Para explorar tablas en una GUI, con cuadrículas filtradas y paginadas, descarga DynoTable en lugar de escanear a ciegas desde el terminal.

Guías relacionadas

• Query vs. Scan — cuándo (rara vez) se justifica un scan.
• ¿Por qué mi Scan de DynamoDB es lento y caro? — el modelo de coste y cómo evitarlo.
• DynamoDB ProvisionedThroughputExceededException — lo que un escaneo de tabla completa le hace a la capacidad de una tabla aprovisionada.
• DynamoDB ThrottlingException — la otra limitación, y cómo la gestiona el backoff exponencial.

Referencias

• Scan — Amazon DynamoDB API Reference
• scan — AWS CLI Command Reference
• Using the pagination options in the AWS CLI — AWS CLI User Guide
• Scanning tables — Amazon DynamoDB Developer Guide