本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Query **重要** ***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。*** **如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。** ## 描述 `Query` 操作以主索引鍵獲取一或多個項目的值及其屬性 (`Query` 僅適用於雜湊與範圍主索引鍵資料表)。您必須提供特定的 `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 在查詢資料表時處理的項目數達上限，則會停止查詢，並傳回截至該時間點的相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續查詢。此外，如果在 DynamoDB 達到此限制之前結果集大小超過 1MB，則會停止查詢並傳回相符值，附帶 `LastEvaluatedKey` 以套用於後續操作中繼續查詢。類型：數字 | 否 | | ConsistentRead | 如果設定為 `true`，則會發送一致性讀取，反之則會使用最終一致性。類型：布林值 | 否 | | Count | 如果設定為 `true`，則 DynamoDB 會傳回符合查詢參數的項目總數，而不是相符項目及其屬性的清單。您可以套用 `Limit` 參數至僅計數查詢。 請勿在提供 `AttributesToGet` 清單之時將 `Count` 設定為 `true`，否則 DynamoDB 會傳回驗證錯誤。如需詳細資訊，請參閱 [計算結果中的項目](Query.Other.md#Query.Count)。類型：布林值 | 否 | | HashKeyValue | 複合主索引鍵雜湊元件的屬性值。類型：字串、數字或二進位 | 是 | | RangeKeyCondition | 屬性值容器以及用於查詢的比較運算子。查詢請求不需要 `RangeKeyCondition`。如果只提供 `HashKeyValue`，則 DynamoDB 會傳回具有指定雜湊索引鍵元素值的所有項目。類型：映射 | 否 | | RangeKeyCondition:​ AttributeValueList | 查詢參數要評估的屬性值。除非已指定 `BETWEEN` 比較，否則 `AttributeValueList` 一律包含一個屬性值。對於 `BETWEEN` 比較，`AttributeValueList` 包含兩個屬性值。類型：`ComparisonOperator` 的 `AttributeValue` 映射。 | 否 | | RangeKeyCondition:​ ComparisonOperator | 用於評估所提供的屬性的條件，例如等於、大於。以下是查詢操作的有效比較運算子。 大於、等於或小於的字串值比較是根據 ASCII 字元代碼值。例如，`a` 大於 `A`，`aa` 大於 `B`。如需代碼值的清單，請參閱 [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters)。 針對 Binary，每當 DynamoDB 比較二進位值，例如在評估查詢表達式時，都會將二進位資料的每個位元組視為不帶正負號。 類型：字串或二進位 | 否 | |   | `EQ`：等於。 對於 `EQ`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。 |   | |   | `LE`：小於或等於。 對於 `LE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 |   | |   | `LT`：小於。 對於 `LT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 |   | |   | `GE`：大於或等於。 對於 `GE`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 |   | |   | `GT`：大於。 對於 `GT`，`AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 |   | |   | `BEGINS_WITH`：檢查字首。 對於 `BEGINS_WITH`，`AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。 |   | |   | `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。 對於 `BETWEEN`，`AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。 |   | | ScanIndexForward | 指定遞增或遞減的索引周遊。DynamoDB 傳回結果會反映由範圍索引鍵決定之所請求順序：如果資料類型為數字，則會依數值順序傳回結果，反之，周遊則是根據 ASCII 字元代碼值。類型：布林值預設為 `true` (遞增)。 | 否 | | ExclusiveStartKey | 繼續先前查詢之項目的主索引鍵。如果因為結果集大小或 `Limit` 參數，導致查詢操作在查詢完成前中斷，較早的查詢可能提供此值為 `LastEvaluatedKey`。`LastEvaluatedKey` 可以在新的查詢請求中傳回，以便從該時間點繼續操作。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`。 | 否 | ## 回應 ### 語法 ``` 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 | 回應中的項目數。如需詳細資訊，請參閱 [計算結果中的項目](Query.Other.md#Query.Count)。 類型：數字 | | LastEvaluatedKey | 查詢操作停止的項目的主索引鍵，包括先前的結果集。使用此值開始新操作，在新的請求中排除此值。當整個查詢結果集完成時 (意即操作已處理「最後一頁」)，`LastEvaluatedKey` 為 `null`。類型：複合主索引鍵的 `HashKeyElement` 或 `HashKeyElement` 和 `RangeKeyElement`。 | | ConsumedCapacityUnits | 操作所使用的讀取容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 | ## 特殊錯誤 **** | 錯誤 | 描述 | | --- | --- | | ResourceNotFoundException | 找不到指定的資料表。 | ## 範例 如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 中查詢資料表](Query.md)。 ### 請求範例 ``` // 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 } ``` ## 相關動作 + [Scan](API_Scan_v20111205.md)