本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
重要
This section refers to API version 2011-12-05,
which is deprecated and should not be used for new
applications.
如需目前低階 的文件API,請參閱 Amazon DynamoDB API參考。
描述
Query
操作會依主索引鍵取得一或多個項目的值及其屬性 (Query
僅適用於 hash-and-range主索引鍵資料表)。您必須提供特定的 HashKeyValue
,且能在主索引鍵的 RangeKeyValue
上使用比較運算子縮小查詢範圍。使用 ScanIndexForward
參數以範圍索引鍵取得正向或反向順序的結果。
未傳回結果的查詢會根據讀取類型使用最小讀取容量單位。
注意
如果符合查詢參數的項目總數超過 1MB 限制,則查詢會停止,並將結果傳回給使用者,附帶 LastEvaluatedKey
用以在後續操作中繼續查詢。查詢操作不同於掃描操作,一律不會傳回空的結果集和 LastEvaluatedKey
。只有在結果超過 1MB,或者您已使用 Limit
參數時,才會提供 LastEvaluatedKey
。
使用 ConsistentRead
參數可設定一致性讀取的結果。
請求
語法
// This header is abbreviated. // For a sample of a complete header, see DynamoDB 低階 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"]}, }
名稱 | 描述 | 必要 |
---|---|---|
TableName
|
包含請求項目的資料表的名稱。 類型:字串 |
是 |
AttributesToGet
|
屬性名稱陣列。如果未指定屬性名稱,則會傳回所有屬性。如果有部分屬性未找到,則這些屬性不會出現在結果中。 類型:陣列 |
否 |
Limit
|
要傳回的項目數上限 (不一定是相符項目數)。如果 DynamoDB 在查詢資料表時處理的項目數達上限,則會停止查詢,並傳回截至該時間點的相符值,附帶 類型:數字 |
否 |
ConsistentRead
|
如果設定為 類型:布林值 |
否 |
Count
|
如果設定為 請勿在提供 類型:布林值 |
否 |
HashKeyValue
|
複合主索引鍵雜湊元件的屬性值。 類型:字串、數字或二進位 |
是 |
RangeKeyCondition
|
屬性值容器以及用於查詢的比較運算子。查詢請求不需要 類型:映射 |
否 |
RangeKeyCondition :
AttributeValueList |
查詢參數要評估的屬性值。除非已指定 類型: |
否 |
RangeKeyCondition :
ComparisonOperator |
用於評估所提供的屬性的條件,例如等於、大於。以下是查詢操作的有效比較運算子。 注意大於、等於或小於 的字串值比較是根據ASCII字元碼值。例如, 針對 Binary,每當 DynamoDB 比較二進位值,例如在評估查詢表達式時,都會將二進位資料的每個位元組視為不帶正負號。 類型:字串或二進位 |
否 |
對於 |
||
對於 |
||
對於 |
||
對於 |
||
對於 |
||
對於 |
||
對於 |
||
ScanIndexForward |
指定遞增或遞減的索引周遊。DynamoDB 傳回的結果會反映由範圍索引鍵決定的請求順序:如果資料類型為 Number,則結果會以數值順序傳回;否則,周遊是根據ASCII字元碼值。 類型:布林值 預設為 |
否 |
ExclusiveStartKey |
繼續先前查詢之項目的主索引鍵。如果因為結果集大小或 類型:複合主索引鍵的 |
否 |
回應
語法
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
}
名稱 | 描述 |
---|---|
Items
|
符合查詢參數的項目屬性。 類型:屬性名稱映射,以及其資料類型和值。 |
Count
|
回應中的項目數。如需詳細資訊,請參閱 計算結果中的項目。 類型:數字 |
LastEvaluatedKey |
查詢操作停止的項目的主索引鍵,包括先前的結果集。使用此值開始新操作,在新的請求中排除此值。 當整個查詢結果集完成時 (意即操作已處理「最後一頁」), 類型:複合主索引鍵的 |
ConsumedCapacityUnits |
操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需詳細資訊,請參閱 DynamoDB 佈建容量模式。 類型:數字 |
特殊錯誤
錯誤 | 描述 |
---|---|
ResourceNotFoundException
|
找不到指定的資料表。 |
範例
如需使用 的範例 AWS SDK,請參閱 在 DynamoDB 中查詢資料表。
請求範例
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 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"} } }
回應範例
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
}
請求範例
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 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}
回應範例
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
}