Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Utilizzo di elementi e attributi
In Amazon DynamoDB, un elemento è una raccolta di attributi. Ogni attributo ha un nome e un valore. Il valore di un attributo può essere un tipo scalare, un set o un tipo di documento. Per ulteriori informazioni, consulta Amazon DynamoDB: come funziona.
DynamoDB fornisce quattro operazioni per le funzionalità di base di creazione, lettura, aggiornamento ed eliminazione CRUD (). Tutte queste operazioni sono atomiche.
-
PutItem
: crea un elemento. -
GetItem
: legge un elemento. -
UpdateItem
: aggiorna un elemento. -
DeleteItem
: elimina un elemento.
Ognuna di queste operazioni richiede di specificare la chiave primaria dell'elemento da usare. Per leggere, ad esempio, un elemento con GetItem
, devi specificare la chiave di partizione e la chiave di ordinamento (se applicabile) per l'elemento.
Oltre alle quattro CRUD operazioni di base, DynamoDB fornisce anche quanto segue:
-
BatchGetItem
: legge fino a 100 elementi da una o più tabelle. -
BatchWriteItem
: crea o elimina fino a 25 elementi in una o più tabelle.
Queste operazioni in batch combinano più CRUD operazioni in un'unica richiesta. Le operazioni batch, inoltre, leggono e scrivono gli elementi in parallelo, per ridurre al minimo la latenza delle risposte.
In questa sezione viene descritto come usare queste operazioni e sono inclusi argomenti correlati, come gli aggiornamenti condizionali e i contatori atomici. Questa sezione include anche un codice di esempio che utilizza il AWS SDKs.
Argomenti
- Lettura di un elemento
- Scrittura di un elemento
- Valori restituiti
- Operazioni batch
- Contatori atomici
- Scritture condizionali
- Utilizzo di espressioni in DynamoDB
- Tempo di vita (TTL)
- Interrogazione di tabelle in DynamoDB
- Tabelle di scansione in DynamoDB
- PartiQL: un linguaggio di query compatibile con SQL per Amazon DynamoDB
- Utilizzo degli elementi: Java
- Uso di elementi: .NET
Lettura di un elemento
Per leggere un elemento da una tabella DynamoDB, utilizza l'operazione GetItem
. Devi fornire il nome della tabella e la chiave primaria dell'elemento desiderato.
Esempio
L' AWS CLI esempio seguente mostra come leggere un elemento dalla ProductCatalog
tabella.
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}'
Nota
Con GetItem
, devi specificare l'intera chiave primaria, non una parte di essa. Se, ad esempio, una tabella ha una chiave primaria composita (chiave di partizione e chiave di ordinamento), devi fornire un valore per la chiave di partizione e uno per la chiave di ordinamento.
Una richiesta GetItem
esegue una lettura consistente finale per impostazione predefinita. Puoi usare il parametro ConsistentRead
per richiedere invece una lettura consistente assoluta. (Ciò consuma unità di capacità di lettura aggiuntive, ma restituisce la maggior parte delle up-to-date versioni dell'articolo.)
GetItem
restituisce tutti gli attributi dell'elemento. Puoi usare un'espressione di proiezione per restituire solo alcuni degli attributi. Per ulteriori informazioni, consulta Espressioni di proiezione.
Per restituire il numero di unità di capacità di lettura utilizzate da GetItem
, imposta il parametro ReturnConsumedCapacity
su TOTAL
.
Esempio
L'esempio seguente AWS Command Line Interface (AWS CLI) mostra alcuni GetItem
parametri opzionali.
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL
Scrittura di un elemento
Per creare, aggiornare o eliminare un elemento in una tabella DynamoDB, utilizza una delle operazioni seguenti:
-
PutItem
-
UpdateItem
-
DeleteItem
Per ognuna di queste operazioni, devi specificare l'intera chiave primaria e non solo una parte di essa. Se, ad esempio, una tabella ha una chiave primaria composita (chiave di partizione e chiave di ordinamento), devi fornire un valore per la chiave di partizione e uno per la chiave di ordinamento.
Per restituire il numero di unità di capacità di scrittura utilizzate da queste operazioni, imposta il parametro ReturnConsumedCapacity
su uno dei valori seguenti:
-
TOTAL
: restituisce il numero totale di unità di capacità di scrittura totali consumate. -
INDEXES
: restituisce il numero totale di unità di capacità di scrittura consumate, con i subtotali per la tabella e gli eventuali indici secondari interessati dall'operazione. -
NONE
: non vengono restituiti dettagli sulla capacità di scrittura. Questa è l'impostazione predefinita.
PutItem
PutItem
crea un nuovo elemento. Se nella tabella esiste già un elemento con la stessa chiave, il nuovo elemento sostituisce quello esistente.
Esempio
Scrivi un nuovo elemento nella tabella Thread
. La chiave primaria per Thread
è costituita da ForumName
(chiave di partizione) e Subject
(chiave di ordinamento).
aws dynamodb put-item \ --table-name Thread \ --item file://item.json
Gli argomenti per --item
sono memorizzati nel file item.json
:
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} }
UpdateItem
Se non esiste un elemento con la chiave specificata, UpdateItem
crea un nuovo elemento. In caso contrario, modifica gli attributi di un elemento esistente.
Puoi usare un'espressione di aggiornamento per specificare gli attributi che desideri modificare e i loro nuovi valori. Per ulteriori informazioni, consulta Espressioni di aggiornamento.
Nell'espressione di aggiornamento usi i valori degli attributi di espressione come segnaposto per i valori effettivi. Per ulteriori informazioni, consulta Valori degli attributi dell'espressione.
Esempio
Modifica i diversi attributi nell'elemento Thread
. Il parametro ReturnValues
facoltativo mostra l'elemento dopo l'aggiornamento. Per ulteriori informazioni, consulta Valori restituiti.
aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW
Gli argomenti per --key
sono memorizzati nel file key.json
:
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} }
Gli argomenti per --expression-attribute-values
sono memorizzati nel file expression-attribute-values.json
:
{ ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} }
DeleteItem
DeleteItem
elimina l'elemento con la chiave specificata.
Esempio
L' AWS CLI esempio seguente mostra come eliminare l'Thread
elemento.
aws dynamodb delete-item \ --table-name Thread \ --key file://key.json
Valori restituiti
In alcuni casi potrebbe essere necessario che DynamoDB restituisca determinati valori degli attributi nello stato in cui si trovano prima o dopo la modifica. Le operazioni PutItem
, UpdateItem
e DeleteItem
hanno un parametro ReturnValues
che è possibile usare per restituire i valori degli attributi prima o dopo la modifica.
Il valore predefinito per ReturnValues
è NONE
, il che significa che DynamoDB non restituisce informazioni sugli attributi che sono stati modificati.
Di seguito sono riportate le altre impostazioni valide perReturnValues
, organizzate per operazione API DynamoDB.
PutItem
-
ReturnValues
:ALL_OLD
-
Se sovrascrivi un elemento esistente,
ALL_OLD
restituisce l'intero elemento precedente alla sovrascrittura. -
Se scrivi un elemento che non esiste,
ALL_OLD
non ha alcun effetto.
-
UpdateItem
L'uso più comune di UpdateItem
è quello di aggiornare un elemento esistente. UpdateItem
esegue tuttavia un'operazione upsert, ovvero crea automaticamente l'elemento, se non esiste già.
-
ReturnValues
:ALL_OLD
-
Se aggiorni un elemento esistente,
ALL_OLD
restituisce l'intero elemento precedente all'aggiornamento. -
Se aggiorni un item che non esiste (upsert),
ALL_OLD
non ha alcun effetto.
-
-
ReturnValues
:ALL_NEW
-
Se aggiorni un elemento esistente,
ALL_NEW
restituisce l'intero elemento successivo all'aggiornamento. -
Se aggiorni un elemento che non esiste (upsert),
ALL_NEW
restituisce l'intero elemento.
-
-
ReturnValues
:UPDATED_OLD
-
Se aggiorni un elemento esistente,
UPDATED_OLD
restituisce solo gli attributi aggiornati, nello stato precedente all'aggiornamento. -
Se aggiorni un item che non esiste (upsert),
UPDATED_OLD
non ha alcun effetto.
-
-
ReturnValues
:UPDATED_NEW
-
Se aggiorni un elemento esistente,
UPDATED_NEW
restituisce solo gli attributi interessati, nello stato successivo all'aggiornamento. -
Se aggiorni un elemento che non esiste (upsert),
UPDATED_NEW
restituisce solo gli attributi aggiornati, nello stato successivo all'aggiornamento.
-
DeleteItem
-
ReturnValues
:ALL_OLD
-
Se elimini un elemento esistente,
ALL_OLD
restituisce l'intero elemento precedente all'eliminazione. -
Se elimini un elemento che non esiste,
ALL_OLD
non restituisce alcun dato.
-
Operazioni batch
Per le applicazioni che devono leggere o scrivere più elementi, DynamoDB fornisce le operazioni BatchGetItem
e BatchWriteItem
. L'uso di queste operazioni permette di ridurre il numero di viaggi di andata e ritorno di rete dall'applicazione a DynamoDB. Inoltre, DynamoDB esegue le singole operazioni di lettura o scrittura in parallelo. Le applicazioni possono ottenere un vantaggio da questo parallelismo, senza dover gestire la concorrenza o il threading.
Le operazioni batch sono essenzialmente una combinazione di più richieste di lettura o di scrittura. Se, ad esempio, una richiesta BatchGetItem
contiene cinque elementi, DynamoDB esegue cinque operazioni GetItem
per conto tuo. Analogamente, se una richiesta BatchWriteItem
contiene due richieste put e quattro richieste delete, DynamoDB esegue due richieste PutItem
e quattro richieste DeleteItem
.
In generale, un'operazione batch non ha esito negativo a meno che tutte le richieste nel batch non abbiano esito negativo. Supponi, ad esempio, di eseguire un'operazione BatchGetItem
, ma una delle singole richieste GetItem
nel batch ha esito negativo. In questo caso, BatchGetItem
restituisce le chiavi e i dati della richiesta GetItem
che ha avuto esito negativo. Le altre richieste GetItem
nel batch non sono interessate.
BatchGetItem
Una singola operazione BatchGetItem
può contenere fino a 100 singole richieste GetItem
e può recuperare fino a 16 MB di dati. Un'operazione BatchGetItem
può inoltre recuperare elementi da più tabelle.
Esempio
Recupera due elementi dalla tabella Thread
usando un'espressione di proiezione per restituire solo alcuni degli attributi.
aws dynamodb batch-get-item \ --request-items file://request-items.json
Gli argomenti per --request-items
sono memorizzati nel file request-items.json
:
{ "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } }
BatchWriteItem
L'operazione BatchWriteItem
può contenere fino a 25 singole richieste PutItem
e DeleteItem
e può scrivere fino a 16 MB di dati. La dimensione massima di un singolo elemento è 400 KB. Un'operazione BatchWriteItem
può inoltre inserire o eliminare elementi in più tabelle.
Nota
BatchWriteItem
non supporta le richieste UpdateItem
.
Esempio
Scrivi due elementi nella tabella ProductCatalog
.
aws dynamodb batch-write-item \ --request-items file://request-items.json
Gli argomenti per --request-items
sono memorizzati nel file request-items.json
:
{ "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] }
Contatori atomici
È possibile utilizzare l'operazione UpdateItem
per implementare un contatore atomico: un attributo numerico che viene incrementato, incondizionatamente, senza interferire con altre richieste di scrittura. Tutte le richieste di scrittura vengono applicate in base all'ordine di ricezione. Con un contatore atomico, gli aggiornamenti non sono idempotenti. In altre parole, il valore numerico aumenta o diminuisce a ogni chiamata di UpdateItem
. Se il valore di incremento utilizzato per aggiornare il contatore atomico è positivo, può causare un conteggio in eccesso. Se il valore dell'incremento è negativo, può causare un conteggio in difetto.
Puoi usare un contatore atomico per tenere traccia del numero di visitatori di un sito Web. In questo caso, l'applicazione incrementa un valore numerico, indipendentemente dal valore corrente. Se un'operazione UpdateItem
non va a buon fine, l'applicazione può semplicemente provare a ripetere l'operazione. Ciò rischierebbe di aggiornare il contatore due volte, anche se probabilmente un lieve discostamento in eccesso o in difetto nel numero di visitatori del sito Web può essere tollerato.
Un contatore atomico non è appropriato quando un conteggio maggiore o minore di quello effettivo non può essere tollerato (ad esempio, in un'applicazione bancaria). In questo caso, è preferibile usare un aggiornamento condizionale al posto di un contatore atomico.
Per ulteriori informazioni, consulta Incremento e decremento di attributi numerici.
Esempio
L' AWS CLI esempio seguente incrementa il valore Price
di un prodotto di 5. In questo esempio, l'esistenza dell'articolo era nota prima dell'aggiornamento del contatore. Poiché UpdateItem
non è idempotente, il valore di Price
aumenta ogni volta che si esegue il codice.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW
Scritture condizionali
Per impostazione predefinita, le operazioni di scrittura di DynamoDB (PutItem
, UpdateItem
, DeleteItem
) sono non condizionali: ogni operazione sovrascrive un elemento esistente con la chiave primaria specificata.
Facoltativamente, per queste operazioni DynamoDB supporta le scritture condizionali. Una scrittura condizionale ha esito positivo solo se gli attributi dell'elemento soddisfano una o più condizioni. In caso contrario, restituisce un errore.
Le scritture condizionali confrontano le relative condizioni con la versione aggiornata più recente dell'elemento. Nota che se l'elemento non esisteva in precedenza o se l'ultima operazione riuscita su quell'elemento è stata un'eliminazione, la scrittura condizionale non troverà alcun elemento precedente.
Le operazioni di scrittura condizionali sono utili in molte situazioni. Potrebbe ad esempio essere necessario fare in modo che un'operazione PutItem
abbia esito positivo solo se non è già presente un elemento con la stessa chiave primaria. In alternativa, si potrebbe impedire a un'operazione UpdateItem
di modificare un elemento se uno o più dei relativi attributi ha un determinato valore.
Le scritture condizionali sono utili nei casi in cui più utenti tentano di modificare lo stesso elemento. Si consideri il diagramma seguente, in cui due utenti (Alice e Bob) stanno lavorando con lo stesso elemento in una tabella DynamoDB.
![Gli utenti Alice e Bob tentano di modificare un elemento con Id 1, dimostrando la necessità di scritture condizionali.](images/update-no-condition.png)
Supponiamo che Alice utilizzi l'attributo to AWS CLI per aggiornare l'Price
attributo a 8.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json
Gli argomenti per --expression-attribute-values
sono memorizzati nel file expression-attribute-values.json
:
{ ":newval":{"N":"8"} }
Supponi ora che Bob esegua una richiesta UpdateItem
simile in un secondo momento, modificando però il valore di Price
in 12. Per Bob, l'aspetto del parametro --expression-attribute-values
è simile al seguente.
{ ":newval":{"N":"12"} }
La richiesta di Bob ha esito positivo, ma l'aggiornamento precedente di Alice viene perso.
Per richiedere un'operazione PutItem
, DeleteItem
o UpdateItem
condizionale, specifichi un'espressione di condizione. Un'espressione condizionale è una stringa contenente nomi di attributi, operatori condizionali e funzioni predefinite. L'intera espressione deve essere vera. In caso contrario, l'operazione non va a buon fine.
Considera ora il diagramma seguente, che mostra in che modo le scritture condizionali impedirebbero la sovrascrittura dell'aggiornamento di Alice.
![Scrittura condizionale che impedisce all'aggiornamento dell'utente Bob di sovrascrivere la modifica dell'utente Alice allo stesso elemento.](images/update-yes-condition.png)
Alice prova innanzitutto ad aggiornare il valore di Price
a 8, ma solo se il valore di Price
corrente è 10.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json
Gli argomenti per --expression-attribute-values
sono memorizzati nel file expression-attribute-values.json
:
{ ":newval":{"N":"8"}, ":currval":{"N":"10"} }
L'aggiornamento di Alice riesce perché la condizione è vera.
Bob cerca quindi di aggiornare il valore di Price
a 12, ma solo se il valore di Price
corrente è 10. Per Bob, l'aspetto del parametro --expression-attribute-values
è simile al seguente.
{ ":newval":{"N":"12"}, ":currval":{"N":"10"} }
Poiché in precedenza Alice ha modificato il valore di Price
in 8, l'espressione condizionale è falsa e l'aggiornamento di Bob non riesce.
Per ulteriori informazioni, consulta Espressioni di condizione.
Idempotenza delle scritture condizionali
Le scritture condizionali possono essere idempotenti se la verifica condizionale è sullo stesso attributo in fase di aggiornamento. Ciò significa che DynamoDB esegue una certa richiesta di scrittura solo se determinati valori degli attributi nell'elemento corrispondono a quanto previsto al momento della richiesta.
Supponi, ad esempio, di eseguire una richiesta UpdateItem
per aumentare il valore di Price
per un elemento di 3, ma solo se il valore di Price
corrente è 20. Dopo che hai inviato la richiesta, ma prima di ricevere i risultati, si verifica un errore di rete e non sai se la richiesta ha avuto esito positivo. Poiché la scrittura condizionale è idempotente, è possibile eseguire di nuovo la stessa richiesta UpdateItem
e DynamoDB aggiornerà l'elemento solo se il valore di Price
corrente è 20.
Unità di capacità utilizzate dalle scritture condizionali
Se ConditionExpression
restituisce false durante una scrittura condizionale, DynamoDB utilizza comunque la capacità di scrittura della tabella. La quantità consumata dipende dalla dimensione dell'elemento esistente (o almeno 1). Ad esempio, se un elemento esistente è di 300 KB e il nuovo elemento che si sta cercando di creare o aggiornare è 310 KB, le unità di capacità di scrittura consumate saranno 300 se la condizione restituisce un errore o 310 se la condizione riesce. Se si tratta di un elemento nuovo (non un elemento esistente), le unità di capacità di scrittura consumate saranno 1 se la condizione restituisce un errore e 310 se la condizione riesce.
Nota
Le operazioni di scrittura utilizzano solo unità di capacità in scrittura. Non utilizzano mai unità di capacità in lettura.
Una scrittura condizionale non riuscita restituisce ConditionalCheckFailedException
. Quando ciò si verifica, nella risposta non si riceve alcuna informazione sulla capacità di scrittura consumata.
Per restituire il numero di unità di capacità di scrittura utilizzate durante una scrittura condizionale, usa il parametro ReturnConsumedCapacity
:
-
TOTAL
: restituisce il numero totale di unità di capacità di scrittura totali consumate. -
INDEXES
: restituisce il numero totale di unità di capacità di scrittura consumate, con i subtotali per la tabella e gli eventuali indici secondari interessati dall'operazione. -
NONE
: non vengono restituiti dettagli sulla capacità di scrittura. Questa è l'impostazione predefinita.
Nota
A differenza di un indice secondario globale, un indice secondario locale condivide la capacità di throughput assegnata con la relativa tabella. L'attività di lettura e scrittura su un indice secondario locale utilizza la capacità di throughput assegnata della tabella.