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": "[e-mail]"},
    "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":"[e-mail]"}
}

DeleteItem

DeleteItem elimina l'elemento con la chiave specificata.

Esempio

L' AWS CLI esempio seguente mostra come eliminare l'Threadelemento.

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.

Supponiamo che Alice utilizzi l'attributo to AWS CLI per aggiornare l'Priceattributo 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.

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.