Utilizzo di elementi e attributi in DynamoDB

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.

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:

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.

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.

aws dynamodb get-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"1"}}'

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 Utilizzo delle espressioni di proiezione in DynamoDB.

Per restituire il numero di unità di capacità di lettura utilizzate da GetItem, imposta il parametro ReturnConsumedCapacity su TOTAL.

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:

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:

PutItem

PutItem crea un nuovo elemento. Se nella tabella esiste già un elemento con la stessa chiave, il nuovo elemento sostituisce quello esistente.

aws dynamodb put-item \
    --table-name Thread \
    --item 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 Utilizzo delle espressioni di aggiornamento in DynamoDB.

Nell'espressione di aggiornamento usi i valori degli attributi di espressione come segnaposto per i valori effettivi. Per ulteriori informazioni, consulta Utilizzo dei valori degli attributi di espressione in DynamoDB.

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.

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

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à.

DeleteItem

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.

aws dynamodb batch-get-item \
    --request-items 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.

aws dynamodb batch-write-item \
    --request-items 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.

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 Esempio di espressione di condizione DynamoDB CLI.

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.

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: