Query
重要
このセクションでは、API バージョン 2011-12-05 について言及しています。これは非推奨なので、新しいアプリケーションに使用しないでください。
現在の低レベルの API に関するドキュメントについては、Amazon DynamoDB API リファレンスを参照してください。
説明
Query
オペレーションオペレーションは、1 つ以上の項目の値とその属性をプライマリキーごとに取得します (Query
はハッシュと範囲のプライマリキーテーブルでのみ使用できます)。特定の HashKeyValue
を指定する必要があります。プライマリキーの RangeKeyValue
で比較オペレーションを使用してクエリの範囲を絞り込むことができます。範囲キーごとに正順または逆順で結果を取得するには、ScanIndexForward
パラメータを使用します。
結果を返さないクエリは、読み込みのタイプに応じて最小読み込み容量ユニットを消費します。
注記
クエリパラメータを満たす項目の合計数が 1 MB の制限を超えるとクエリが停止し、結果が後続のオペレーションでクエリを続行するための LastEvaluatedKey
とともにユーザーに返されます。スキャン操作とは異なり、クエリ操作では、空の結果セットおよび LastEvaluatedKey
が返されません。結果が 1 MB を超える場合、または 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 はクエリを停止し、その時点までの一致する値とともに、後続のオペレーションでクエリを続行するために適用する 型: 数値 |
いいえ |
ConsistentRead
|
型: ブール値 |
いいえ |
Count
|
型: ブール値 |
いいえ |
HashKeyValue
|
複合プライマリキーのハッシュコンポーネントの属性値。 型: 文字列、数値、またはバイナリ |
はい |
RangeKeyCondition
|
クエリに使用する属性値および比較演算子のコンテナ。クエリリクエストには 型: マップ |
いいえ |
RangeKeyCondition :
AttributeValueList |
クエリパラメータについて評価する属性値。 型: |
いいえ |
RangeKeyCondition :
ComparisonOperator |
指定された属性 (等しい、より大きい、など) を評価するための基準。クエリオペレーションで有効な比較演算子は次の通りです。 注記より大きい、等しい、より小さいに関する文字列値の比較は、ASCII 文字コード値に基づきます。例えば、 バイナリの場合、DynamoDB は、バイナリ値を比較する際 (クエリ表現の評価など)、バイナリデータの各バイトを符号なしとしてて扱います。 型: 文字列またはバイナリ |
いいえ |
|
||
|
||
|
||
|
||
|
||
|
||
|
||
ScanIndexForward |
インデックスの昇順または降順トラバーサルを指定します。DynamoDB は、範囲キーによって決定されたリクエストされた順序を反映した結果を返します。データ型が数値の場合、結果は数値順に返されます。それ以外の場合は、トラバーサルは ASCII 文字コード値に基づきます。 型: ブール値 デフォルトは |
いいえ |
ExclusiveStartKey |
以前のクエリを続行する項目のプライマリキー。クエリが完了する前に結果セットサイズまたは 型: 複合プライマリキーの |
いいえ |
レスポンス
構文
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 |
クエリオペレーションが停止した項目のプライマリキー (以前の結果セットを含みます)。この値を使用して、新しいリクエストでこの値を除く新しいオペレーションをスタートします。 クエリ結果セット全体が完了したとき (オペレーションが「最後のページ」を処理したとき)、 型: 複合プライマリキーの |
ConsumedCapacityUnits |
オペレーションによって消費される読み込み容量ユニットの数。この値は、プロビジョニングされたスループットに適用される数を示します。詳細については、「プロビジョンドキャパシティモード」を参照してください。 型: 数値 |
特殊なエラー
エラー | 説明 |
---|---|
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 }