Utilisation d’expressions de mise à jour dans DynamoDB - 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.

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.

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

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 soit le chemin d'un document vers un élément, soit 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"}
}

Modification d’attributs

Exemple

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

Exemple

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

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.

Ajout d’attributs de mappage imbriqués

Exemple

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

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

Exemple

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.

Exemple

Dans Ajout d’éléments à une liste, 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

Exemple

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
Exemple

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.

Exemple

Dans Ajout d’éléments à une liste, 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 vous recommandons d’utiliser SET plutôt qu’ADD.

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.

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.

  • subsetIl s'agit d'un ou de plusieurs éléments que vous souhaitez supprimerpath. Vous devez le spécifier subset en tant que type d'ensemble.

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.

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

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