Amazon DynamoDB
開発者ガイド (API バージョン 2012-08-10)

Query

重要

このセクションは、廃止された API バージョン 2011-12-05 についての記述で、新しいアプリケーションで使用することはできません。

現在の低レベル API のドキュメントについては、「Amazon DynamoDB API Reference」を参照してください。

説明

Query オペレーションは、プライマリキーによって 1 つ以上の項目とその属性の値を取得します(Query は、ハッシュおよび範囲プライマリキーテーブルに対してのみ使用できます)。特定の HashKeyValue を指定する必要があり、プライマリキーの RangeKeyValue に対して比較演算子を使用するとクエリの範囲を絞り込むことができます。ScanIndexForward パラメータを使用して、範囲キーの昇順または降順で結果を取得します。

結果を返さないクエリは、読み込みのタイプに応じて最小の読み込みキャパシティーユニットを消費します。

注記

クエリパラメータを満たす項目の合計数が、1 MB の制限を超えた場合、クエリは停止し、後続のオペレーションでクエリを継続できるように、LastEvaluatedKey とともに結果がユーザーに返されます。Scan オペレーションとは異なり、Query オペレーションは空白の結果セット LastEvaluatedKey を返しません。結果が 1 MB を超えた場合、または LastEvaluatedKey パラメータを使用した場合にのみ、Limit が指定されます。

結果は、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 は、この上限に到達する前に結果セットのサイズが 1 MB を超えた場合、クエリを停止し、一致する値と、クエリを継続するために後続のオペレーションで利用できる LastEvaluatedKey を返します。

型: 数値

いいえ
ConsistentRead

true に設定した場合、整合性のある読み込みが実行されます。それ以外の場合は、結果整合性が使用されます。

タイプ: ブール値

いいえ
Count

true に設定した場合、DynamoDB は、一致する項目とその属性のリストではなく、クエリパラメータに一致する項目の合計数を返します。Limit パラメータはカウントのみのクエリに適用できます。

AttributesToGet のリストを指定している場合は、Counttrue に設定しないでください。設定すると、DynamoDB は検証エラーを返します。詳細については、「結果での項目のカウント」を参照してください。

タイプ: ブール値

いいえ
HashKeyValue

複合プライマリキーのハッシュコンポーネントの属性値。

型: 文字列、数値、またはバイナリ

はい
RangeKeyCondition

クエリに使用する属性値と比較演算子のコンテナ。クエリリクエストには、RangeKeyCondition は必要ありません。HashKeyValue のみを指定した場合、DynamoDB は、指定したハッシュキー要素の値を持つすべての項目を返します。

タイプ: マップ

いいえ
RangeKeyCondition:​ AttributeValueList

クエリパラメータに対して評価する属性値。AttributeValueList には、1 つの属性値を指定します。ただし、BETWEEN 比較を指定する場合を除きます。BETWEEN 比較の場合、AttributeValueList には 2 つの属性値を指定します。

型: AttributeValueComparisonOperator のマップ

いいえ
RangeKeyCondition:​ ComparisonOperator

等しい、より大きいなど、指定した属性を評価するための基準。Query オペレーションで有効な比較演算子を次に示します。

注記

より大きい、等しい、より小さいの文字列値比較は、ASCII 文字コード値に基づいて行われます。たとえば、aA より大きく、aaB より大きい文字列です。コードの値のリストについては、「http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters」を参照してください。

バイナリの場合、DynamoDB では、クエリ式の値を求める場合など、バイナリ値を比較する場合に、バイナリデータの各バイトを符号なしとして処理します。

型: 文字列またはバイナリ

いいえ
 

EQ : 等しい。

EQ の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} は等しくありません。また、{"N":"6"}{"NS":["6", "2", "1"]} も等しくありません。

 
 

LE : 以下。

LE の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} は等しくありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
 

LT : 未満。

LT の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} は等しくありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
 

GE : 以上。

GE の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} は等しくありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
 

GT : より大きい。

GT の場合、AttributeValueList に指定できるのは、文字列型、数値型、またはバイナリ型の 1 つの AttributeValue だけです(セット型は指定できません)。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} は等しくありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
 

BEGINS_WITH : プレフィックスのチェック。

BEGINS_WITH の場合、AttributeValueList に指定できるのは、文字列型またはバイナリ型の 1 つの AttributeValue だけです(数値型またはセット型は指定できません)。比較対象の属性は、(数値型またはセット型ではなく)文字列型またはバイナリ型である必要があります。

 
 

BETWEEN : 最初の値以上、かつ 2 番目の値以下。

BETWEEN の場合、AttributeValueList には、同じ型(文字列、数値、またはバイナリ)の AttributeValue 要素を 2 つ指定する必要があります(セット型は指定できません)。対象の属性が一致するのは、対象の値が最初の要素以上かつ 2 番目の要素以下の場合です。リクエストで指定した型とは異なる型の AttributeValue が項目に含まれている場合、値は一致しません。たとえば、{"S":"6"}{"N":"6"} と同等ではありません。また、{"N":"6"}{"NS":["6", "2", "1"]} と同等ではありません。

 
ScanIndexForward

インデックスの昇順または降順トラバーサルを指定します。DynamoDB は、範囲キーによって決まる、リクエストされた順序を反映した結果を返します。データ型が数値の場合、結果は数字順で返されます。それ以外の場合、トラバーサルは ASCII 文字コード値に基づいて行われます。

タイプ: ブール値

デフォルトは true (昇順) です。

いいえ
ExclusiveStartKey

以前のクエリを継続するときに開始する項目のプライマリキー。結果セットのサイズまたは LastEvaluatedKey パラメータが原因で、以前のクエリオペレーションがクエリを完了する前に中断された場合、この値が Limit として返されている可能性があります。新しいクエリリクエストで LastEvaluatedKey を渡して、その時点からオペレーションを継続できます。

型: HashKeyElement、または複合プライマリキーの場合 HashKeyElementRangeKeyElement

いいえ

レスポンス

構文

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 になります。

型: HashKeyElement、または複合プライマリキーの場合 HashKeyElementRangeKeyElement

ConsumedCapacityUnits

オペレーションによって消費された読み込みキャパシティーユニットの数。この値は、プロビジョニングされたスループットに対して適用された数を示します。詳細については、「読み取りと書き込みのスループット設定」を参照してください。

型: 数値

特殊なエラー

エラー 説明
ResourceNotFoundException 指定されたテーブルが見つかりませんでした。

AWS SDK を使用した例については、「クエリの操作」を参照してください。

リクエスト例

// 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 }