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. # Interrogation de tables dans DynamoDB Vous pouvez utiliser l’opération d’API `Query` dans Amazon DynamoDB pour rechercher des éléments en fonction de valeurs de clé primaire. Vous devez fournir le nom de l’attribut de clé de partition et une valeur unique pour cet attribut. `Query` retourne tous les éléments avec cette valeur de clé de partition. Vous pouvez le cas échéant fournir un attribut de clé de tri et utiliser un opérateur de comparaison pour affiner les résultats de recherche. Pour plus d’informations sur l’utilisation`Query`, tels que la syntaxe de requête, les paramètres de réponse et d’autres exemples, voir[Interrogation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)dans le*Amazon DynamoDB API Reference*. **Topics** + [ # Expressions de condition clé pour l’opération Query dans DynamoDB ](Query.KeyConditionExpressions.md) + [ # Expressions de filtre pour l’opération Query dans DynamoDB ](Query.FilterExpression.md) + [ # Pagination des résultats de requête de table dans DynamoDB ](Query.Pagination.md) + [ # Autres aspects de l’utilisation de l’opération Query dans DynamoDB ](Query.Other.md) # Expressions de condition clé pour l’opération Query dans DynamoDB Vous pouvez utiliser n’importe quel nom dans une expression de condition de clé, sous réserve que le premier caractère soit `a-z` ou `A-Z` et que les autres caractères (à compter du deuxième caractère s’il y en a un) soit `a-z`, `A-Z` ou `0-9`. En outre, le nom d’attribut ne doit pas être un mot réservé DynamoDB. (Pour en obtenir la liste complète, consultez [Mots réservés dans DynamoDB](ReservedWords.md).) Si un nom d’attribut ne répond pas à ces exigences, vous devez définir un nom d’attribut d’expression comme espace réservé. Pour de plus amples informations, veuillez consulter [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md). Pour les éléments avec une valeur de clé de partition donnée, DynamoDB stocke ces éléments proches les uns des autres, triés par valeur de clé de tri. Dans une opération `Query`, DynamoDB récupère les éléments en ordre trié, puis traite les éléments à l’aide d’une `KeyConditionExpression` et d’une `FilterExpression` éventuellement présente. Alors seulement les résultats de `Query` sont renvoyés au client. Une opération `Query` retourne toujours un ensemble de résultats. Si aucun élément correspondant n’est trouvé, le jeu de résultats est vide. Les résultats de `Query` sont toujours triés sur la valeur de la clé de tri. Si le type de données de la clé de tri est `Number`, les résultats sont retournés par ordre numérique. Sinon, les résultats sont retournés dans l’ordre des octets UTF-8. Par défaut, l’ordre de tri est croissant. Pour inverser l’ordre, définissez le paramètre `ScanIndexForward` sur `false`. Une seule opération `Query` peut extraire au maximum 1 Mo de données. Cette limite s’applique avant qu’une `FilterExpression` ou `ProjectionExpression` ne soit appliquée aux résultats. Si `LastEvaluatedKey` est présent dans la réponse et n’a pas la valeur null, vous devez paginer le jeu de résultats (voir [Pagination des résultats de requête de table dans DynamoDB](Query.Pagination.md)). ## Exemples d’expression de condition clé Pour spécifier les critères de recherche, vous utilisez une *expression de condition de clé*, c’est-à-dire une chaîne qui détermine les éléments à lire dans la table ou l’index. Vous devez spécifier le nom de la clé de partition et la valeur comme condition d’égalité. Vous ne pouvez pas utiliser d’attribut non-clé dans une expression de condition clé. Le cas échéant, vous pouvez fournir une deuxième condition pour la clé de tri (si elle est présente). La condition de la clé de tri doit être l’un des opérateurs de comparaison suivants : + `a = b`— vrai si l'attribut *a* est égal à la valeur *b* + `a < b`— vrai s'il *a* est inférieur à *b* + `a <= b`— vrai s'*a*il est inférieur ou égal à *b* + `a > b`— vrai s'il *a* est supérieur à *b* + `a >= b`— vrai s'*a*il est supérieur ou égal à *b* + `a BETWEEN b AND c`— vrai s'*a*il est supérieur ou égal à*b*, et inférieur ou égal à*c*. La fonction suivante est également prise en charge : + `begins_with (a, substr)` – True si la valeur de l’attribut `a` commence par une sous-chaîne particulière. Les exemples suivants AWS Command Line Interface (AWS CLI) illustrent l'utilisation d'expressions de conditions clés. Ces expressions utilisent des espaces réservés (tels que `:name` et `:sub`) au lieu de valeurs réelles. Pour plus d’informations, consultez [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md) et [Utilisation de valeurs d’attributs d’expression dans DynamoDB](Expressions.ExpressionAttributeValues.md). **Example** Interrogez la table `Thread` pour un `ForumName` (clé de partition) particulier. Tous les éléments ayant cette valeur `ForumName` sont lus par la requête, car la clé de tri (`Subject`) n’est pas incluse dans `KeyConditionExpression`. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name" \ --expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}' ``` **Example** Interrogez la table `Thread` en quête d’un `ForumName` (clé de partition) particulier, mais cette fois ne retournez que les éléments avec un `Subject` (clé de tri) donné. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name and Subject = :sub" \ --expression-attribute-values file://values.json ``` Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`. ``` { ":name":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"} } ``` **Example** Interrogez la table `Reply` en quête d’un `Id` (clé de partition) particulier, mais retournez uniquement les éléments dont `ReplyDateTime` (clé de tri) commence par certains caractères. ``` aws dynamodb query \ --table-name Reply \ --key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \ --expression-attribute-values file://values.json ``` Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`. ``` { ":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"}, ":dt":{"S":"2015-09"} } ``` # Expressions de filtre pour l’opération Query dans DynamoDB Si vous avez besoin d’affiner davantage les résultats de l’opération `Query`, vous pouvez fournir une expression de filtre facultative. Une *expression de filtre* détermine les éléments dans les résultats de l’opération `Query` qui doivent vous être renvoyés. Tous les autres résultats sont ignorés. Une expression de filtre est appliquée après la fin de l’opération `Query`, mais avant que les résultats soient renvoyés. Par conséquent, une opération `Query` utilise la même capacité de lecture, qu’une expression de filtre soit présente ou non. Une opération `Query` permet d’extraire au maximum 1 Mo de données. Cette limite s’applique avant que l’expression de filtre soit évaluée. Une expression de filtre ne peut pas contenir d’attributs de clé de partition ou de clé de tri. Vous devez préciser ces attributs dans l’expression de condition de clé, pas dans l’expression de filtre. La syntaxe d’un expression de filtre est similaire à celle d’une expression de condition de clé. Les expressions de filtre peuvent utiliser les mêmes comparateurs, fonctions et opérateurs logiques qu’une expression de condition de clé. En outre, les expressions de filtre peuvent utiliser l’opérateur non égal (`<>`), l’opérateur `OR`, l’opérateur `CONTAINS`, l’opérateur `IN`, l’opérateur `BEGINS_WITH`, l’opérateur `BETWEEN`, l’opérateur `EXISTS` et l’opérateur `SIZE`. Pour plus d’informations, consultez [Expressions de condition clé pour l’opération Query dans DynamoDB](Query.KeyConditionExpressions.md) et [Syntaxe des expressions de filtre et de condition](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax). **Example** L' AWS CLI exemple suivant interroge la `Thread` table pour une `ForumName` (clé de partition) et une `Subject` (clé de tri) particulières. Parmi les éléments trouvés, seules les unités d’exécution de discussion les plus populaires sont renvoyés, c’est-à-dire les threads ayant plus qu’un certain nombre de `Views`. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject begins_with :sub" \ --filter-expression "#v >= :num" \ --expression-attribute-names '{"#v": "Views"}' \ --expression-attribute-values file://values.json ``` Les arguments de la fonction `--expression-attribute-values` sont stockés dans le fichier `values.json`. ``` { ":fn":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"}, ":num":{"N":"3"} } ``` Notez que `Views` étant un mot réservé dans DynamoDB (consultez [Mots réservés dans DynamoDB](ReservedWords.md)), cet exemple utilise `#v` comme espace réservé. Pour de plus amples informations, veuillez consulter [Noms d’attributs d’expression (alias) dans DynamoDB](Expressions.ExpressionAttributeNames.md). **Note** Une expression de filtre supprime des éléments du jeu de résultats de `Query`. Dans la mesure du possible, évitez d’utiliser `Query` lorsque vous pensez extraire un grand nombre d’éléments mais que vous devrez en supprimer une grande partie. # Pagination des résultats de requête de table dans DynamoDB DynamoDB *pagine* les résultats des opérations `Query`. Avec la pagination, les résultats de l’opération `Query` sont répartis en « pages » de données d’une taille maximum de 1 Mo. Une application peut traiter la première page des résultats, puis la deuxième, et ainsi de suite. Une opération `Query` retourne uniquement un ensemble de résultats correspondant à la limite de taille de 1 Mo. Pour déterminer si le nombre de résultats est plus important et pour récupérer une page à la fois, les applications doivent procéder de la manière suivante : 1. Examinez le résultat de l’opération `Query` de niveau inférieur : + Si le résultat contient un élément `LastEvaluatedKey` dont la valeur n’est pas null, passez à l’étape 2. + S’il n’y a *pas* de `LastEvaluatedKey` dans le résultat, il n’y a plus aucun élément à récupérer. 1. Construisez une `Query` avec la même `KeyConditionExpression`. Cependant, cette fois, acceptez la valeur `LastEvaluatedKey` de l’étape 1 et utilisez-la comme paramètre `ExclusiveStartKey` dans la nouvelle demande `Query`. 1. Exécutez la nouvelle demande `Query`. 1. Passez à l’étape 1. En d’autres termes, l’élément `LastEvaluatedKey` provenant d’une réponse `Query` doit être utilisé comme `ExclusiveStartKey` pour la demande `Query` suivante. Si aucun élément `LastEvaluatedKey` n’est présent dans la réponse `Query`, vous avez extrait la dernière page de résultats. Si `LastEvaluatedKey` n’est pas vide, cela ne signifie pas nécessairement qu’il y a plus de données dans le jeu de résultats. Le seul moyen de savoir que vous avez atteint la fin du jeu de résultats est lorsque `LastEvaluatedKey` est vide. Vous pouvez utiliser le AWS CLI pour visualiser ce comportement. AWS CLI envoie des `Query` requêtes de bas niveau à DynamoDB à plusieurs reprises, `LastEvaluatedKey` jusqu'à ce qu'elles ne soient plus présentes dans les résultats. Prenons l' AWS CLI exemple suivant qui récupère les titres de films d'une année donnée. ``` aws dynamodb query --table-name Movies \ --projection-expression "title" \ --key-condition-expression "#y = :yyyy" \ --expression-attribute-names '{"#y":"year"}' \ --expression-attribute-values '{":yyyy":{"N":"1993"}}' \ --page-size 5 \ --debug ``` Normalement, il AWS CLI gère automatiquement la pagination. Toutefois, dans cet exemple, le AWS CLI `--page-size` paramètre limite le nombre d'éléments par page. La paramètre `--debug` imprime les informations de bas niveau relatives aux demandes et aux réponses. Si vous exécutez l’exemple, la première réponse de DynamoDB est à similaire à ce qui suit. ``` 2017-07-07 11:13:15,603 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":5,"Items":[{"title":{"S":"A Bronx Tale"}}, {"title":{"S":"A Perfect World"}},{"title":{"S":"Addams Family Values"}}, {"title":{"S":"Alive"}},{"title":{"S":"Benny & Joon"}}], "LastEvaluatedKey":{"year":{"N":"1993"},"title":{"S":"Benny & Joon"}}, "ScannedCount":5}' ``` Le `LastEvaluatedKey` de la réponse indique que certains éléments n’ont pas été récupérés. Il envoie AWS CLI ensuite une autre `Query` demande à DynamoDB. Ce modèle de requête et de réponse se poursuit jusqu’à l’obtention d’une réponse finale. ``` 2017-07-07 11:13:16,291 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":1,"Items":[{"title":{"S":"What\'s Eating Gilbert Grape"}}],"ScannedCount":1}' ``` L’absence de `LastEvaluatedKey` indique qu’il n’y a pas plus de d’élément à récupérer. **Note** Ils AWS SDKs gèrent les réponses DynamoDB de bas niveau (y compris la présence ou l'absence de) et fournissent diverses abstractions pour `LastEvaluatedKey` la pagination des résultats. `Query` Par exemple, l’interface de document du kit SDK pour Java fournit le support `java.util.Iterator` pour vous permettre de parcourir les résultats un par un. Pour des exemples de code dans divers langages de programmation, consultez le [Guide de prise en main d’Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) et la documentation du kit SDK  AWS pour votre langage. Vous pouvez également réduire la taille de la page en limitant le nombre d’éléments dans l’ensemble de résultats, avec le paramètre `Limit` de l’opération `Query`. Pour plus d’informations sur l’interrogation avec DynamoDB, consultez [Interrogation de tables dans DynamoDB](Query.md). # Autres aspects de l’utilisation de l’opération Query dans DynamoDB Cette section couvre d’autres aspects de l’opération Query DynamoDB, notamment la limitation de la taille des résultats, le comptage des éléments analysés par rapport aux éléments renvoyés, la surveillance de la consommation de capacité de lecture et le contrôle de la cohérence en lecture. ## Limiter le nombre d’éléments dans le jeu de résultats Avec l’opération `Query`, vous pouvez limiter le nombre d’éléments qu’elle lit. Pour ce faire, définissez le paramètre `Limit` sur le nombre maximal d’éléments souhaité. Par exemple, supposons que vous effectuiez une opération `Query` sur une table, avec une valeur `Limit` de `6` et sans expression de filtre. Le résultat `Query` contient les six premiers éléments de la table qui correspondent à l’expression de condition de clé de la demande. Supposons maintenant que vous ajoutiez une expression de filtre à l’opération `Query`. Dans ce cas, DynamoDB lit jusqu’à six éléments, puis renvoie uniquement ceux qui correspondent à l’expression de filtre. Le résultat `Query` final contient au maximum six éléments, même si davantage d’éléments auraient correspondu à l’expression de filtre si DynamoDB avait continué à lire plus d’éléments. ## Comptabilisation des éléments dans les résultats Outre les éléments qui correspondent à vos critères, la réponse d’une opération `Query` contient les éléments suivants : + `ScannedCount` – Nombre d’éléments qui correspondaient à l’expression de condition de clé *avant* qu’une expression de filtre (le cas échéant) soit appliquée. + `Count` – Nombre d’éléments qui restent *après* l’application d’une expression de filtre (le cas échéant). **Note** Si vous n’utilisez pas d’expression de filtre, alors `ScannedCount` et `Count` ont la même valeur. Si la taille de l’ensemble de résultats `Query` est supérieure à 1 Mo, les opérations `ScannedCount` et `Count` représentent seulement un compte partiel du total des éléments. Vous devez effectuer plusieurs opérations `Query` pour extraire tous les résultats. (Consultez [Pagination des résultats de requête de table dans DynamoDB](Query.Pagination.md).) Chaque réponse `Query` comporte les `ScannedCount` et `Count` des éléments traités par cette demande `Query` particulière. Pour obtenir les totaux de toutes les demandes `Query`, vous pouvez garder un compte actif de `ScannedCount` et de `Count`. ## Unités de capacité consommées par la requête Vous pouvez interroger n’importe quelle table ou n’importe quel index secondaire avec `Query`, à condition de fournir le nom de l’attribut de clé de partition et une valeur unique pour cet attribut. `Query` renvoie tous les éléments contenant cette valeur de clé de partition. Vous pouvez éventuellement fournir un attribut de clé de tri et utiliser un opérateur de comparaison pour affiner les résultats de recherche. Les opérations d’API `Query` consomment des unités de capacité de lecture, comme suit. **** | Si vous effectuez une opération `Query` sur… | DynamoDB consomme des unités de capacité de lecture de… | | --- | --- | | Table | Capacité de lecture allouée de la table. | | GSI | Capacité de lecture allouée à l’index. | | Index secondaire local | Capacité de lecture allouée de la table de base. | Par défaut, l’opération `Query` ne renvoie pas de données concernant la consommation de capacité de lecture. Vous pouvez toutefois spécifier le paramètre `ReturnConsumedCapacity` dans une demande `Query` pour obtenir ces informations. Voici les paramètres valides pour `ReturnConsumedCapacity` : + `NONE` – Aucune donnée de capacité consommée n’est renvoyée. (Il s’agit de l’option par défaut.) + `TOTAL` – La réponse inclut le nombre agrégé d’unités de capacité de lecture consommées. + `INDEXES` – La réponse indique le nombre agrégé d’unités de capacité de lecture consommées, ainsi que la capacité consommée pour chaque table et index consultés. DynamoDB calcule le nombre d’unités de capacité de lecture consommées en fonction du nombre d’éléments et de la taille de ces éléments, et non du volume de données renvoyées à une application. Pour cette raison, le nombre d’unités de capacité consommées sera le même que vous demandiez tous les attributs (comportement par défaut) ou seulement certains d’entre eux (avec une expression de projection). Le nombre est également le même, que vous utilisiez ou non une expression de filtre. `Query` consomme une unité de capacité de lecture minimale pour effectuer une lecture fortement cohérente par seconde ou deux lectures cohérentes à terme par seconde pour un élément d’une taille maximale de 4 Ko. Si vous devez lire un élément d’une taille supérieure à 4 Ko, DynamoDB a besoin d’unités de demande de lecture supplémentaires. Les tables vides et les très grandes tables contenant peu de clés de partition peuvent entraîner des RCUs frais supplémentaires au-delà de la quantité de données demandées. Cela couvre les frais de traitement de la demande `Query`, même en l’absence de données. ## Cohérence en lecture de la requête Par défaut, une opération `Query` effectue des lectures cohérentes à terme. Autrement dit, les résultats de l’opération `Query` peuvent ne pas refléter des modifications apportées par des opérations `PutItem` ou `UpdateItem` récentes. Pour de plus amples informations, veuillez consulter [Cohérence en lecture DynamoDB](HowItWorks.ReadConsistency.md). Si vous avez besoin de lectures fortement cohérentes, définissez le paramètre `ConsistentRead` sur `true` dans la demande `Query`.