Description Requêtes Réponses Erreurs spéciales Exemples Actions connexes

Requête

Important

Cette section fait référence à l'API version 2011-12-05 qui est obsolète et ne doit pas être utilisée pour de nouvelles applications.

Pour une documentation sur l'API de bas niveau actuelle, consultez la Référence d'API Amazon DynamoDB.

Description

Une Query opération obtient les valeurs d'un ou de plusieurs éléments et leurs attributs par clé primaire (Querydisponible uniquement pour les tables de clés hash-and-range primaires). Vous devez indiquer une HashKeyValue spécifique, et pouvez restreindre la portée de la requête à l'aide d'opérateurs de comparaison sur la RangeKeyValue de la clé primaire. Utilisez le paramètre ScanIndexForward pour obtenir les résultats dans l'ordre croissant ou inverse par clé de plage.

Les requêtes qui ne renvoient pas de résultat consomment les unités de capacité de lecture minimum en fonction du type de lecture.

Note

Si le nombre total d'éléments correspondant aux paramètres de requête dépasse la limite de 1 Mo, la requête s'arrête et les résultats sont renvoyés à l'utilisateur avec une LastEvaluatedKey pour continuer la requête dans une opération subséquente. Contrairement à une opération d'analyse, une opération de requête ne renvoie jamais un ensemble de résultats vide et une valeur LastEvaluatedKey. La valeur LastEvaluatedKey n'est fournie que si les résultats dépassent 1 Mo ou si vous avez utilisé le paramètre Limit.

Le résultat peut être défini pour une lecture cohérente à l'aide du paramètre ConsistentRead.

Requêtes

Syntaxe


// This header is abbreviated.
// For a sample of a complete header, see DynamoDB de bas niveau API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query  
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
	"Limit":2,
	"ConsistentRead":true,
	"HashKeyValue":{"S":"AttributeValue1":},
	"RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"}
	"ScanIndexForward":true,
	"ExclusiveStartKey":{
		"HashKeyElement":{"S":"AttributeName1"},
		"RangeKeyElement":{"N":"AttributeName2"}
	},
    "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
}

