Expressions de condition - Amazon DynamoDB

Expressions de condition

Pour manipuler les données d'une table Amazon DynamoDB, vous utilisez les opérations PutItem, UpdateItem et DeleteItem. Vous pouvez également utiliser BatchWriteItem pour effectuer plusieurs opérations PutItem ou DeleteItem au cours d'un seul appel.

Pour ces opérations de manipulation de données, vous pouvez préciser une expression de condition afin de déterminer les éléments à modifier. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

Voici quelques exemples AWS Command Line Interface (AWS CLI) d'utilisation d'expressions de condition. Ces exemples sont basés sur la table ProductCatalog, qui a été présentée dans Spécification d'attributs d'élément lors de l'utilisation d'expressions. La clé de partition de cette table est Id ; et il n'y a aucune clé de tri. L'opération PutItem suivante crée un exemple d'élément ProductCatalog 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": "456" }, "ProductCategory": {"S": "Sporting Goods" }, "Price": {"N": "650" } }

Insertion conditionnelle

L'opération PutItem remplace un élément avec la même clé (si elle existe). Pour éviter cela, utilisez une expression de condition. Elle permet la poursuite de l'écriture uniquement si l'élément en question ne possède pas déjà la même clé.

aws dynamodb put-item \ --table-name ProductCatalog \ --item file://item.json \ --condition-expression "attribute_not_exists(Id)"

Si l'expression de condition prend la valeur false, demandeur renvoie le message d'erreur suivant : The conditional request failed (Échec de la demande conditionnelle).

Note

Pour plus d'informations sur attribute_not_exists et d'autres fonctions, consultez Référence concernant les opérateurs et fonctions de comparaison.

Suppressions conditionnelles

Pour effectuer une suppression conditionnelle, utilisez une opération DeleteItem avec une expression de condition. L'expression de condition doit avoir la valeur true afin que l'opération aboutisse. Dans le cas contraire, l'opération échoue.

Considère l'élément depuis Expressions de condition.

{ "Id": { "N": "456" }, "Price": { "N": "650" }, "ProductCategory": { "S": "Sporting Goods" } }

Supposons maintenant que vous souhaitiez supprimer l'élément, mais uniquement dans les conditions suivantes :

  • L'attribut ProductCategory est soit « Sporting Goods » (Matériels de sport) soit « Gardening Supplies » (Articles de jardinerie).

  • Le Price est compris entre 500 et 600.

L'exemple suivant tente de supprimer l'élément.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"456"}}' \ --condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \ --expression-attribute-values file://values.json

Les arguments de la fonction --expression-attribute-values sont stockés dans le fichier values.json.

{ ":cat1": {"S": "Sporting Goods"}, ":cat2": {"S": "Gardening Supplies"}, ":lo": {"N": "500"}, ":hi": {"N": "600"} }
Note

Dans l'expression de condition, le signe : (deux points) indique une valeur d'attribut d'expression, c'est-à-dire un espace réservé pour une valeur réelle. Pour de plus amples informations, veuillez consulter Valeurs d'attributs d'expressions.

Pour plus d'informations sur IN, AND et d'autres mots-clés, consultez Référence concernant les opérateurs et fonctions de comparaison.

Dans cet exemple, la comparaison ProductCategory a la valeur true, mais la comparaison Price a la valeur false. Il s'ensuit que l'expression de condition prend la valeur false et que l'opération DeleteItem échoue.

Mises à jour conditionnelles

Pour effectuer une mise à jour conditionnelle, utilisez une opération UpdateItem avec une expression de condition. L'expression de condition doit avoir la valeur true afin que l'opération aboutisse. Dans le cas contraire, l'opération échoue.

Note

UpdateItem prend également en charge les expressions de mise à jour, dans lesquelles vous spécifiez les modifications à apporter à un élément. Pour de plus amples informations, veuillez consulter Expressions de mise à jour.

Supposons que vous commenciez avec l'élément présenté dans Expressions de condition.

