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 des éléments et des attributs
Dans Amazon DynamoDB, un élément est une collection d'attributs. Chaque attribut a un nom et une valeur. Une valeur d'attribut peut être de type scalar, set ou document. Pour de plus amples informations, veuillez consulter Fonctionnement d'Amazon DynamoDB.
DynamoDB propose quatre opérations pour les fonctionnalités de base de création, de lecture, de mise à jour et de suppression CRUD (). Toutes ces opérations sont atomiques.
-
PutItem
– Création d'un élément. -
GetItem
– Lecture d'un élément. -
UpdateItem
– Mise à jour d'un élément. -
DeleteItem
– Suppression d'un élément.
Pour chacune de ces opérations, vous devez indiquer la clé primaire de l'élément que vous souhaitez utiliser. Par exemple, pour lire un élément avec GetItem
, vous devez spécifier la clé de partition et la clé de tri (le cas échéant) de cet élément.
Outre les quatre CRUD opérations de base, DynamoDB fournit également les fonctionnalités suivantes :
-
BatchGetItem
– Lecture de 100 éléments au plus à partir d'une ou de plusieurs tables. -
BatchWriteItem
– Création ou suppression de 25 éléments au plus dans une ou plusieurs tables.
Ces opérations par lots combinent plusieurs CRUD opérations en une seule demande. En outre, les opérations par lot lisent et écrivent des éléments en parallèle afin de réduire les latences de réponse.
Cette section explique comment utiliser ces opérations. Elle comprend des rubriques connexes, telles que les mises à jour conditionnelles et les compteurs atomiques. Cette section inclut également un exemple de code utilisant le AWS SDKs.
Rubriques
- Lecture d'un élément
- Écriture d'un élément
- Valeurs de retour
- Opérations par lot
- Compteurs atomiques
- Écritures conditionnelles
- Utilisation d'expressions dans DynamoDB
- Time to Live (TTL)
- Interrogation de tables dans DynamoDB
- Numérisation de tables dans DynamoDB
- PartiQL – Langage de requête compatible SQL pour Amazon DynamoDB
- Utilisation des éléments : Java
- Utilisation des élements : .NET
Lecture d'un élément
Pour lire un élément à partir d'une table DynamoDB, utilisez l'opération GetItem
. Vous devez fournir le nom de la table, ainsi que la clé primaire de l'élément que vous voulez.
Exemple
L' AWS CLI exemple suivant montre comment lire un élément du ProductCatalog
tableau.
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}'
Note
Avec GetItem
, vous devez spécifier la totalité de la clé primaire, pas simplement une partie. Par exemple, si une table possède une clé primaire composite (clé de partition et clé de tri), vous devez fournir une valeur pour la clé de partition et une valeur pour la clé de tri.
Une demande GetItem
effectue une lecture éventuellement cohérente (eventually consistent) par défaut. Vous pouvez utiliser le paramètre ConsistentRead
pour demander une lecture fortement cohérente à la place. (Cela consomme des unités de capacité de lecture supplémentaires, mais renvoie la up-to-date version la plus complète de l'article.)
GetItem
retourne tous les attributs de l'élément. Vous pouvez utiliser une expression de projection pour renvoyer uniquement certains des attributs. Pour de plus amples informations, veuillez consulter Expressions de projections.
Pour renvoyer le nombre d'unités de capacité de lecture consommées par l'opération GetItem
, définissez le paramètre ReturnConsumedCapacity
sur la valeur TOTAL
.
Exemple
L'exemple suivant AWS Command Line Interface (AWS CLI) montre certains des GetItem
paramètres facultatifs.
aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL
Écriture d'un élément
Pour créer, mettre à jour ou supprimer un élément dans une table DynamoDB, utilisez l'une des opérations suivantes :
-
PutItem
-
UpdateItem
-
DeleteItem
Pour chacune de ces opérations, vous devez spécifier la totalité de la clé primaire, pas simplement une partie. Par exemple, si une table possède une clé primaire composite (clé de partition et clé de tri), vous devez fournir une valeur pour la clé de partition et une valeur pour la clé de tri.
Pour renvoyer le nombre d'unités de capacité d'écriture consommées par l'une de ces opérations, définissez le paramètre ReturnConsumedCapacity
sur l'une des valeurs suivantes :
-
TOTAL
– Renvoie le nombre total d'unités de capacité d'écriture consommées. -
INDEXES
– Renvoie le nombre total d'unités de capacité de lecture consommées, avec les sous-totaux correspondant à la table et aux index secondaires concernés par l'opération. -
NONE
– Aucun détail concernant la capacité d'écriture n'est renvoyé. (Il s'agit de l'option par défaut.)
PutItem
PutItem
crée un élément. Si un élément avec la même clé existe déjà dans la table, il est remplacé par le nouvel élément.
Exemple
Écrivez un nouvel élément dans la table Thread
. La clé primaire de la table Thread
est composée de ForumName
(clé de partition) et Subject
(clé de tri).
aws dynamodb put-item \ --table-name Thread \ --item file://item.json
Les arguments de la fonction --item
sont stockés dans le fichier item.json
.
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} }
UpdateItem
S'il n'existe aucun élément associé à la clé spécifiée, UpdateItem
en crée un. Dans le cas contraire, l'opération modifie les attributs d'un élément existant.
Vous utilisez une expression de mise à jour pour préciser les attributs à modifier, ainsi que leurs nouvelles valeurs. Pour de plus amples informations, veuillez consulter Expressions de mise à jour.
Au sein de l'expression de mise à jour, vous utilisez des valeurs d'attributs d'expressions comme espaces réservés pour les valeurs réelles. Pour de plus amples informations, veuillez consulter Valeurs d'attributs d'expressions.
Exemple
Modifiez plusieurs attributs dans l'élément Thread
. Le paramètre ReturnValues
facultatif présente l'élément tel qu'il apparaît après la mise à jour. Pour de plus amples informations, veuillez consulter Valeurs de retour.
aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW
Les arguments de la fonction --key
sont stockés dans le fichier key.json
.
{ "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} }
Les arguments de la fonction --expression-attribute-values
sont stockés dans le fichier expression-attribute-values.json
.
{ ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} }
DeleteItem
DeleteItem
supprime l'élément avec la clé spécifiée.
Exemple
L' AWS CLI exemple suivant montre comment supprimer l'Thread
élément.
aws dynamodb delete-item \ --table-name Thread \ --key file://key.json
Valeurs de retour
Dans certains cas, vous souhaitez que DynamoDB renvoie certaines valeurs d'attribut telles qu'elles apparaissent avant ou après leur modification. Les opérations PutItem
, UpdateItem
et DeleteItem
ont un paramètre ReturnValues
que vous pouvez utiliser pour renvoyer les valeurs d'attribut avant ou après leur modification.
La valeur par défaut de ReturnValues
est NONE
, ce qui signifie que DynamoDB ne renvoie aucune information concernant les attributs qui ont été modifiés.
Voici les autres paramètres valides pourReturnValues
, organisés par opération API DynamoDB.
PutItem
-
ReturnValues
:ALL_OLD
-
Si vous remplacez un élément existant,
ALL_OLD
renvoie l'élément entier tel qu'il apparaissait avant son remplacement. -
Si vous écrivez un élément qui n'existe pas,
ALL_OLD
n'a aucun effet.
-
UpdateItem
L'utilisation la plus courante d'UpdateItem
est la mise à jour d'un élément existant. Cependant, UpdateItem
effectue une opération de mise à jour/insertion, ce qui signifie qu'il crée automatiquement l'élément si celui-ci n'existe pas.
-
ReturnValues
:ALL_OLD
-
Si vous mettez à jour un élément existant,
ALL_OLD
renvoie l'élément entier tel qu'il apparaissait avant sa mise à jour. -
Si vous mettez à jour un élément qui n'existe pas (upsert),
ALL_OLD
n'a aucun effet.
-
-
ReturnValues
:ALL_NEW
-
Si vous mettez à jour un élément existant,
ALL_NEW
renvoie l'élément entier tel qu'il apparaît après la mise à jour. -
Si vous mettez à jour un élément qui n'existe pas (upsert),
ALL_NEW
renvoie l'élément entier.
-
-
ReturnValues
:UPDATED_OLD
-
Si vous mettez à jour un élément existant,
UPDATED_OLD
renvoie uniquement les attributs mis à jour tels qu'ils apparaissaient avant leur mise à jour. -
Si vous mettez à jour un élément qui n'existe pas (upsert),
UPDATED_OLD
n'a aucun effet.
-
-
ReturnValues
:UPDATED_NEW
-
Si vous mettez à jour un élément existant,
UPDATED_NEW
renvoie uniquement les attributs affectés tels qu'ils apparaissaient après leur mise à jour. -
Si vous mettez à jour (upsert) un élément qui n'existe pas,
UPDATED_NEW
renvoie uniquement les attributs mis à jour tels qu'ils apparaissent après la mise à jour.
-
DeleteItem
-
ReturnValues
:ALL_OLD
-
Si vous supprimez un élément existant,
ALL_OLD
renvoie l'élément entier tel qu'il apparaissait avant sa suppression. -
Si vous supprimez un élément qui n'existe pas,
ALL_OLD
ne renvoie pas de données.
-
Opérations par lot
Pour les applications ayant besoin de lire ou d'écrire plusieurs éléments, DynamoDB fournit les opérations BatchGetItem
et BatchWriteItem
. L'utilisation de ces opérations peut réduire le nombre d'allers et retours réseau entre votre application et DynamoDB. En outre, DynamoDB effectue les opérations de lecture ou d'écriture individuelles en parallèle. Vos applications bénéficient de ce parallélisme sans devoir gérer la simultanéité ou les threads.
Les opérations par lot sont essentiellement des wrappers autour de plusieurs demandes de lecture ou d'écriture. Par exemple, si une demande BatchGetItem
contient cinq éléments, DynamoDB exécute cinq opérations GetItem
pour vous. De même, si une demande BatchWriteItem
contient deux demandes d'insertion et quatre demandes de suppression, DynamoDB exécute deux demandes PutItem
et quatre demandes DeleteItem
.
En général, une opération de traitement par lots n'échoue pas, sauf si toutes les demandes du traitement par lots échouent. Supposons, par exemple, que vous effectuiez une opération BatchGetItem
, mais que l'une des demandes GetItem
du lot échoue. Dans ce cas, BatchGetItem
renvoie les clés et les données provenant de la demande GetItem
qui a échoué. Les autres demandes GetItem
du lot ne sont pas affectées.
BatchGetItem
Une seule opération BatchGetItem
peut contenir jusqu'à 100 demandes GetItem
individuelles, et peuvent extraire jusqu'à 16 Mo de données. En outre, une opération BatchGetItem
peut extraire les éléments de plusieurs tables.
Exemple
Extrayez deux éléments de la table Thread
en utilisant une expression de projection pour renvoyer uniquement certains des attributs.
aws dynamodb batch-get-item \ --request-items file://request-items.json
Les arguments de la fonction --request-items
sont stockés dans le fichier request-items.json
.
{ "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } }
BatchWriteItem
L'opération BatchWriteItem
peut contenir jusqu'à 25 demandes PutItem
et DeleteItem
individuelles, et peut écrire jusqu'à 16 Mo de données (la taille maximale d'un élément est de 400 Ko). En outre, une même opération BatchWriteItem
peut insérer ou supprimer les éléments de plusieurs tables.
Note
BatchWriteItem
ne prend pas en charge les demandes UpdateItem
.
Exemple
Ajoute deux éléments à la table ProductCatalog
.
aws dynamodb batch-write-item \ --request-items file://request-items.json
Les arguments de la fonction --request-items
sont stockés dans le fichier request-items.json
.
{ "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] }
Compteurs atomiques
Vous pouvez utiliser l'opération UpdateItem
pour implémenter un compteur atomique, c'est-à-dire un attribut numérique incrémenté sans condition, sans interférer avec d'autres demandes d'écriture. (Toutes les demandes d'écriture sont appliquées dans l'ordre dans lequel elles ont été reçues.) Avec un compteur atomique, les mises à jour ne sont pas idempotentes. En d'autres termes, la valeur numérique augmente ou diminue chaque fois que vous appelez UpdateItem
. Si la valeur d'incrément utilisée pour mettre à jour le compteur atomique est positive, cela peut provoquer un surcomptage. Si la valeur d'incrément est négative, cela peut entraîner une sous-estimation.
Vous pouvez utiliser un compteur atomique pour suivre le nombre de visiteurs d'un site web. Dans ce cas, l'application doit incrémenter une valeur numérique, quelle que soit sa valeur actuelle. En cas d'échec d'une opération UpdateItem
, l'application peut simplement retenter l'opération. Cela risquerait de mettre à jour le compteur deux fois, mais vous pourriez probablement tolérer de sur-comptabiliser ou sous-comptabiliser légèrement les visiteurs.
Dans le cas contraire, l'utilisation d'un compteur automatique n'est pas adaptée (par exemple, dans une application bancaire). Il est alors plus sûr d'utiliser une mise à jour conditionnelle plutôt qu'un compteur atomique.
Pour de plus amples informations, veuillez consulter Incrémentation et décrémentation d'attributs numériques.
Exemple
L' AWS CLI exemple suivant augmente la valeur Price
d'un produit de 5. Dans cet exemple, l'existence de l'article était connue avant que le compteur ne soit mis à jour. Puisque l'opération UpdateItem
n'est pas idempotente, le Price
augmente à chaque exécution de ce code.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW
Écritures conditionnelles
Par défaut, les opérations d'écriture de DynamoDB (PutItem
, UpdateItem
, DeleteItem
) sont sans condition : chacune remplace un élément existant doté de la clé primaire spécifiée.
DynamoDB prend en charge, en option, les écritures conditionnelles pour ces opérations. Une écriture conditionnelle réussit uniquement si les attributs de l'élément satisfont une ou plusieurs conditions prévues. Dans le cas contraire, elle renvoie une erreur.
Les écritures conditionnelles vérifient leurs conditions par rapport à la dernière version mise à jour de l'élément. Notez que si l'élément n'existait pas auparavant ou si la dernière opération réussie sur cet élément a été une suppression, l'écriture conditionnelle ne trouvera aucun élément précédent.
Les écritures conditionnelles sont utiles dans de nombreux cas. Par exemple, vous pouvez décider qu'une opération PutItem
ne réussit que si aucun élément avec la même clé primaire n'existe déjà. Vous pouvez également empêcher une opération UpdateItem
de modifier un élément si l'un de ses attributs possède une valeur donnée.
Les écritures conditionnelles sont utiles dans les cas où plusieurs utilisateurs tentent de modifier le même élément. Examinez le diagramme suivant, dans lequel deux utilisateurs (Alice et Bob) utilisent le même élément provenant d'une table DynamoDB.
Supposons qu'Alice utilise le AWS CLI pour mettre à jour l'Price
attribut à 8.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json
Les arguments de la fonction --expression-attribute-values
sont stockés dans le fichier expression-attribute-values.json
:
{ ":newval":{"N":"8"} }
Supposons maintenant que Bob émette une demande UpdateItem
similaire ultérieurement, mais qu'il change la valeur de Price
en 12. Pour Bob, le paramètre --expression-attribute-values
prend la forme suivante.
{ ":newval":{"N":"12"} }
La demande de Bob aboutit, mais la mise à jour précédente d'Alice est perdue.
Pour demander une opération PutItem
, DeleteItem
ou UpdateItem
conditionnelle, vous spécifiez une expression de condition. Une expression de condition est une chaîne contenant des noms d'attributs, des opérateurs conditionnels et des fonctions intégrées. L'expression entière doit avoir la valeur true. Sinon, l'opération échoue.
Examinez maintenant le diagramme suivant, qui présente les écritures conditionnelles qui empêcheraient le remplacement de la mise à jour d'Alice.
Alice tente dans un premier temps de mettre à jour Price
avec la valeur 8, mais uniquement si la valeur actuelle de Price
est 10.
aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json
Les arguments de la fonction --expression-attribute-values
sont stockés dans le fichier expression-attribute-values.json
.
{ ":newval":{"N":"8"}, ":currval":{"N":"10"} }
La mise à jour d'Alice aboutit, car la condition a la valeur true.
Ensuite, Bob tente de mettre à jour la valeur de Price
à 12, mais uniquement si le Price
actuel est 10. Pour Bob, le paramètre --expression-attribute-values
prend la forme suivante.
{ ":newval":{"N":"12"}, ":currval":{"N":"10"} }
Comme Alice a précédemment modifié la valeur de Price
en 8, l'expression de condition prend la valeur false et la mise à jour de Bob échoue.
Pour de plus amples informations, veuillez consulter Expressions de condition.
Idempotence d'écriture conditionnelle
Les écritures conditionnelles peuvent être idempotentes si la vérification conditionnelle porte sur le même attribut que celui mis à jour. Cela signifie que DynamoDB effectue une demande d'écriture donnée uniquement si certaines valeurs d'attribut dans l'élément correspondent à ce que attendez au moment de la demande.
Par exemple, supposons que vous émettiez une demande UpdateItem
pour augmenter le Price
d'un article de 3, mais uniquement si le Price
actuel est 20. Après l'envoi de la demande, mais avant que vous n'obteniez les résultats, une erreur réseau se produit et vous ne savez pas si votre demande a abouti ou non. Cette écriture conditionnelle étant idempotente, vous pouvez relancer la même demande UpdateItem
, et DynamoDB met à jour l'élément uniquement si la valeur Price
est actuellement 20.
Unités de capacité consommées par les écritures conditionnelles
Si une ConditionExpression
prend la valeur false pendant une écriture conditionnelle, DynamoDB continue à utiliser la capacité d'écriture de la table. La quantité consommée dépend de la taille de l'élément existant (ou valeur minimale de 1). Par exemple, si un élément existant fait 300 Ko et que l'élément que vous essayez de créer ou de mettre à jour fait 310 Ko, les unités de capacité d'écriture consommées seront de 300 Ko si la condition n'est pas remplie et de 310 si elle est remplie. S'il s'agit d'un nouvel élément (élément non existant), les unités de capacité d'écriture consommées seront de 1 si la condition n'est pas remplie et de 310 si elle est remplie.
Note
Les opérations d'écriture consomment uniquement des unités de capacité d'écriture. Elles n'utilisent jamais d'unités de capacité de lecture.
Une écriture conditionnelle ayant échoué retourne un ConditionalCheckFailedException
. Dans ce cas, vous ne recevez aucune information dans la réponse concernant la capacité d'écriture consommée.
Pour renvoyer le nombre d'unités de capacité d'écriture utilisées au cours d'une écriture conditionnelle, utilisez le paramètre ReturnConsumedCapacity
:
-
TOTAL
– Renvoie le nombre total d'unités de capacité d'écriture consommées. -
INDEXES
– Renvoie le nombre total d'unités de capacité de lecture consommées, avec les sous-totaux correspondant à la table et aux index secondaires concernés par l'opération. -
NONE
– Aucun détail concernant la capacité d'écriture n'est renvoyé. (Il s'agit de l'option par défaut.)
Note
Contrairement à un index secondaire global, un index secondaire local partage sa capacité de débit approvisionné avec sa table. L'activité de lecture et d'écriture sur un index secondaire local consomme la capacité de débit approvisionné de la table.