Query - Amazon DynamoDB
描述請求回應特殊錯誤範例相關動作

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

Query

重要

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 包含兩個屬性值。

類型：ComparisonOperator 的 AttributeValue 映射。

 否
RangeKeyCondition:​ ComparisonOperator

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

注意

大於、等於或小於 的字串值比較是根據ASCII字元碼值。例如，a 大於 A，aa 大於 B。如需程式碼值的清單，請參閱 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 傳回的結果會反映由範圍索引鍵決定的請求順序：如果資料類型為 Number，則結果會以數值順序傳回；否則，周遊是根據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

回應中的項目數。如需詳細資訊，請參閱 計算結果中的項目。

類型：數字
LastEvaluatedKey 查詢操作停止的項目的主索引鍵，包括先前的結果集。使用此值開始新操作，在新的請求中排除此值。

當整個查詢結果集完成時 (意即操作已處理「最後一頁」)，LastEvaluatedKey 為 null。

類型：複合主索引鍵的 HashKeyElement 或 HashKeyElement 和 RangeKeyElement。
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
}