選取您的 Cookie 偏好設定

我們使用提供自身網站和服務所需的基本 Cookie 和類似工具。我們使用效能 Cookie 收集匿名統計資料,以便了解客戶如何使用我們的網站並進行改進。基本 Cookie 無法停用,但可以按一下「自訂」或「拒絕」以拒絕效能 Cookie。

如果您同意,AWS 與經核准的第三方也會使用 Cookie 提供實用的網站功能、記住您的偏好設定,並顯示相關內容,包括相關廣告。若要接受或拒絕所有非必要 Cookie,請按一下「接受」或「拒絕」。若要進行更詳細的選擇,請按一下「自訂」。

Query

焦點模式
Query - Amazon DynamoDB

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。

重要

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 在查詢資料表時處理的項目數達上限,則會停止查詢,並傳回截至該時間點的相符值,附帶 LastEvaluatedKey 以套用於後續操作中繼續查詢。此外,如果在 DynamoDB 達到此限制之前結果集大小超過 1MB,則會停止查詢並傳回相符值,附帶 LastEvaluatedKey 以套用於後續操作中繼續查詢。

類型:數字

ConsistentRead

如果設定為 true,則會發送一致性讀取,反之則會使用最終一致性。

類型:布林值

Count

如果設定為 true,則 DynamoDB 會傳回符合查詢參數的項目總數,而不是相符項目及其屬性的清單。您可以套用 Limit 參數至僅計數查詢。

請勿在提供 AttributesToGet 清單之時將 Count 設定為 true,否則 DynamoDB 會傳回驗證錯誤。如需詳細資訊,請參閱 計算結果中的項目

類型:布林值

HashKeyValue

複合主索引鍵雜湊元件的屬性值。

類型:字串、數字或二進位

RangeKeyCondition

屬性值容器以及用於查詢的比較運算子。查詢請求不需要 RangeKeyCondition。如果只提供 HashKeyValue,則 DynamoDB 會傳回具有指定雜湊索引鍵元素值的所有項目。

類型:映射

RangeKeyCondition:​ AttributeValueList

查詢參數要評估的屬性值。除非已指定 BETWEEN 比較,否則 AttributeValueList 一律包含一個屬性值。對於 BETWEEN 比較,AttributeValueList 包含兩個屬性值。

類型:ComparisonOperatorAttributeValue 映射。

RangeKeyCondition:​ ComparisonOperator

用於評估所提供的屬性的條件,例如等於、大於。以下是查詢操作的有效比較運算子。

注意

大於、等於或小於 的字串值比較是根據ASCII字元碼值。例如,a 大於 Aaa 大於 B。如需程式碼值的清單,請參閱 http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters

針對 Binary,每當 DynamoDB 比較二進位值,例如在評估查詢表達式時,都會將二進位資料的每個位元組視為不帶正負號。

類型:字串或二進位

 

EQ:等於。

對於 EQAttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不等於 {"N":"6"}。另外,{"N":"6"} 不等於 {"NS":["6", "2", "1"]}

 
 

LE:小於或等於。

對於 LEAttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不等於 {"N":"6"}。另外,{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

 
 

LT:小於。

對於 LTAttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不等於 {"N":"6"}。另外,{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

 
 

GE:大於或等於。

對於 GEAttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不等於 {"N":"6"}。另外,{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

 
 

GT:大於。

對於 GTAttributeValueList 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個 AttributeValue。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不等於 {"N":"6"}。另外,{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

 
 

BEGINS_WITH:檢查字首。

對於 BEGINS_WITHAttributeValueList 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個 AttributeValue。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。

 
 

BETWEEN:大於或等於第一個數值,並且小於或等於第二個數值。

對於 BETWEENAttributeValueList 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個 AttributeValue 元素。如果目標數值大於或等於第一個元素,並且小於或等於第二個元素,則目標屬性相符。如果項目內含的 AttributeValue 所屬類型與請求中指定的類型不同,則數值不相符。例如,{"S":"6"} 不與 {"N":"6"} 比較。另外,{"N":"6"} 不與 {"NS":["6", "2", "1"]} 比較。

 
ScanIndexForward

指定遞增或遞減的索引周遊。DynamoDB 傳回的結果會反映由範圍索引鍵決定的請求順序:如果資料類型為 Number,則結果會以數值順序傳回;否則,周遊是根據ASCII字元碼值。

類型:布林值

預設為 true (遞增)。

ExclusiveStartKey

繼續先前查詢之項目的主索引鍵。如果因為結果集大小或 Limit 參數,導致查詢操作在查詢完成前中斷,較早的查詢可能提供此值為 LastEvaluatedKeyLastEvaluatedKey 可以在新的查詢請求中傳回,以便從該時間點繼續操作。

類型:複合主索引鍵的 HashKeyElementHashKeyElementRangeKeyElement

回應

語法

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 查詢操作停止的項目的主索引鍵,包括先前的結果集。使用此值開始新操作,在新的請求中排除此值。

當整個查詢結果集完成時 (意即操作已處理「最後一頁」),LastEvaluatedKeynull

類型:複合主索引鍵的 HashKeyElementHashKeyElementRangeKeyElement

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 }

下一個主題:

Scan

上一個主題:

PutItem
隱私權網站條款Cookie 偏好設定
© 2025, Amazon Web Services, Inc.或其附屬公司。保留所有權利。