Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Utilisation d’expressions de mise à jour dans DynamoDB
L’opération `UpdateItem` met à jour un élément existant ou ajoute un nouvel élément à la table si celui-ci n’existe pas déjà. Vous devez fournir la clé de l’élément que vous souhaitez mettre à jour. Vous devez également fournir une expression de mise à jour, en indiquant les attributs que vous souhaitez modifier et les valeurs que vous souhaitez leur affecter.
Une *expression de mise à jour* spécifie comment l’opération `UpdateItem` doit modifier les attributs d’un élément, par exemple en définissant une valeur scalaire ou en supprimant des éléments d’une liste ou d’un mappage.
Voici un résumé de la syntaxe des expressions de mise à jour :
```
update-expression ::=
[ SET action [, action] ... ]
[ REMOVE action [, action] ...]
[ ADD action [, action] ... ]
[ DELETE action [, action] ...]
```
Une expression de mise à jour se compose d’une ou de plusieurs clauses. Chaque clause commence par un mot clé `SET`, `REMOVE`, `ADD` ou `DELETE`. Vous pouvez inclure l’une de ces clauses dans une expression de mise à jour, dans n’importe quel ordre. Toutefois, chaque mot clé d’action peut n’apparaître qu’une seule fois.
Chaque clause comporte une ou plusieurs actions, séparées par des virgules. Chaque action représente une modification de données.
Les exemples de cette section sont basés sur l’élément `ProductCatalog` présenté dans [Utilisation d’expressions de projection dans DynamoDB](Expressions.ProjectionExpressions.md).
Les rubriques ci-dessous couvrent différents cas d’utilisation de l’action `SET`.
**Topics**
+ [SET – Modification ou ajout d’attributs d’élément](#Expressions.UpdateExpressions.SET)
+ [REMOVE – Suppression d’attributs d’un élément](#Expressions.UpdateExpressions.REMOVE)
+ [ADD – Mise à jour de nombres et d’ensembles](#Expressions.UpdateExpressions.ADD)
+ [DELETE – Suppression d’éléments d’un ensemble](#Expressions.UpdateExpressions.DELETE)
+ [Utilisation de plusieurs expressions de mise à jour](#Expressions.UpdateExpressions.Multiple)
## SET – Modification ou ajout d’attributs d’élément
Ajoutez un ou plusieurs attributs à un élément à l’aide de l’action `SET` dans une expression de mise à jour. Si l’un de ces attributs existe déjà, il est remplacé par les nouvelles valeurs. Si vous souhaitez éviter de remplacer un attribut existant, vous pouvez utiliser l’action `SET` avec la fonction `if_not_exists`. La fonction `if_not_exists` est spécifique à l’action `SET` et utilisable uniquement dans une expression de mise à jour.
Lorsque vous utilisez `SET` pour mettre à jour un élément de la liste, le contenu de cet élément est remplacé par les nouvelles données que vous spécifiez. Si l’élément n’existe pas déjà, `SET` ajoute le nouvel élément à la fin de la liste.
Si vous ajoutez plusieurs éléments dans une seule opération `SET`, les éléments sont triés dans l’ordre par numéro d’élément.
Vous pouvez également effectuer un ajout ou une soustraction à un attribut de type `Number` à l’aide de `SET`. Afin d’effectuer plusieurs actions `SET`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers l'élément.
+ Un **operand**élément peut être un chemin de document vers un élément ou une fonction.
```
set-action ::=
path = value
value ::=
operand
| operand '+' operand
| operand '-' operand
operand ::=
path | function
function ::=
if_not_exists (path, value)
```
Si l’élément ne contient pas d’attribut au chemin d’accès spécifié, la fonction `if_not_exists` prend la valeur `value`. Dans le cas contraire, elle prend la valeur `path`.
L’opération `PutItem` suivante crée un exemple d’élément auquel nous ferons référence dans les exemples.
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
Les arguments de la fonction `--item` sont stockés dans le fichier `item.json`. Dans un souci de simplicité, seuls quelques attributs sont utilisés.
```
{
"Id": {"N": "789"},
"ProductCategory": {"S": "Home Improvement"},
"Price": {"N": "52"},
"InStock": {"BOOL": true},
"Brand": {"S": "Acme"}
}
```
**Topics**
+ [Modification d’attributs](#Expressions.UpdateExpressions.SET.ModifyingAttributes)
+ [Ajout de listes et de mappages](#Expressions.UpdateExpressions.SET.AddingListsAndMaps)
+ [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.AddingListElements)
+ [Ajout d’attributs de mappage imbriqués](#Expressions.UpdateExpressions.SET.AddingNestedMapAttributes)
+ [Incrémentation et décrémentation d’attributs numériques](#Expressions.UpdateExpressions.SET.IncrementAndDecrement)
+ [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.UpdatingListElements)
+ [Empêcher le remplacement d’un attribut existant](#Expressions.UpdateExpressions.SET.PreventingAttributeOverwrites)
### Modification d’attributs
**Example**
Mettez à jour les attributs `ProductCategory` et `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
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":c": { "S": "Hardware" },
":p": { "N": "60" }
}
```
**Note**
Dans l’opération `UpdateItem`, `--return-values ALL_NEW` amène DynamoDB à renvoyer l’élément tel qu’il s’affiche après la mise à jour.
### Ajout de listes et de mappages
**Example**
Ajoutez une nouvelle liste et un nouveau mappage.
```
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
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":ri": {
"L": [
{ "S": "Hammer" }
]
},
":pr": {
"M": {
"FiveStar": {
"L": [
{ "S": "Best product ever!" }
]
}
}
}
}
```
### Ajout d’éléments à une liste
**Example**
Ajoutez un nouvel attribut à la liste `RelatedItems`. (N’oubliez pas que les éléments de liste sont en base zéro, donc [0] représente le premier élément dans la liste, [1] représente le deuxième et ainsi de suite.)
```
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
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":ri": { "S": "Nails" }
}
```
**Note**
Lorsque vous utilisez `SET` pour mettre à jour un élément de la liste, le contenu de cet élément est remplacé par les nouvelles données que vous spécifiez. Si l’élément n’existe pas déjà, `SET` ajoute le nouvel élément à la fin de la liste.
Si vous ajoutez plusieurs éléments dans une seule opération `SET`, les éléments sont triés dans l’ordre par numéro d’élément.
### Ajout d’attributs de mappage imbriqués
**Example**
Ajoutez certains attributs de mappage imbriqués.
```
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
```
Les arguments de la fonction `--expression-attribute-names` sont stockés dans le fichier `names.json`.
```
{
"#pr": "ProductReviews",
"#5star": "FiveStar",
"#3star": "ThreeStar"
}
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":r5": { "S": "Very happy with my purchase" },
":r3": {
"L": [
{ "S": "Just OK - not that great" }
]
}
}
```
**Important**
Vous ne pouvez pas mettre à jour les attributs de carte imbriqués si la carte parent n'existe pas. Si vous tentez de mettre à jour un attribut imbriqué (par exemple,`ProductReviews.FiveStar`) alors que la carte parent (`ProductReviews`) n'existe pas, DynamoDB renvoie `ValidationException` un avec le *message « Le chemin du document fourni dans l'expression de mise à jour n'est pas valide pour la mise à jour* ».
Lorsque vous créez des éléments dont les attributs de carte imbriqués seront mis à jour ultérieurement, initialisez des cartes vides pour les attributs parents. Par exemple :
```
{
"Id": {"N": "789"},
"ProductReviews": {"M": {}},
"Metadata": {"M": {}}
}
```
Cela vous permet de mettre à jour les attributs imbriqués `ProductReviews.FiveStar` sans erreur.
### Incrémentation et décrémentation d’attributs numériques
Vous pouvez effectuer un ajout ou une soustraction à un attribut numérique existant. Pour ce faire, utilisez les opérateurs `+` (plus) et `-` (moins).
**Example**
Réduisez l’attribut `Price` d’un élément.
```
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
```
Augmentez l’attribut `Price` à l’aide de l’opérateur `+` dans l’expression de mise à jour.
### Ajout d’éléments à une liste
Vous pouvez ajouter des éléments à la fin d’une liste. Pour ce faire, utilisez `SET` avec la fonction `list_append`. (Le nom de fonction respecte la casse.) La fonction `list_append` est spécifique à l’action `SET` et utilisable uniquement dans une expression de mise à jour. La syntaxe est la suivante.
+ `list_append (list1, list2)`
La fonction prend deux listes en entrée et ajoute tous les éléments de `list2` à ` list1`.
**Example**
Dans [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.AddingListElements), vous créez la liste `RelatedItems` et la renseignez avec deux éléments : `Hammer` et `Nails`. Vous allez maintenant ajouter deux autres éléments à la fin de `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
```
Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`.
```
{
":vals": {
"L": [
{ "S": "Screwdriver" },
{"S": "Hacksaw" }
]
}
}
```
Enfin, vous allez ajouter un autre élément au *début* de `RelatedItems`. Pour ce faire, permutez l’ordre des éléments `list_append`. (N’oubliez pas que la fonction `list_append` prend deux listes en entrée, puis ajoute la seconde liste à la première.)
```
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’attribut `RelatedItems` résultant comporte maintenant cinq éléments, dans l’ordre suivant : `Chisel`, `Hammer`, `Nails`, `Screwdriver`, `Hacksaw`.
### Empêcher le remplacement d’un attribut existant
**Example**
Définissez l’attribut `Price` d’un élément, mais seulement si l’élément ne possède pas déjà un attribut `Price`. (Si `Price` existe déjà, il ne se passe rien.)
```
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 – Suppression d’attributs d’un élément
Supprimez un ou plusieurs attributs d’un élément dans Amazon DynamoDB à l’aide de l’action `REMOVE` dans une expression de mise à jour. Afin d’effectuer plusieurs actions `REMOVE`, séparez-les par des virgules.
Voici un résumé de la syntaxe pour `REMOVE` dans une expression de mise à jour. Le seul opérande est le chemin d’accès au document pour l’attribut que vous souhaitez supprimer.
```
remove-action ::=
path
```
**Example**
Supprimez des attributs d’un élément. (Si les attributs n’existent pas, il ne se passe rien.)
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE Brand, InStock, QuantityOnHand" \
--return-values ALL_NEW
```
### Suppression d’éléments d’une liste
Vous pouvez supprimer des éléments d’une liste à l’aide de `REMOVE`.
**Example**
Dans [Ajout d’éléments à une liste](#Expressions.UpdateExpressions.SET.UpdatingListElements), vous avez modifié un attribut de liste (`RelatedItems`) de sorte qu’il comporte les cinq éléments suivants :
+ `[0]`—`Chisel`
+ `[1]`—`Hammer`
+ `[2]`—`Nails`
+ `[3]`—`Screwdriver`
+ `[4]`—`Hacksaw`
L'exemple suivant AWS Command Line Interface (AWS CLI) supprime `Hammer` et `Nails` de la liste.
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"789"}}' \
--update-expression "REMOVE RelatedItems[1], RelatedItems[2]" \
--return-values ALL_NEW
```
Après la suppression de `Hammer` et `Nails`, les éléments restants sont déplacés. La liste comporte désormais les éléments suivants :
+ `[0]`—`Chisel`
+ `[1]`—`Screwdriver`
+ `[2]`—`Hacksaw`
## ADD – Mise à jour de nombres et d’ensembles
**Note**
En général, nous recommandons d'utiliser `SET` plutôt que de `ADD` garantir des opérations idempotentes.
Ajoutez un nouvel attribut et ses valeurs à un élément à l’aide de l’action `ADD` dans une expression de mise à jour.
Si l’attribut existe déjà, le comportement d’`ADD` dépend du type de données de l’attribut :
+ Si l’attribut est un nombre et que la valeur que vous ajoutez est également un nombre, la valeur est ajoutée mathématiquement à l’attribut existant. (Si la valeur est un nombre négatif, elle est soustraite de l’attribut existant.)
+ Si l’attribut est un ensemble et que la valeur que vous ajoutez est également un ensemble, la valeur est ajoutée à l’ensemble existant.
**Note**
L’action `ADD` prend uniquement en charge les données de type nombre et ensemble.
Afin d’effectuer plusieurs actions `ADD`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers un attribut. L’attribut doit être un `Number` ou un type de données ensemble.
+ L'*value*élément est un nombre que vous souhaitez ajouter à l'attribut (pour les types de `Number` données) ou un ensemble à ajouter à l'attribut (pour les types d'ensembles).
```
add-action ::=
path value
```
Les rubriques ci-dessous couvrent différents cas d’utilisation de l’action `ADD`.
**Topics**
+ [Ajout d’un nombre](#Expressions.UpdateExpressions.ADD.Number)
+ [Ajout d’éléments à un ensemble](#Expressions.UpdateExpressions.ADD.Set)
### Ajout d’un nombre
Supposons que l’attribut `QuantityOnHand` n’existe pas. L' AWS CLI exemple suivant définit `QuantityOnHand` la valeur 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
```
Maintenant que `QuantityOnHand` existe, vous pouvez réexécuter l’exemple pour incrémenter `QuantityOnHand` de 5 chaque fois.
### Ajout d’éléments à un ensemble
Supposons que l’attribut `Color` n’existe pas. L’exemple AWS CLI suivant définit `Color` sur un ensemble de chaîne avec deux éléments.
```
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
```
Maintenant que `Color` existe, vous pouvez lui ajouter de nouveaux éléments.
```
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 – Suppression d’éléments d’un ensemble
**Important**
L’action `DELETE` prend uniquement en charge les types de données `Set`.
Supprimez un ou plusieurs éléments d’un ensemble à l’aide de l’action `DELETE` dans une expression de mise à jour. Afin d’effectuer plusieurs actions `DELETE`, séparez-les par des virgules.
Dans le récapitulatif de la syntaxe suivante :
+ L'*path*élément est le chemin du document vers un attribut. L’attribut doit être un type de données ensemble.
+ *subset*Il s'agit d'un ou de plusieurs éléments que vous souhaitez supprimer*path*. Vous devez le spécifier *subset* en tant que type d'ensemble.
```
delete-action ::=
path subset
```
**Example**
Dans [Ajout d’éléments à un ensemble](#Expressions.UpdateExpressions.ADD.Set), vous créez l’ensemble de chaînes `Color`. Cet exemple supprime certains des éléments de cet ensemble.
```
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
```
## Utilisation de plusieurs expressions de mise à jour
Vous pouvez utiliser plusieurs actions dans une seule expression de mise à jour. Toutes les références d'attributs sont résolues en fonction de l'état de l'élément avant que l'une des actions ne soit appliquée.
**Example**
Étant donné un élément`{"id": "1", "a": 1, "b": 2, "c": 3}`, l'expression suivante supprime `a` et déplace les valeurs de `b` et `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
```
Le résultat est`{"id": "1", "b": 1, "c": 2}`. Même si elle `a` est supprimée et `b` réaffectée dans la même expression, les deux références retrouvent leurs valeurs d'origine.
**Example**
Vous pouvez modifier la valeur d’un attribut et supprimer complètement un autre attribut à l’aide d’une action SET et d’une action REMOVE dans une seule instruction. Cette opération réduirait la valeur de l’attribut `Price` à 15 tout en supprimant l’attribut `InStock` de l’élément.
```
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**
Vous pouvez ajouter des éléments à une liste tout en modifiant la valeur d’un autre attribut à l’aide de deux actions SET dans une seule instruction. Cette opération ajouterait « Nails » à l’attribut de liste `RelatedItems` et définirait également la valeur de l’attribut `Price` sur 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
```