Name (Nom)	Description	Obligatoire
`TableName`	Nom de la table contenant les éléments demandés. Type : chaîne	Oui
`AttributesToGet`	Tableau de noms d'attribut. Si des noms d'attribut ne sont pas spécifiés, tous les attributs sont renvoyés. Si certains attributs ne sont pas trouvés, ils n'apparaissent pas dans le résultat. Type : Array	Non
`Limit`	Nombre maximum d'éléments à renvoyer (pas nécessairement le nombre d'éléments correspondants). Si DynamoDB traite le nombre d'éléments jusqu'à la limite lors de l'interrogation de la table, il arrête la requête et renvoie les valeurs correspondantes jusqu'à ce point, ainsi qu'une valeur `LastEvaluatedKey` à appliquer dans une opération subséquente pour continuer la requête. Par ailleurs, si la taille de l'ensemble de résultats dépasse 1 Mo avant que DynamoDB atteigne cette limite, DynamoDB arrête la requête et renvoie les valeurs correspondantes, ainsi qu'une valeur `LastEvaluatedKey` à appliquer dans une opération subséquente pour continuer la requête. Type : nombre	Non
`ConsistentRead`	Si la valeur est définie sur `true`, une lecture cohérente est effectuée. Sinon une cohérence éventuelle est utilisée. Type : booléen	Non
`Count`	Si la valeur est définie sur `true`, DynamoDB renvoie un nombre total d'éléments qui correspondent aux paramètres de requête, au lieu d'une liste des éléments correspondants et de leurs attributs. Vous pouvez appliquer le paramètre `Limit` aux requêtes de nombre uniquement. Ne pas définissez pas la valeur `Count` sur `true` tout en fournissant une liste `AttributesToGet`. Sinon, DynamoDB renvoie une erreur de validation. Pour plus d’informations, consultez Comptabilisation des éléments dans les résultats. Type : booléen	Non
`HashKeyValue`	Valeur d'attribut du composant de hachage de la clé primaire composite. Type : chaîne, nombre ou binaire	Oui
`RangeKeyCondition`	Conteneur pour les valeurs d'attribut et les opérateurs de comparaison à utiliser pour la requête. Une demande de requête ne nécessite pas de `RangeKeyCondition`. Si vous fournissez uniquement la valeur `HashKeyValue`, DynamoDB renvoie tous les éléments avec la valeur d'élément de clé de hachage spécifiée. Type : carte	Non
`RangeKeyCondition`: `AttributeValueList`	Valeurs d'attribut à évaluer pour les paramètres de requête. La `AttributeValueList` contient une valeur d'attribut, sauf si une comparaison `BETWEEN` est spécifiée. Pour la comparaison `BETWEEN`, la `AttributeValueList` contient deux valeurs d'attribut. Type : mappage de `AttributeValue` à un `ComparisonOperator`.	Non
`RangeKeyCondition`: `ComparisonOperator`	Critères d'évaluation des attributs fournis, tels que Egal à, Supérieur à, etc. Les opérateurs de comparaison valides pour une opération de requête sont les suivants. Note Les comparaisons de valeurs de chaîne pour les critères Supérieur à, Egal à ou Inférieur à sont basées sur des valeurs de code de caractère ASCII. Par exemple, `a` est supérieur à `A`, et `aa` est supérieur à `B`. Pour obtenir la liste des valeurs des codes, consultez http://fr.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange. Pour une valeur binaire, DynamoDB traite chaque octet des données binaires comme non signé quand il compare des valeurs binaires, par exemple, lors de l'évaluation d'expressions de requête. Type : chaîne ou binaire	Non
	`EQ` : égal. Pour `EQ`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type Chaîne, Nombre ou Binaire (et non Ensemble). Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas égal à `{"N":"6"}`. De même, `{"N":"6"}` n'est pas égal à `{"NS":["6", "2", "1"]}`.
	`LE` : inférieur ou égal. Pour `LE`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type Chaîne, Nombre ou Binaire (et non Ensemble). Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas égal à `{"N":"6"}`. De même, `{"N":"6"}` n'est pas comparable à `{"NS":["6", "2", "1"]}`.
	`LT` : inférieur. Pour `LT`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type Chaîne, Nombre ou Binaire (et non Ensemble). Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas égal à `{"N":"6"}`. De même, `{"N":"6"}` ne se compare pas à `{"NS":["6", "2", "1"]}`.
	`GE` : supérieur ou égal. Pour `GE`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type Chaîne, Nombre ou Binaire (et non Ensemble). Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas égal à `{"N":"6"}`. De même, `{"N":"6"}` ne se compare pas à `{"NS":["6", "2", "1"]}`.
	`GT` : supérieur. Pour `GT`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type Chaîne, Nombre ou Binaire (et non Ensemble). Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas égal à `{"N":"6"}`. De même, `{"N":"6"}` n'est pas comparable à `{"NS":["6", "2", "1"]}`.
	`BEGINS_WITH` : recherche un préfixe. Pour `BEGINS_WITH`, `AttributeValueList` ne peut contenir qu'une seule `AttributeValue` de type chaîne ou binaire (pas nombre ou ensemble). L'attribut cible de la comparaison doit être une chaîne ou un binaire (pas un nombre ou un ensemble).
	`BETWEEN` : supérieur ou égal à la première valeur, et inférieur ou égal à la deuxième valeur. Pour `BETWEEN`, `AttributeValueList` doit inclure deux éléments `AttributeValue` du même type, Chaîne, Nombre ou Binaire (et non Ensemble). Un attribut cible correspond si la valeur cible est supérieure ou égale au premier élément, et inférieure ou égale au deuxième. Si un élément contient une `AttributeValue` d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, `{"S":"6"}` n'est pas comparable à `{"N":"6"}`. De même, `{"N":"6"}` n'est pas comparable à `{"NS":["6", "2", "1"]}`.
`ScanIndexForward`	Spécifie le balayage ascendant ou descendant de l'index. DynamoDB renvoie des résultats reflétant l'ordre demandé déterminé par la clé de plage. Si le type de données est Nombre, les résultats sont renvoyés dans l'ordre numérique. Sinon, le balayage est basé sur des valeurs de code de caractère ASCII. Type : booléen Le paramétrage par défaut est `true` (ascendant).	Non
`ExclusiveStartKey`	Clé primaire de l'élément à partir duquel continuer une requête antérieure. Une requête antérieure peut fournir cette valeur en tant que `LastEvaluatedKey` si cette opération de requête a été interrompue avant la fin, soit en raison de la taille de l'ensemble de résultats, soit en raison du paramètre `Limit`. La `LastEvaluatedKey` peut être retransmise dans une nouvelle demande de requête pour continuer l'opération à partir de ce point. Type : `HashKeyElement`, ou `HashKeyElement` et `RangeKeyElement` pour une clé primaire composite.	Non

