Query DynamoDB con la AWS CLI

aws dynamodb query legge una partizione, opzionalmente ristretta dalla chiave di ordinamento (Query vs Scan spiega quando è la scelta giusta, e le key condition expression elencano ogni operatore ammesso). Quello che la CLI aggiunge sopra è un suo livello di paginazione, ed è l'origine della maggior parte delle sorprese di questo comando.

Codice

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

Gli alias #hashKey/#rangeKey si risolvono in Artist/SongTitle tramite --expression-attribute-names, ed è questo che impedisce a una parola riservata di rompere il comando. Aggiungi --no-scan-index-forward per l'ordine decrescente della chiave di ordinamento; il crescente è quello predefinito.

Paginazione

Per impostazione predefinita la CLI pagina automaticamente — segue internamente LastEvaluatedKey e stampa il risultato combinato. Per paginare a mano (ad esempio su insiemi di risultati grandi), controllala 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.

Spiegazione

La CLI nasconde la paginazione, anche alla cifra del costo. Abbiamo seminato una partizione con 30 Item di ~60 KB ciascuno, circa 1,8 MB e quindi due pagine di servizio, poi abbiamo eseguito la stessa query in tre modi 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…

Paginare a mano ha mostrato il costo reale: la pagina 1 erano 18 Item a 132,0 unità, la pagina 2 erano 12 Item a 88,0, quindi la query ha davvero consumato 220,0 unità di lettura. L'esecuzione con paginazione automatica ha fatto entrambe le chiamate, ha restituito tutti e 30 gli Item e ha riportato 132,0. La CLI unisce Items e Count tra le pagine ma non ConsumedCapacity, quindi il numero stampato sottostima questa query del 40%. Se stai dimensionando la capacità dall'output della CLI, pagina a mano oppure dimensionerai per una sola pagina.

--max-items è un limite di stampa. Non è un Limit. La terza esecuzione qui sopra ha stampato tre Item e ha comunque riportato Count: 18 e ScannedCount: 18, perché la pagina di servizio che ha troncato era di 18 Item e circa 1 MB. Li hai pagati tutti. Il parametro DynamoDB che limita davvero la lettura è Limit, e la CLI lo espone come --page-size.

Quindi i due flag fanno lavori scorrelati. --page-size diventa il Limit dell'API e cambia ciò che legge ogni chiamata al servizio; --max-items decide solo quanta parte del risultato unito raggiunge il tuo terminale, ed emette un NextToken per il resto. Quel token è un blob base64 della contabilità interna della CLI, non il LastEvaluatedKey di DynamoDB, e rientra tramite --starting-token.

Non esistono né --limit né --exclusive-start-key. Controlla aws dynamodb query help sulla 2.36.9 e nessuno dei due compare nella sinossi: la CLI rimuove entrambi i parametri di paginazione di DynamoDB e li sostituisce con i suoi tre. Quindi il loop naturale, prendere LastEvaluatedKey da una chiamata e passarlo alla successiva, non ha alcun flag a cui passarlo. La via di ritorno all'API grezza è --cli-input-json, che prende la richiesta alla lettera:

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

Nota che questo ha anche spento il paginatore: l'esecuzione ha restituito una pagina e un vero LastEvaluatedKey anche senza --no-paginate. Se stai scrivendo un loop di shell su una partizione grande, --cli-input-json è la forma onesta e --no-paginate quella rapida.

--query gira dopo che i soldi sono spesi. Il flag globale --query è JMESPath applicato alla risposta nella tua shell. Un'espressione JMESPath come Items[?Year > '2010'] sembra un filtro e non lo è: ogni item è stato letto, trasferito e fatturato prima che JMESPath lo vedesse. --filter-expression almeno impedisce che i dati vengano trasferiti, ma AWS è esplicita nel dire che "is applied after the items have already been read; the process of filtering does not consume any additional read capacity units" (consultato il 2026-07-28). Questo taglia da entrambi i lati, perché significa che nemmeno il filtro le riduce. L'unico modo di leggere di meno è una condizione di chiave più stretta o un indice.

Una pagina è 1 MB, qualunque cosa tu abbia chiesto. "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" (consultato il 2026-07-28). Una partizione più larga di così pagina sempre, ed è per questo che la query da 30 Item qui sopra non è mai stata una sola chiamata.

Interrogare un indice richiede un flag in più. --index-name sposta la condizione di chiave sulle chiavi di quell'indice; un indice secondario globale rifiuta inoltre --consistent-read. Vedi Interrogare un GSI con la AWS CLI.

Fallo visivamente

Azzeccare la condizione di chiave, le due mappe di segnaposto e il loop di paginazione in un solo comando è tutta la difficoltà qui. Il Generatore di query DynamoDB gratuito compone la richiesta, indice e paginazione inclusi, e la emette come comando CLI eseguibile.

Per eseguire query sulle tue tabelle — form per la condizione di chiave, una griglia che pagina mentre scorri, e copiare la richiesta come comando CLI — scarica DynoTable.

Guide correlate

Query vs. Scan — perché query è il default giusto.
Paginazione — LastEvaluatedKey, ExclusiveStartKey e perché Limit non è una dimensione di pagina.
"Query condition missed key schema element" — la condizione di chiave nomina l'attributo sbagliato o salta la chiave di partizione.
"Query key condition not supported" — un operatore che la condizione di chiave non può usare, come contains o una seconda condizione sulla chiave di ordinamento.

Riferimenti

Misurato il 2026-07-28 con aws-cli/2.36.9 contro DynamoDB Local (amazon/dynamodb-local) sulla porta 9000, su una partizione di 30 Item da ~60 KB ciascuno. I conteggi, i token e le letture di capacità qui sopra sono output catturato. DynamoDB Local calcola la capacità con le regole di arrotondamento documentate; tratta le cifre assolute come una dimostrazione della forma, e misura le tue tabelle contro il servizio prima di dimensionare.