

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 espressioni di aggiornamento in DynamoDB

L'operazione `UpdateItem` aggiorna una voce esistente o aggiunge una nuova voce alla tabella, se non è già presente. È necessario fornire la chiave dell'elemento che intendi aggiornare. È necessario fornire inoltre un'espressione di aggiornamento che indica gli attributi che intendi modificare e i valori che intendi assegnargli. 

Una *espressione di aggiornamento* specifica come `UpdateItem` modificherà gli attributi di un elemento, ad esempio impostando un valore scalare o rimuovendo elementi da un elenco o da una mappa.

Di seguito è riportato un riepilogo della sintassi delle espressioni di aggiornamento.

```
update-expression ::=
    [ SET {{action}} [, {{action}}] ... ]
    [ REMOVE {{action}} [, {{action}}] ...]
    [ ADD {{action}} [, {{action}}] ... ]
    [ DELETE {{action}} [, {{action}}] ...]
```

Un'espressione di aggiornamento comprende una o più clausole. Ogni clausola inizia con una parola chiave `SET`, `REMOVE`, `ADD` o `DELETE`. Puoi includere qualsiasi di queste clausole in un'espressione di aggiornamento, in qualsiasi ordine. Tuttavia, ciascuna parola chiave dell'operazione può comparire una sola volta.

All'interno di ogni clausola esistono una o più operazioni separate da virgole. Ciascuna operazione rappresenta una modifica di dati.

**Nota**  
Quando un'espressione di aggiornamento contiene più azioni, DynamoDB valuta ogni azione rispetto ai valori degli attributi dell'elemento *com'erano prima dell'aggiornamento*. Le azioni non vengono applicate una dopo l'altra da sinistra a destra, quindi l'operando destro di un'azione si riferisce sempre al valore precedente all'aggiornamento di un attributo, anche se un'altra azione nella stessa espressione modifica anche quell'attributo.  
Ad esempio, supponiamo che un elemento sia `{"id": "1", "a": 1, "b": 2, "c": 3}` ed esegui la seguente espressione di aggiornamento:  

```
REMOVE a SET b = a, c = b
```
Il risultato è `{"id": "1", "b": 1, "c": 2}`. Entrambi `b = a` e `c = b` usa i valori originali di `a` e `b` (`1` e `2`) e `a` viene rimosso.

Gli esempi in questa sezione si basano sull'elemento `ProductCatalog` illustrato in [Utilizzo di espressioni di proiezione in DynamoDB](Expressions.ProjectionExpressions.md).

Gli argomenti seguenti illustrano diversi casi d'uso dell'operazione `SET`.

