Abfragen

Wichtig

Dieser Abschnitt bezieht sich auf die veraltete API-Version 2011-12-05, die nicht für neue Anwendungen verwendet werden sollte.

Eine Dokumentation zur aktuellen Low-Level-API finden Sie in der Amazon DynamoDB-API-Referenz.

Beschreibung

Eine Query-Operation ruft die Werte eines oder mehrerer Elemente mit den zugehörigen Attributen nach Primärschlüssel ab (Query ist nur für Hash- und Bereichsprimärschlüssel-Tabellen verfügbar). Sie müssen einen spezifischen HashKeyValue angeben und können den Umfang der Abfrage einschränken, indem Sie Vergleichsoperatoren auf den RangeKeyValue des Primärschlüssels anwenden. Verwenden Sie den Parameter ScanIndexForward, um Ergebnisse nach Bereichsschlüssel in vorwärts gerichteter oder umgekehrter Reihenfolge zu erhalten.

Abfragen, die keine Ergebnisse zurückgeben, verbrauchen die minimalen Lesekapazitätseinheiten entsprechend dem Lesetyp.

Anmerkung

Wenn die Gesamtanzahl der Elemente, die den Abfrageparametern entsprechen, das Limit von 1 MB überschreitet, wird die Abfrage beendet und die Ergebnisse werden an den Benutzer mit einem LastEvaluatedKey zurückgegeben. Die Abfrage wird in einer nachfolgenden Operation fortgesetzt. Im Gegensatz zu einer Scan-Operation gibt eine Abfrage-Operation niemals einen leeren Ergebnissatz und einen LastEvaluatedKey zurück. Der LastEvaluatedKey wird nur bereitgestellt, wenn die Ergebnisse 1 MB überschreiten oder wenn Sie den Parameter Limit verwendet haben.

Das Ergebnis kann für einen Consistent-Lesevorgang mit dem Parameter ConsistentRead festgelegt werden.

Anforderungen

Syntax

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB Low-Level-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	Beschreibung	Erforderlich
TableName	Der Name der Tabelle, die die angeforderten Elemente enthält. Typ: Zeichenfolge	Ja
AttributesToGet	Array von Attributnamen. Wenn Attributnamen nicht angegeben sind, dann werden alle Attribute zurückgegeben. Wenn einige Attribute nicht gefunden werden, sind sie nicht im Abfrageergebnis enthalten. Typ: Array	Nein
Limit	Die maximale Anzahl der zurückzugebenden Elemente (nicht notwendigerweise die Anzahl der übereinstimmenden Elemente). Wenn DynamoDB bei der Abfrage der Tabelle die Anzahl der Elemente bis zum Limit verarbeitet, wird die Abfrage beendet und es werden die bis zu diesem Punkt übereinstimmenden Werte zurückgegeben. Außerdem wird ein LastEvaluatedKey ausgegeben, der bei einer nachfolgenden Operation angewendet wird, um die Abfrage fortzusetzen. Wenn der Ergebnissatz 1 MB überschreitet, bevor DynamoDB dieses Limit erreicht, wird die Abfrage beendet und es werden die übereinstimmenden Werte zurückgegeben. Außerdem wird der LastEvaluatedKey ausgegeben, der bei einer nachfolgenden Operation angewendet wird, um mit der Abfrage fortzufahren. Typ: Zahl	Nein
ConsistentRead	Wenn auf true festgelegt, dann wird ein Consistent-Lesevorgang ausgegeben, andernfalls wird Eventually Consistent verwendet. Typ: Boolesch	Nein
Count	Wenn auf true festgelegt, gibt DynamoDB die Gesamtzahl der Elemente zurück, die mit den Abfrageparametern übereinstimmen, anstatt eine Liste der übereinstimmenden Elemente und der zugehörigen Attribute. Sie können den Parameter Limit auf Abfragen anwenden, die nur zählen. Setzen Sie Count nicht auf true, wenn Sie eine Liste von AttributesToGet bereitstellen, sonst gibt DynamoDB einen Validierungsfehler zurück. Weitere Informationen finden Sie unter Zählen der Elemente in den Ergebnissen. Typ: Boolesch	Nein
HashKeyValue	Attributwert der Hash-Komponente des zusammengesetzten Primärschlüssels. Typ: Zeichenfolge, Zahl oder Binärzahl	Ja
RangeKeyCondition	Ein Container für die Attributwerte und Vergleichsoperatoren für die Abfrage. Eine Abfrageanforderung erfordert keine RangeKeyCondition. Wenn Sie nur den HashKeyValue angeben, gibt DynamoDB alle Elemente mit dem angegebenen Hash-Schlüsselelementwert zurück. Typ: Zuordnung	Nein
RangeKeyCondition:​ AttributeValueList	Die Attributwerte zur Bewertung der Abfrageparameter. AttributeValueList enthält einen Attributwert, es sei denn, es wurde ein BETWEEN -Vergleich angegeben. Für den BETWEEN-Vergleich enthält AttributeValueList zwei Attributwerte. Typ: Zuordnung von AttributeValue zu einer ComparisonOperator.	Nein
RangeKeyCondition:​ ComparisonOperator	Die Kriterien für die Bewertung der bereitgestellten Attribute, z. B. gleich, größer als usw. Die folgenden Operatoren sind gültige Vergleichsoperatoren für eine Abfrage-Operation. Anmerkung Vergleiche von Zeichenfolgenwerten für größer als, gleich oder kleiner als basieren auf ASCII-Zeichensatzwerten. Beispiel: a ist größer als A und aa ist größer als B. Eine Liste von Codewerten finden Sie unter http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters. Beim Binärtyp behandelt DynamoDB jedes Byte der Binärdaten als ohne Vorzeichen, wenn binäre Werte verglichen werden (z. B. bei der Bewertung von Abfrageausdrücken). Typ: Zeichenfolge oder Binärzahl	Nein
	EQ : gleich. Bei EQ kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge, Zahl oder Binärzahl (keinen Satz) enthalten. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} ist nicht gleich {"N":"6"}. Auch, {"N":"6"} ist nicht gleich {"NS":["6", "2", "1"]}.
	LE : kleiner als oder gleich. Bei LE kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge, Zahl oder Binärzahl (keinen Satz) enthalten. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} ist nicht gleich {"N":"6"}. Auch, {"N":"6"} entspricht nicht {"NS":["6", "2", "1"]}.
	LT : kleiner als. Bei LT kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge, Zahl oder Binärzahl (keinen Satz) enthalten. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} ist nicht gleich {"N":"6"}. Auch, {"N":"6"} entspricht nicht {"NS":["6", "2", "1"]}.
	GE : größer als oder gleich. Bei GE kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge, Zahl oder Binärzahl (keinen Satz) enthalten. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} ist nicht gleich {"N":"6"}. Auch, {"N":"6"} entspricht nicht {"NS":["6", "2", "1"]}.
	GT : größer als. Bei GT kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge, Zahl oder Binärzahl (keinen Satz) enthalten. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} ist nicht gleich {"N":"6"}. Auch, {"N":"6"} entspricht nicht {"NS":["6", "2", "1"]}.
	BEGINS_WITH: Prüft auf ein Präfix. Bei BEGINS_WITH kann AttributeValueList nur einen AttributeValue vom Typ Zeichenfolge oder Binärzahl (keine Zahl bzw. keinen Satz) enthalten. Das Zielattribut des Vergleichs muss vom Typ Zeichenfolge oder Binärzahl sein (keine Zahl bzw. kein Satz).
	BETWEEN: Größer als oder gleich dem ersten Wert und kleiner als oder gleich dem zweiten Wert. Für BETWEEN muss AttributeValueList zwei AttributeValue-Elemente desselben Typs enthalten, und zwar Zeichenfolge, Zahl oder Binärzahl (keinen Satztyp). Es kommt zu einer Übereinstimmung mit dem Zielattribut, wenn der Zielwert größer als oder gleich dem ersten Element und kleiner als oder gleich dem zweiten Element ist. Wenn ein Element einen AttributeValue eines anderen Typs enthält, als in der Anforderung angegeben, stimmt der Wert nicht überein. Beispiel: {"S":"6"} stimmt nicht mit {"N":"6"} überein. Auch, {"N":"6"} entspricht nicht {"NS":["6", "2", "1"]}.
