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. 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