「翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。」
DynamoDB でのクエリの操作
Amazon DynamoDB での Query
オペレーションはプライマリキー値に基づいて項目を探します。
パーティションキー属性の名前と、その属性の単一の値を指定する必要があります。Query
は、そのパーティションキーの値を持つすべての項目を返します。必要に応じて、ソートキーの属性を指定し、比較演算子を使用して、検索結果をさらに絞り込むことができます。
トピック
キー条件式
検索条件を指定するには、キー条件式 —テーブルまたはインデックスから読み取る項目を決定する文字列を使用します。
等価条件としてパーティションキーの名前と値を指定する必要があります。
オプションで、ソートキーに 2 番目の条件を指定できます (存在する場合)。ソートキーの条件では、次の比較演算子の 1 つを使用する必要があります。
-
属性の場合、true—a
=b
a
は値と等しくなりますb
-
の場合、— truea
<b
a
は 未満b
-
の場合、— truea
<=b
a
が 以下であるb
-
の場合、— truea
>b
a
が より大きいb
-
の場合、— truea
>=b
a
が 以上にb
-
の場合、— truea
BETWEENb
ANDc
a
が 以上にb
、以下c
.
次の関数もサポートされます。
-
begins_with (
— 属性の値a
,substr
)
が特定のサブ文字列から始まる場合、true。a
キー条件式の使用方法を示す AWS Command Line Interface (AWS CLI) の例を次に示します。これらの式では、実際の値の代わりにプレースホルダー
(:name
や :sub
など) を使用しています。詳細については、「DynamoDB の式の属性名」および「式の属性値」を参照してください。
例
Thread
テーブルに対して、特定の ForumName
(パーティションキー) についてのクエリを実行します。その ForumName
の値を持つすべての項目はクエリによって読み込まれます。これはソートキー (Subject
) が KeyConditionExpression
に含まれないためです。
aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name" \ --expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}'
例
Thread
テーブルに対して、特定の ForumName
(パーティションキー) についてのクエリを実行しますが、今回は指定の Subject
(ソートキー) を持つ項目のみを返します。
aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name and Subject = :sub" \ --expression-attribute-values file://values.json
--expression-attribute-values
の引数は、ファイル values.json
に保存されます。
{ ":name":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"} }
例
Reply
テーブルに対して、特定の Id
(パーティションキー) についてのクエリを実行しますが、ReplyDateTime
(ソートキー) が特定の文字で始まる項目のみを返します。
aws dynamodb query \ --table-name Reply \ --key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \ --expression-attribute-values file://values.json
--expression-attribute-values
の引数は、ファイル values.json
に保存されます。
{ ":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"}, ":dt":{"S":"2015-09"} }
最初の文字が a-z
または A-Z
であり、2 番目の文字(ある場合)が a-z
、A-Z
、または 0-9
である場合は、キー条件式で任意の属性値を使用できます。 さらに、属性名は DynamoDB の予約語ではない必要があります (これらの完全なリストについては、「の予約語DynamoDB」を参照してください)。 属性名がこれらの要件を満たさない場合は、式の属性名をプレースホルダーとして定義する必要があります。詳細については、「DynamoDB の式の属性名」を参照してください。
特定のパーティションキー値を持つ項目は、DynamoDB によって、ソートキーの値で並べ替えられた順序で近くに配置されて保存されます。Query
オペレーションでは、DynamoDB は並べ替えられた順序で項目を取得し、KeyConditionExpression
や存在する任意の FilterExpression
を使用して項目を処理します。その後、Query
の結果がクライアントに返されます。
Query
オペレーションは常に結果セットを返します。一致する項目がない場合、結果セットは空になります。
Query
の結果は常にソートキーの値によってソートされます。ソートキーのデータ型が Number
である場合は、結果が番号順で返されます。その他の場合は、UTF-8 バイトの順序で結果が返されます。デフォルトの並べ替え順序は昇順です。順序を反転させるには、ScanIndexForward
パラメータを false
に設定します。
1 回の Query
オペレーションで、最大 1 MB のデータを取得できます。この制限は、結果への FilterExpression
の適用前に適用されます。レスポンスに LastEvaluatedKey
が存在し、Null 以外の場合、結果セットをページ分割する必要があります (テーブルクエリ結果をページ分割する を参照)。
クエリのフィルタ式
Query
結果の絞り込みが必要な場合は、オプションでフィルタ式を指定できます。フィルタ式によって、Query
結果の返される項目が決まります。他のすべての結果は破棄されます。
フィルタ式は、Query
の完了後、結果が返される前に適用されます。そのため、Query
は、フィルタ式があるかどうかにかかわらず、同じ量の読み込みキャパシティーを消費します。
1 回の Query
オペレーションで、最大 1 MB のデータを取得できます。この制限は、フィルタ式を評価する前に適用されます。
フィルタ式には、パーティションキーまたはソートキーの属性を含めることはできません。フィルタ式ではなく、キー条件式のこれらの属性を指定する必要があります。
フィルタ式の構文は、条件式の構文と同じです。フィルタ式は、等しくない演算子 (<>
) を追加することで、条件式と同じコンパレータ、関数、および論理演算子を使用できます。詳細については、「条件式」を参照してください。
例
以下に、Thread
テーブルで特定の ForumName
(パーティションキー) および Subject
(ソートキー) に対する AWS CLI のサンプルクエリを示します。見つかった項目のうち、最も一般的なディスカッションスレッドだけが返されます — つまり、Views
が特定の数を超えるスレッドのみです。
aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject = :sub" \ --filter-expression "#v >= :num" \ --expression-attribute-names '{"#v": "Views"}' \ --expression-attribute-values file://values.json
--expression-attribute-values
の引数は、ファイル values.json
に保存されます。
{ ":fn":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"}, ":num":{"N":"3"} }
Views
は DynamoDB で予約語であるため (の予約語DynamoDB を参照)、この例では #v
をプレースホルダーとして使用します。詳細については、「DynamoDB の式の属性名」を参照してください。
フィルタ式は、Query
結果セットから項目を削除します。可能であれば、大量の項目を取得してもそのほとんどを破棄する必要のあるような Query
を使用するのは避けます。
結果セットの項目数の制限
Query
オペレーションは、読み取られる項目数を制限することができます。これを行うには、Limit
パラメータに項目の最大数を設定します。
たとえば、フィルタ式を使用せず、Limit
値を 6
として、テーブルを Query
するとします。Query
結果には、リクエストからのキー条件式に一致するテーブルからの最初 6 つの項目が含まれます。
ここで、Query
にフィルタ式を追加するとします。 この場合、DynamoDB は最大 6 つの項目を読み取り、フィルタ式と一致する項目のみを返します。DynamoDB がより多くの項目を読み続けた場合、最終的な
Query
結果に含まれる項目数は、より多くの項目がフィルタ式にマッチしても 6 件以下です。
結果での項目のカウント
Query
レスポンスには、条件に一致する項目に加えて次の要素が含まれます。
-
ScannedCount
— フィルタ式 (存在する場合) が適用される前に、キー条件式に一致する項目数。 -
Count
— フィルタ式 (存在する場合) が適用された後に残っている項目数。
フィルタ式を使用しない場合、ScannedCount
と Count
は同じ値を持ちます。
Query
結果セットのサイズが 1 MB より大きい場合、ScannedCount
および Count
は、合計項目数の一部の数のみを表します。すべての結果を取得するためには、複数の Query
オペレーションを実行する必要があります (テーブルクエリ結果をページ分割する を参照してください)。
各 Query
レスポンスには、特定の ScannedCount
によって処理された項目の Count
および Query
が含まれます。すべての Query
リクエストの合計を取得するには、ScannedCount
および Count
の実行中の集計を維持することができます。
クエリで消費されるキャパシティーユニット
複合プライマリキー (パーティションキーおよびソートキー) がある場合、任意のテーブルまたは Query
を セカンダリインデックス できます。Query
オペレーションは、次のように読み込みキャパシティーユニットを消費します。
...を Query する場合
|
DynamoDB は ... からの読み込みキャパシティーユニットを消費します。 |
---|---|
表 | テーブルのプロビジョニングされた読み込みキャパシティー。 |
Global secondary index | インデックスのプロビジョニングされた読み込みキャパシティー。 |
ローカルセカンダリインデックス | ベーステーブルのプロビジョニングされた読み込みキャパシティー。 |
デフォルトでは、Query
オペレーションはどのくらいの読み込みキャパシティーを消費するかについてのデータを返しません。ただし、この情報を取得するために ReturnConsumedCapacity
リクエストで Query
パラメータを指定できます。ReturnConsumedCapacity
の有効な設定を以下に示します。
-
NONE
— 消費されたキャパシティーデータは返されません。(これがデフォルトです) -
TOTAL
— レスポンスには消費された読み込みキャパシティーユニットの合計値が含まれます。 -
INDEXES
— レスポンスは、アクセスする各テーブルとインデックスの消費されるキャパシティーとともに、消費される読み込みキャパシティーユニットの合計値を示します。
DynamoDB はアプリケーションに返されるデータ量ではなく、項目のサイズに基づいて、消費される読み込みキャパシティーユニットの数を計算します。このため、消費されるキャパシティーユニットの数は、(射影式を使用して) 属性のすべてをリクエストしても (デフォルトの動作) 一部をリクエストしても、同じになります。数は、フィルタ式を使用していてもいなくても同じです。
クエリの読み込み整合性
Query
オペレーションは、結果的に整合性のある読み込みをデフォルトで行います。つまり、Query
結果が、最近完了した PutItem
または UpdateItem
オペレーションによる変更を反映しない場合があります。詳細については、「読み込み整合性」を参照してください。
強力な整合性のある読み込みが必要な場合は、Query
リクエストで ConsistentRead
パラメータを true
に設定します。