Expressions de mise à jour - Amazon DynamoDB
SET – Modification ou ajout d'attributs d'élémentREMOVE – Suppression d'attributs d'un élémentADD – Mise à jour de nombres et d'ensemblesDELETE – Suppression d'éléments d'un ensembleUtilisation de plusieurs expressions de mise à jour

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.

Expressions de mise à jour

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, ce qui indique les attributs que vous voulez modifier et les valeurs que vous souhaitez leur attribuer.

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écapitulatif 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 plusieurs clauses. Chaque clause commence par un mot-clé SET, REMOVE, ADD ou DELETE. Vous pouvez inclure 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 contient 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 Expressions de projections.

Les rubriques ci-dessous couvrent différents cas d'utilisation de l'action SET.

SET – Modification ou ajout d'attributs d'élément

Utilisez l'action SET dans une expression de mise à jour pour ajouter un ou plusieurs attributs à un élément. Si l'un de ces attributs existe déjà, il est remplacé par les nouvelles valeurs.

Vous pouvez également utiliser SET pour ajouter ou soustraire un attribut qui est de type Number. Afin d'effectuer plusieurs actions SET, séparez-les par des virgules.

Dans le récapitulatif de la syntaxe suivante :

  • L'élément chemin est le chemin d'accès au document pour l'élément.

  • Un élément opérande peut être un chemin d'accès au document pour un élément ou une fonction.

set-action ::=
    path = value

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

operand ::=
    path | function

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"}
}

Modification d'attributs

Exemple

Met à 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 apparaît après la mise à jour.

Ajouter des listes et des maps

Exemple

Ajoutez une nouvelle liste et une nouvelle carte.

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

Exemple

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.

Ajouter des attributs de map imbriqués

Exemple

Ajoutez certains attributs de carte 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" }
        ]
    }
}

Incrémentation et décrémentation d'attributs numériques

Vous pouvez ajouter ou soustraire depuis un attribut numérique existant. Pour ce faire, utilisez les opérateurs + (plus) et - (moins).

Exemple

Réduit 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

Afin d'accroître le Price, utilisez 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 est sensible à la casse.) La fonction list_append est spécifique de l'action SET et peut être utilisée 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.

Exemple

Dans Ajout d'éléments à une liste, vous créez la liste RelatedItems et la complétez avec deux éléments : Hammer et Nails. Nous allons 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, nous allons 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 contient maintenant cinq éléments, dans l'ordre suivant : Chisel, Hammer, Nails, Screwdriver, Hacksaw.

Empêcher le remplacement d'un attribut existant

Si vous souhaitez éviter de remplacer un attribut existant, vous pouvez utiliser l'attribut SET avec la fonction if_not_exists. (Le nom de fonction est sensible à la casse.) La fonction if_not_exists est spécifique de l'action SET et peut être utilisée uniquement dans une expression de mise à jour. La syntaxe est la suivante.

  • if_not_exists (path, value)

Si l'élément ne contient pas un attribut au path spécifié, alors if_not_exists prend la valeur value ; sinon, path.

Exemple

Définissez l'attribut Price d'un élément, mais uniquement 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

Utilisez l'action REMOVE dans une expression de mise à jour pour supprimer un ou plusieurs attributs d'un élément dans Amazon DynamoDB. Afin d'effectuer plusieurs actions REMOVE, séparez-les par des virgules.

Ce qui suit est 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
Exemple

Supprimer 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 utiliser REMOVE pour supprimer des éléments d'une liste.

Exemple

Dans Ajout d'éléments à une liste, nous avons modifié un attribut de liste (RelatedItems) de sorte qu'il contienne 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 contient 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 ADD.

Utilisez l'action ADD dans une expression de mise à jour pour ajouter un nouvel attribut et ses valeurs à un élément.

Si l'attribut existe déjà, alors le comportement de 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, alors elle est soustraite de l'attribut existant.)

  • Si l'attribut est un ensemble, et que la valeur que vous ajoutez est également un ensemble, alors la valeur est ajoutée à l'ensemble existant.

Note

L'action ADD prend uniquement en charge les données de type Number et Set.

Afin d'effectuer plusieurs actions ADD, séparez-les par des virgules.

Dans le récapitulatif de la syntaxe suivante :

  • L'élément path est le chemin d'accès au document pour un attribut. L'attribut doit être un Number ou un type de données défini.

  • L'élément value est un nombre que vous voulez ajouter à l'attribut (pour les types de données Number), ou un ensemble à ajouter à l'attribut (pour les types SET).

add-action ::=
    path value

Les rubriques ci-dessous couvrent différents cas d'utilisation de l'action ADD.

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 exécuter à nouveau 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.

Utilisez l'action DELETE dans une expression de mise à jour pour supprimer un ou plusieurs éléments d'un ensemble. Afin d'effectuer plusieurs actions DELETE, séparez-les par des virgules.

Dans le récapitulatif de la syntaxe suivante :

  • L'élément path est le chemin d'accès au document pour un attribut. L'attribut doit être un type de données défini.

  • Le sous-ensemble correspond à un ou plusieurs éléments à supprimer du chemin. Vous devez spécifier sous-ensemble comme type d'attribut Set.

delete-action ::=
    path subset
Exemple

Dans Ajout d'éléments à un ensemble, 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 expressions de mise à jour dans une seule instruction.

Si vous souhaitez modifier la valeur d'un attribut et supprimer complètement un autre attribut, vous pouvez utiliser une action SET et une action REMOVE dans une seule instruction. Cette opération réduirait la valeur de 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

Si vous souhaitez ajouter des éléments à une liste tout en modifiant la valeur d'un autre attribut, vous pouvez utiliser deux actions SET dans une seule instruction. Cette opération ajouterait « Nails » à l'attribut RelatedItems list et définirait également la valeur de 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