**Topics**
+ [SET: modifica o aggiunta di attributi dell'elemento](#Expressions.UpdateExpressions.SET)
+ [REMOVE: eliminazione degli attributi da un elemento](#Expressions.UpdateExpressions.REMOVE)
+ [ADD: aggiornamento di numeri e set](#Expressions.UpdateExpressions.ADD)
+ [DELETE: rimozione di elementi da un set](#Expressions.UpdateExpressions.DELETE)
+ [Utilizzo di più espressioni di aggiornamento](#Expressions.UpdateExpressions.Multiple)

## SET: modifica o aggiunta di attributi dell'elemento
<a name="Expressions.UpdateExpressions.SET"></a>

Utilizza l'operazione `SET` in un'espressione di aggiornamento per aggiungere uno o più attributi a un elemento. Se alcuni di questi attributi esistono già, vengono sovrascritti dai nuovi valori. Se intendi evitare la sovrascrittura di un attributo esistente, puoi utilizzare `SET` con la funzione `if_not_exists`. La funzione `if_not_exists` è specifica dell'operazione `SET` e può essere utilizzata solo in un'espressione di aggiornamento.

Quando utilizzi `SET` per aggiornare un elemento dell'elenco, i contenuti dell'elemento vengono sostituiti con i nuovi dati specificati. Se l'elemento non esiste ancora, `SET` aggiunge il nuovo elemento alla fine dell'elenco.

Se aggiungi più elementi in un'unica operazione `SET`, gli elementi verranno ordinati per numero di elemento.

Puoi inoltre utilizzare `SET` per aggiungere o sottrarre un attributo di tipo `Number`. Per eseguire più operazioni `SET`, separarle con virgole.

Nel riepilogo della sintassi seguente:
+ Il {{path}} elemento è il percorso del documento dell'elemento.
+ Un *{{operand}}* un elemento può essere il percorso del documento di un elemento o una funzione.

```
set-action ::=
    {{path}} = value

value ::=
    {{operand}}
    | {{operand}} '+' {{operand}}
    | {{operand}} '-' {{operand}}

operand ::=
    {{path}} | function

function ::=
    {{if_not_exists (path, value)}}
```

Se l’elemento non contiene un attributo nel percorso specificato, `if_not_exists` restituisce `value`. Altrimenti, restituisce `path`.

L'operazione `PutItem` seguente crea un elemento di esempio a cui gli esempi fanno riferimento.

```
aws dynamodb put-item \
    --table-name ProductCatalog \
    --item file://item.json
```

Gli argomenti per `--item` sono memorizzati nel file `item.json`: (Per semplicità, vengono utilizzati solo pochi attributi dell'item).

```json
{
    "Id": {"N": "789"},
    "ProductCategory": {"S": "Home Improvement"},
    "Price": {"N": "52"},
    "InStock": {"BOOL": true},
    "Brand": {"S": "Acme"}
}
```

**Topics**
+ [Modifica degli attributi](#Expressions.UpdateExpressions.SET.ModifyingAttributes)
+ [Aggiunta di elenchi e mappe](#Expressions.UpdateExpressions.SET.AddingListsAndMaps)
+ [Aggiunta di elementi a un elenco](#Expressions.UpdateExpressions.SET.AddingListElements)
+ [Aggiunta di attributi di mappa nidificati](#Expressions.UpdateExpressions.SET.AddingNestedMapAttributes)
+ [Incremento e decremento di attributi numerici](#Expressions.UpdateExpressions.SET.IncrementAndDecrement)
+ [Aggiunta di elementi a un elenco](#Expressions.UpdateExpressions.SET.UpdatingListElements)
+ [Prevenzione delle sovrascritture di un attributo esistente](#Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites)

### Modifica degli attributi
<a name="Expressions.UpdateExpressions.SET.ModifyingAttributes"></a>

**Example**  
Aggiorna gli attributi `ProductCategory` e `Price`.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET ProductCategory = :c, Price = :p" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW
```
Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `values.json`:  

```json
{
    ":c": { "S": "Hardware" },
    ":p": { "N": "60" }
}
```

**Nota**  
Nell'operazione `UpdateItem`, `--return-values ALL_NEW` fa in modo che DynamoDB restituisca l'elemento come compare dopo l'aggiornamento.

### Aggiunta di elenchi e mappe
<a name="Expressions.UpdateExpressions.SET.AddingListsAndMaps"></a>

**Example**  
Aggiungi un nuovo elenco e una nuova mappa.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems = :ri, ProductReviews = :pr" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW
```
Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `values.json`:  

```json
{
    ":ri": {
        "L": [
            { "S": "Hammer" }
        ]
    },
    ":pr": {
        "M": {
            "FiveStar": {
                "L": [
                    { "S": "Best product ever!" }
                ]
            }
        }
    }
}
```

### Aggiunta di elementi a un elenco
<a name="Expressions.UpdateExpressions.SET.AddingListElements"></a>

**Example**  
Aggiungi un nuovo attributo all'elenco `RelatedItems`. Ricorda che gli elementi dell'elenco sono a base zero, ovvero [0] rappresenta il primo elemento nell'elenco, [1] il secondo e così via.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :ri" \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW
```
Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `values.json`:  

```json
{
    ":ri": { "S": "Nails" }
}
```

**Nota**  
Quando utilizzi `SET` per aggiornare un elemento dell'elenco, i contenuti dell'elemento vengono sostituiti con i nuovi dati specificati. Se l'elemento non esiste ancora, `SET` aggiunge il nuovo elemento alla fine dell'elenco.  
Se aggiungi più elementi in un'unica operazione `SET`, gli elementi verranno ordinati per numero di elemento.

### Aggiunta di attributi di mappa nidificati
<a name="Expressions.UpdateExpressions.SET.AddingNestedMapAttributes"></a>

**Example**  
Aggiungi alcuni attributi di mappa nidificati.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #pr.#5star[1] = :r5, #pr.#3star = :r3" \
    --expression-attribute-names file://names.json \
    --expression-attribute-values file://values.json \
    --return-values ALL_NEW
```
Gli argomenti per `--expression-attribute-names` sono memorizzati nel file `names.json`:  

```json
{
    "#pr": "ProductReviews",
    "#5star": "FiveStar",
    "#3star": "ThreeStar"
}
```
Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `values.json`:  

```json
{
    ":r5": { "S": "Very happy with my purchase" },
    ":r3": {
        "L": [
            { "S": "Just OK - not that great" }
        ]
    }
}
```

**Importante**  
Non è possibile aggiornare gli attributi della mappa annidata se la mappa principale non esiste. Se si tenta di aggiornare un attributo nidificato (ad esempio, `ProductReviews.FiveStar`) quando la mappa principale (`ProductReviews`) non esiste, DynamoDB restituisce un `ValidationException` con il messaggio *«Il percorso del documento fornito nell'espressione di aggiornamento non è valido per l'aggiornamento».*  
Quando crei elementi con attributi di mappa annidati aggiornati in un secondo momento, inizializza le mappe vuote per gli attributi principali. Ad esempio:  

```json
{
    "Id": {"N": "789"},
    "ProductReviews": {"M": {}},
    "Metadata": {"M": {}}
}
```
Ciò consente di aggiornare attributi annidati come `ProductReviews.FiveStar` senza errori.

### Incremento e decremento di attributi numerici
<a name="Expressions.UpdateExpressions.SET.IncrementAndDecrement"></a>

Puoi eseguire aggiunte o sottrazioni da un attributo numerico esistente. A questo scopo, utilizza gli operatori `+` (più) e `-` (meno).

**Example**  
Riduci il valore `Price` di un elemento.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW
```
Per aumentare il valore `Price`, puoi utilizzare l'operatore `+` nell'espressione di aggiornamento.

### Aggiunta di elementi a un elenco
<a name="Expressions.UpdateExpressions.SET.UpdatingListElements"></a>

Puoi aggiungere elementi alla fine di un elenco. A tale scopo, utilizza `SET` con la funzione `list_append`. Il nome funzione rileva la distinzione tra maiuscole e minuscole. La funzione `list_append` è specifica dell'operazione `SET` e può essere utilizzata solo in un'espressione di aggiornamento. La sintassi è esposta di seguito.
+ `list_append ({{list1}}, {{list2}})`

La funzione prende due liste come input e aggiunge tutti gli elementi da `{{list2}}` a ` {{list1}}`.

**Example**  
In [Aggiunta di elementi a un elenco](#Expressions.UpdateExpressions.SET.AddingListElements), viene creato l'elenco `RelatedItems` e popolato con due elementi: `Hammer` e `Nails`. Vengono quindi aggiunti due altri elementi alla fine di `RelatedItems`.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(#ri, :vals)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values file://values.json  \
    --return-values ALL_NEW
```
Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `values.json`:  

```json
{
    ":vals": {
        "L": [
            { "S": "Screwdriver" },
            {"S": "Hacksaw" }
        ]
    }
}
```
Infine, viene aggiunto un ulteriore elemento all'*inizio* di `RelatedItems`. A questo scopo, scambia l'ordine degli elementi `list_append`. Ricorda che `list_append` accetta due elenchi come input e aggiunge il secondo elenco al primo.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET #ri = list_append(:vals, #ri)" \
    --expression-attribute-names '{"#ri": "RelatedItems"}' \
    --expression-attribute-values '{":vals": {"L": [ { "S": "Chisel" }]}}' \
    --return-values ALL_NEW
```
L'attributo `RelatedItems` risultante contiene ora cinque elementi nell'ordine seguente: `Chisel`, `Hammer`, `Nails`, `Screwdriver`, `Hacksaw`.

### Prevenzione delle sovrascritture di un attributo esistente
<a name="Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites"></a>

**Example**  
Imposta l'attributo `Price` di un elemento, ma solo se l'elemento non dispone già di un attributo `Price`. Se l'attributo `Price` esiste già, non accade nulla.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = if_not_exists(Price, :p)" \
    --expression-attribute-values '{":p": {"N": "100"}}' \
    --return-values ALL_NEW
```

## REMOVE: eliminazione degli attributi da un elemento
<a name="Expressions.UpdateExpressions.REMOVE"></a>

Utilizza l'operazione `REMOVE` in una espressione di aggiornamento per rimuovere uno o più attributi di un elemento in Amazon DynamoDB. Per eseguire più operazioni `REMOVE`, separarle con virgole.

Di seguito è riportato un riepilogo della sintassi di `REMOVE` in un'espressione di aggiornamento. L'unico operando è il percorso di documento dell'attributo che intendi rimuovere.

```
remove-action ::=
    {{path}}
```

**Example**  
Rimuovi alcuni attributi di un elemento. Se gli attributi non esistono, non accade nulla.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE Brand, InStock, QuantityOnHand" \
    --return-values ALL_NEW
```

### Rimozione di elementi da un elenco
<a name="Expressions.UpdateExpressions.REMOVE.RemovingListElements"></a>

Puoi utilizzare `REMOVE` per eliminare singoli elementi da un elenco.

**Example**  
In [Aggiunta di elementi a un elenco](#Expressions.UpdateExpressions.SET.UpdatingListElements), modifica un attributo di elenco (`RelatedItems`) in modo che contenga cinque elementi:   
+ `[0]`—`Chisel`
+ `[1]`—`Hammer`
+ `[2]`—`Nails`
+ `[3]`—`Screwdriver`
+ `[4]`—`Hacksaw`
Quanto segue AWS Command Line Interface (AWS CLI), ad esempio, elimina `Hammer` e `Nails` dall'elenco.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
    --return-values ALL_NEW
```
Dopo che `Hammer` e `Nails` sono stati rimossi, gli elementi rimanenti vengono spostati. Ora l'elenco contiene quanto segue:  
+ `[0]`—`Chisel`
+ `[1]`—`Screwdriver`
+ `[2]`—`Hacksaw`

## ADD: aggiornamento di numeri e set
<a name="Expressions.UpdateExpressions.ADD"></a>

**Nota**  
In generale, si consiglia di utilizzare `SET` piuttosto che `ADD` per garantire operazioni idempotenti.

Utilizza l'operazione `ADD` in un'espressione di aggiornamento per aggiungere un nuovo attributo e i suoi valori a un elemento.

Se l'attributo esiste già, il comportamento di `ADD` dipende dal tipo di dati dell'attributo:
+ Se l'attributo è un numero e anche il valore da aggiungere è un numero, il valore viene aggiunto matematicamente all'attributo esistente. Se il valore è un numero negativo, viene sottratto dall'attributo esistente.
+ Se l'attributo è un set e anche il valore da aggiungere è un set, il valore viene aggiunto matematicamente al set esistente.

**Nota**  
L'operazione `ADD` supporta solo i tipi di dati Number e Set.

Per eseguire più operazioni `ADD`, separarle con virgole.

Nel riepilogo della sintassi seguente:
+ Le {{path}} l'elemento è il percorso del documento a un attributo. L'attributo deve essere un tipo di dati `Number` o Set. 
+ Il {{value}} l'elemento è un numero che si desidera aggiungere all'attributo (per `Number` tipi di dati) o un set da aggiungere all'attributo (per i tipi di set).

```
add-action ::=
    {{path}} {{value}}
```

Gli argomenti seguenti illustrano diversi casi d'uso dell'operazione `ADD`.

**Topics**
+ [Aggiunta di un numero](#Expressions.UpdateExpressions.ADD.Number)
+ [Aggiunta di elementi a un set](#Expressions.UpdateExpressions.ADD.Set)

### Aggiunta di un numero
<a name="Expressions.UpdateExpressions.ADD.Number"></a>

Supponiamo che l'attributo `QuantityOnHand` non esista. Quanto segue AWS CLI set di esempi `QuantityOnHand` fino a 5.

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD QuantityOnHand :q" \
    --expression-attribute-values '{":q": {"N": "5"}}' \
    --return-values ALL_NEW
```

Ora che `QuantityOnHand` esiste, puoi eseguire nuovamente l'esempio per incrementare `QuantityOnHand` ogni volta di 5.

### Aggiunta di elementi a un set
<a name="Expressions.UpdateExpressions.ADD.Set"></a>

Supponiamo che l'attributo `Color` non esista. L'esempio AWS CLI seguente imposta `Color` su un set di stringhe con due elementi.

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Orange", "Purple"]}}' \
    --return-values ALL_NEW
```

Ora che `Color` esiste, puoi aggiungergli più elementi:

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "ADD Color :c" \
    --expression-attribute-values '{":c": {"SS":["Yellow", "Green", "Blue"]}}' \
    --return-values ALL_NEW
```

## DELETE: rimozione di elementi da un set
<a name="Expressions.UpdateExpressions.DELETE"></a>

**Importante**  
L'operazione `DELETE` supporta solo i tipi di dati `Set`.

Utilizza l'operazione `DELETE` in un'espressione di aggiornamento per rimuovere uno o più elementi da un set. Per eseguire più operazioni `DELETE`, separarle con virgole.

Nel riepilogo della sintassi seguente:
+ Il {{path}} l'elemento è il percorso del documento a un attributo. L'attributo deve essere un tipo di dati Set.
+ Il {{subset}} è uno o più elementi che desideri eliminare da {{path}}. È necessario specificare {{subset}} come tipo di set.

```
delete-action ::=
    {{path}} {{subset}}
```

**Example**  
In [Aggiunta di elementi a un set](#Expressions.UpdateExpressions.ADD.Set), crea lo String Set `Color`. In questo esempio vengono rimossi alcuni elementi di tale set.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "DELETE Color :p" \
    --expression-attribute-values '{":p": {"SS": ["Yellow", "Purple"]}}' \
    --return-values ALL_NEW
```

## Utilizzo di più espressioni di aggiornamento
<a name="Expressions.UpdateExpressions.Multiple"></a>

È possibile utilizzare più azioni in una singola espressione di aggiornamento. Tutti i riferimenti agli attributi vengono risolti in base allo stato dell'elemento prima dell'applicazione di qualsiasi azione.

**Example**  
Dato un elemento `{"id": "1", "a": 1, "b": 2, "c": 3}`, l'espressione seguente rimuove `a` e sposta i valori di `b` e `c`:  

```
aws dynamodb update-item \
    --table-name test \
    --key '{"id":{"S":"1"}}' \
    --update-expression "REMOVE a SET b = a, c = b" \
    --return-values ALL_NEW
```
Il risultato è `{"id": "1", "b": 1, "c": 2}`. Anche se `a` viene rimosso e `b` viene riassegnato nella stessa espressione, entrambi i riferimenti vengono ripristinati ai valori originali.

**Example**  
Se vuoi modificare il valore di un attributo e rimuovere completamente un altro attributo, puoi utilizzare le operazioni SET e REMOVE in una singola istruzione. Questa operazione imposta il valore di `Price` su 15 e rimuove l'attributo `InStock` dall'elemento.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET Price = Price - :p REMOVE InStock" \
    --expression-attribute-values '{":p": {"N":"15"}}' \
    --return-values ALL_NEW
```

**Example**  
Se desideri aggiungere una voce a un elenco modificando anche il valore di un attributo, puoi utilizzare due operazioni SET in una singola istruzione. Questa operazione aggiunge "Nails" all'attributo di elenco `RelatedItems` e imposta il valore di `Price` su 21.  

```
aws dynamodb update-item \
    --table-name ProductCatalog \
    --key '{"Id":{"N":"789"}}' \
    --update-expression "SET RelatedItems[1] = :newValue, Price = :newPrice" \
    --expression-attribute-values '{":newValue": {"S":"Nails"}, ":newPrice": {"N":"21"}}'  \
    --return-values ALL_NEW
```