Query - Amazon DynamoDB
説明リクエストレスポンス特殊なエラー例関連アクション

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

型: 数値

 いいえ
ConsistentRead

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

型: ブール値

 いいえ
Count

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

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

型: ブール値

 いいえ
HashKeyValue

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

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

 はい
RangeKeyCondition

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

型: マップ

 いいえ
RangeKeyCondition:​ AttributeValueList

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

型: ComparisonOperator への AttributeValue のマップ。

 いいえ
RangeKeyCondition:​ ComparisonOperator

指定された属性 (等しい、より大きい、など) を評価するための基準。クエリオペレーションで有効な比較演算子は次の通りです。

注記

より大きい、等しい、より小さいに関する文字列値の比較は、ASCII 文字コード値に基づきます。例えば、a は A より大きく、aa は B より大きいと評価されます。コードの値のリストについては、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 は、文字列、数値、またはバイナリのいずれかの同じ型の 2 つの AttributeValue 要素を含む必要があります (セットではありません)。ターゲット属性は、ターゲット値が最初の要素より大きいか等しく、2番目の要素より小さいか等しい場合に一致します。リクエストで指定されているもの以外の型の 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
}