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 plus d’informations, consultez Fonctionnement d'Amazon DynamoDB.

DynamoDB fournit quatre opérations correspondant aux fonctionnalités de base de création, lecture, mise à jour et 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 opérations CRUD de base, DynamoDB offre 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 lot peuvent associer plusieurs opérations CRUD dans une même 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 des exemples de code utilisant les AWS SDK.

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)
• 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 plus d’informations, consultez 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": "[e-mail]"},
    "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 plus d’informations, consultez 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 plus d’informations, consultez 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 plus d’informations, consultez 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":"[e-mail]"}
}

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.

Les autres paramètres valides pour ReturnValues sont les suivants, classés par opération d'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 plus d’informations, consultez 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 la mise à jour du compteur. 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'Priceattribut à 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 plus d’informations, consultez 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. Lorsque cela se produit, vous ne recevrez aucune information dans la réponse concernant la capacité d'écriture qui a été consommée. Cependant, vous pouvez consulter la ConsumedWriteCapacityUnits métrique du tableau sur Amazon CloudWatch. Pour plus d'informations, consultez Métriques DynamoDB dans Journalisation et surveillance dans DynamoDB.

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.