{ "Id": { "N": "456"}, "Price": {"N": "650"}, "ProductCategory": {"S": "Sporting Goods"} }

L'exemple suivant effectue une opération UpdateItem. Elle tente de réduire le Price d'un produit de 75, mais l'expression de condition empêche la mise à jour si le Price actuel est inférieur à 500.

aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --update-expression "SET Price = Price - :discount" \ --condition-expression "Price > :limit" \ --expression-attribute-values file://values.json

Les arguments de la fonction --expression-attribute-values sont stockés dans le fichier values.json.

{ ":discount": { "N": "75"}, ":limit": {"N": "500"} }

Si le Price de départ est 650, l'opération UpdateItem réduit le Price à 575. Si vous exécutez à nouveau l'opération UpdateItem, le Price est réduit à 500. Si vous l'exécutez une troisième fois, l'expression de condition prend la valeur false et l'opération de mise à jour échoue.

Note

Dans l'expression de condition, le signe : (deux points) indique une valeur d'attribut d'expression, c'est-à-dire un espace réservé pour une valeur réelle. Pour de plus amples informations, veuillez consulter Valeurs d'attributs d'expressions.

Pour plus d'informations sur « > » et d'autres opérateurs, consultez Référence concernant les opérateurs et fonctions de comparaison.

Exemples d'expressions conditionnelles

Pour de plus amples informations sur les fonctions utilisées dans les exemples suivants, veuillez consulter Référence concernant les opérateurs et fonctions de comparaison. Pour en savoir plus sur la façon de spécifier différents types d'attributs dans une expression, veuillez consulter Spécification d'attributs d'élément lors de l'utilisation d'expressions.

Vérification des attributs d'un élément

Vous pouvez vérifier l'existence (ou la non existence) d'un attribut. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

L'exemple suivant utilise attribute_not_exists pour supprimer un produit uniquement s'il ne possède pas d'attribut Price.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "attribute_not_exists(Price)"

DynamoDB fournit également une fonction attribute_exists. L'exemple suivant supprime un produit uniquement si les commentaires le concernant sont négatifs.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "attribute_exists(ProductReviews.OneStar)"

Vérification du type d'attribut

Vous pouvez vérifier le type de données d'une valeur d'attribut à l'aide de la fonction attribute_type. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

L'exemple suivant utilise attribute_type pour supprimer un produit uniquement s'il possède un attribut Color de type String Set.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "attribute_type(Color, :v_sub)" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments pour --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":v_sub":{"S":"SS"} }

Vérification de la valeur de début de la chaîne

Vous pouvez vérifier si une valeur d'attribut String commence par une sous-chaîne spécifique à l'aide de la fonction begins_with. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

L'exemple suivant utilise begins_with pour supprimer un produit uniquement si l'élément FrontView de la carte Pictures commence par une valeur spécifique.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "begins_with(Pictures.FrontView, :v_sub)" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments pour --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":v_sub":{"S":"http://"} }

Recherche d'un élément dans un ensemble

Vous pouvez rechercher un élément dans un ensemble ou rechercher une sous-chaîne dans une chaîne à l'aide de la fonction contains. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

L'exemple suivant utilise contains pour supprimer un produit uniquement si l'attribut de type String Set Color comporte un élément avec une valeur spécifique.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "contains(Color, :v_sub)" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments pour --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":v_sub":{"S":"Red"} }

Vérification de la taille d'une valeur d'attribut

Vous pouvez vérifier la taille d'une valeur d'attribut à l'aide de la fonction size. Si l'expression de condition a la valeur true, l'opération aboutit. Dans le cas contraire, l'opération échoue.

L'exemple suivant utilise size pour supprimer un produit uniquement si la taille du binary attribute VideoClip est supérieure à 64000 octets.

aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{"Id": {"N": "456"}}' \ --condition-expression "size(VideoClip) > :v_sub" \ --expression-attribute-values file://expression-attribute-values.json

Les arguments pour --expression-attribute-values sont stockés dans le fichier expression-attribute-values.json.

{ ":v_sub":{"N":"64000"} }