ScanIndexForward	Gibt die auf- oder absteigende Traversierung des Index an. DynamoDB gibt Ergebnisse zurück, die der angeforderten Reihenfolge entsprechen, die vom Bereichsschlüssel bestimmt wird: Wenn der Datentyp „Zahl“ lautet, werden die Ergebnisse in numerischer Reihenfolge zurückgegeben, andernfalls basiert der Traversal auf ASCII-Zeichencodewerten. Typ: Boolesch Der Standardwert ist true (aufsteigend).	Nein
ExclusiveStartKey	Der Primärschlüssel des Elements, von dem eine frühere Abfrage fortgesetzt wird. Eine frühere Abfrage kann diesen Wert als LastEvaluatedKey bereitstellen, wenn diese Abfrage-Operation vor Abschluss unterbrochen wurde – entweder aufgrund der Größe des Ergebnissatzes oder aufgrund des Limit-Parameters. Der LastEvaluatedKey kann in einer neuen Abfrageanforderung zurückgegeben werden, um die Operation von diesem Punkt fortzusetzen. Typ: HashKeyElement oder HashKeyElement und RangeKeyElement für einen zusammengesetzten Primärschlüssel.	Nein

Antworten

Syntax

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	Beschreibung
Items	Elementattribute, die den Abfrageparametern entsprechen. Typ: Zuordnung der Attributnamen und ihrer Datentypen und Werte.
Count	Anzahl der Elemente in der Antwort. Weitere Informationen finden Sie unter Zählen der Elemente in den Ergebnissen. Typ: Zahl
LastEvaluatedKey	Primärschlüssel des Elements, an dem die Abfrage-Operation beendet wurde, einschließlich des vorherigen Ergebnissatzes. Verwenden Sie diesen Wert, um eine neue Operation ohne diesen Wert in der neuen Anforderung zu starten. Der LastEvaluatedKey ist null, wenn der Ergebnissatz der Abfrage vollständig ist (das heißt, wenn die "letzte Seite" von der Operation verarbeitet wurde). Typ: HashKeyElement oder HashKeyElement und RangeKeyElement für einen zusammengesetzten Primärschlüssel.
ConsumedCapacityUnits	Die Anzahl der Lesekapazitätseinheiten, die von der Operation verbraucht werden. Dieser Wert zeigt die Anzahl, die für Ihren bereitgestellten Durchsatz gültig ist. Weitere Informationen finden Sie unter Verwalten von Einstellungen für DynamoDB-Tabellen mit bereitgestellter Kapazität. Typ: Zahl

Spezielle Fehler

Fehler	Beschreibung
ResourceNotFoundException	Die angegebene Tabelle wurde nicht gefunden.

Beispiele

Beispiele für die Verwendung des AWS SDK finden Sie unter Abfrageoperationen in DynamoDB.

Beispielanforderung

// This header is abbreviated. For a sample of a complete header, see DynamoDB Low-Level-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"}
	}
}

Beispielantwort

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
}

Beispielanforderung

// This header is abbreviated. For a sample of a complete header, see DynamoDB Low-Level-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}

Beispielantwort

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
}

Zugehörige Aktionen

• Scan