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

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

Query

重要

本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。

如需目前低階 API 的文件，請參閱Amazon DynamoDB API 參考。

描述

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 會傳回驗證錯誤。如需詳細資訊，請參閱 計算結果中的項目。

類型：布林值

 否
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 傳回結果會反映由範圍索引鍵決定之所請求順序：如果資料類型為數字，則會依數值順序傳回結果，反之，周遊則是根據 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
}