Réponses

Syntaxe


HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 308

{"Count":2,"Items":[{
    "AttributeName1":{"S":"AttributeValue1"},
    "AttributeName2":{"N":"AttributeValue2"},
    "AttributeName3":{"S":"AttributeValue3"}
    },{
    "AttributeName1":{"S":"AttributeValue3"},
    "AttributeName2":{"N":"AttributeValue4"},
    "AttributeName3":{"S":"AttributeValue3"},
    "AttributeName5":{"B":"dmFsdWU="}
}],
    "LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"},
                        "RangeKeyElement":{"AttributeValue4":"N"}
     },
     "ConsumedCapacityUnits":1
}

Name (Nom)	Description
`Items`	Attributs d'élément répondant aux paramètres de requête. Type : mappage de noms d'attribut à leurs types de données et valeurs.
`Count`	Nombre d'éléments dans la réponse. Pour plus d’informations, consultez Comptabilisation des éléments dans les résultats. Type : nombre
`LastEvaluatedKey`	Clé primaire de l'élément où l'opération de requête s'est arrêtée, incluant l'ensemble de résultats précédent. Utilisez cette valeur pour démarrer une nouvelle opération excluant cette valeur dans la nouvelle demande. La `LastEvaluatedKey` a une valeur `null` quand l'ensemble des résultats de la requête est complet (c'est-à-dire que l'opération a traité la « dernière page »). Type : `HashKeyElement`, ou `HashKeyElement` et `RangeKeyElement` pour une clé primaire composite.
`ConsumedCapacityUnits`	Nombre d'unités de capacité de lecture consommées par l'opération. Cette valeur indique le nombre appliqué à votre débit approvisionné. Pour plus d'informations, consultez Mode de capacité provisionnée DynamoDB. Type : nombre

Erreurs spéciales

Erreur	Description
`ResourceNotFoundException`	La table spécifiée n'a pas été trouvée.

Exemples

Pour des exemples d'utilisation du AWS SDK, consultezInterrogation de tables dans DynamoDB.

Exemple de demande



// This header is abbreviated. For a sample of a complete header, see DynamoDB de bas niveau API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query  
content-type: application/x-amz-json-1.0

{"TableName":"1-hash-rangetable",
	"Limit":2,
	"HashKeyValue":{"S":"John"},
	"ScanIndexForward":false,
	"ExclusiveStartKey":{
		"HashKeyElement":{"S":"John"},
		"RangeKeyElement":{"S":"The Matrix"}
	}
}

Exemple de réponse



HTTP/1.1 200 
x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 308

{"Count":2,"Items":[{
	"fans":{"SS":["Jody","Jake"]},
	"name":{"S":"John"},
	"rating":{"S":"***"},
	"title":{"S":"The End"}
	},{
	"fans":{"SS":["Jody","Jake"]},
	"name":{"S":"John"},
	"rating":{"S":"***"},
	"title":{"S":"The Beatles"}
	}],
	"LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}},
"ConsumedCapacityUnits":1
}

Exemple de demande


// This header is abbreviated. For a sample of a complete header, see DynamoDB de bas niveau API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.Query 
content-type: application/x-amz-json-1.0
 
{"TableName":"1-hash-rangetable",
	"Limit":2,
	"HashKeyValue":{"S":"Airplane"},
	"RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"},
	"ScanIndexForward":false}

Exemple de réponse


HTTP/1.1 200 
x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a
content-type: application/x-amz-json-1.0
content-length: 119 
 
{"Count":1,"Items":[{
	"fans":{"SS":["Dave","Aaron"]},
	"name":{"S":"Airplane"},
	"rating":{"S":"***"},
	"year":{"N":"1980"}
	}],
"ConsumedCapacityUnits":1
}

Actions connexes

Analyser

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

PutItem

Analyser