Query de DynamoDB en Node.js (SDK de AWS v3)

Un Query completo en el SDK de AWS v3 es el do/while de abajo, no el único client.send() que muestran la mayoría de los fragmentos: una página tiene un tope de 1 MB, y el resto de la partición solo llega si devuelves LastEvaluatedKey. Mira Query vs. Scan para saber cuándo Query es siquiera la lectura correcta.

Código

import {DynamoDBClient, QueryCommand} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({region: 'us-east-1'});

const items = [];
let lastEvaluatedKey;

do {
  const response = await client.send(
    new QueryCommand({
      TableName: 'Music',
      KeyConditionExpression: '#hashKey = :hashKeyValue AND begins_with(#rangeKey, :rangeKeyValue)',
      ExpressionAttributeNames: {
        '#hashKey': 'Artist',
        '#rangeKey': 'SongTitle'
      },
      ExpressionAttributeValues: {
        ':hashKeyValue': {S: 'Arturo Sandoval'},
        ':rangeKeyValue': {S: 'C'}
      },
      ExclusiveStartKey: lastEvaluatedKey
    })
  );

  items.push(...(response.Items ?? []));
  lastEvaluatedKey = response.LastEvaluatedKey;
} while (lastEvaluatedKey);

console.log(`Found ${items.length} items`);

Qué hace el bucle en realidad

Contra un juego de prueba de 600 canciones, cada una de ~3,9 KB y todas bajo Artist = "Arturo Sandoval", el bucle de arriba envía tres peticiones:

Ida y vuelta	`Count`	`ScannedCount`	Unidades de lectura	`LastEvaluatedKey`
1	271	271	128,5	presente
2	271	271	128,5	presente
3	58	58	27,5	ausente

Nadie configuró 271. Ahí es donde se agotó 1 MB, así que el límite de página se mueve cada vez que lo hace el tamaño de tus Items. Una partición que hoy pagina una vez pagina dos después de que añadas un atributo, y el código que lee response.Items de un solo send() devuelve en silencio 271 de 600 canciones sin error alguno.

Ahora añade Limit: 10 y una FilterExpression sobre Year a la misma consulta:

Count: 0   ScannedCount: 10   ConsumedCapacity: 5   LastEvaluatedKey: set

Diez Items evaluados, cero devueltos, y la petición aun así costó capacidad de lectura. Limit acota lo que DynamoDB lee, y el filtro corre después, así que un Limit elegido con la idea de «dame 10 resultados» te da entre 0 y 10.

Medido el 2026-07-28 contra DynamoDB Local (amazon/dynamodb-local) con @aws-sdk/client-dynamodb 3.1095.0 en node v24.18.0. Los conteos y la capacidad son los propios campos de respuesta del motor.

Explicación

ExclusiveStartKey: lastEvaluatedKey es undefined en la primera pasada, y eso es deliberado: el serializador de v3 descarta los miembros undefined, así que el mismo objeto literal sirve para la primera petición y para todas las siguientes. Sustituirlo por {} — la suposición obvia para «empieza por el principio» — falla con ValidationException: The provided starting key is invalid.
@aws-sdk/client-dynamodb nunca hace el marshalling por ti. Los valores entran como {S: 'Arturo Sandoval'} y los Items vuelven igual. Ese es el precio de no arrastrar el DocumentClient; si prefieres escribir objetos JS planos, @aws-sdk/lib-dynamodb es el envoltorio al que recurrir.
Los números sobreviven al viaje de ida y vuelta como cadenas. Deshacer el marshalling de {N: '9007199254740993'} con unmarshall de @aws-sdk/util-dynamodb devuelve un bigint de JS, no un number con pérdida; pasa {wrapNumbers: true} y obtienes {value: '9007199254740993'} en su lugar. En cualquier caso, no le apliques Number() a un N de DynamoDB cuyo tamaño no hayas comprobado.
KeyConditionExpression admite una igualdad sobre la clave de partición más, como mucho, una condición de clave de ordenación (=, <, <=, >, >=, BETWEEN, begins_with). Cualquier otra cosa va en una FilterExpression, que corre después de la lectura.
ScanIndexForward: false invierte el orden de la clave de ordenación; ascendente es lo predeterminado. IndexName cambia el mismo comando a un índice secundario.

Hazlo visualmente

El generador de consultas de DynamoDB emite esta forma entera — condición de clave, mapas de nombres y valores, y el bucle de LastEvaluatedKey — como un programa ejecutable del SDK v3, para que la paginación no sea la parte que se te olvida.

Para ejecutar consultas contra tablas reales en una GUI, con un formulario de condición de clave y una cuadrícula de resultados paginada, descarga DynoTable.

Guías relacionadas

Query vs. Scan — por qué Query es el valor predeterminado correcto.
Expresiones de condición de clave — todos los operadores legales de clave de partición y de ordenación.
«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 de clave de ordenación.