DynamoDB でのクエリの使用
Amazon DynamoDB での Query
オペレーションでは、プライマリキーの値に基づいて項目を探します。
パーティションキー属性の名前、および属性の単一値を指定する必要があります。Query
はそのパーティションキー値を持つすべての項目を返します。必要に応じて、ソートキーの属性を指定し、比較演算子を使用して、検索結果をさらに絞り込むことができます。
トピック
キー条件式
検索条件を指定するには、キー条件式 (テーブルまたはインデックスから読み取る項目を決定する文字列) を使用します。
等価条件としてパーティションキーの名前と値を指定する必要があります。
オプションで、ソートキーに 2 番目の条件を指定できます (存在する場合)。ソートキーの条件では、次の比較演算子の 1 つを使用する必要があります。
-
— 属性a
=b
a
が値b
と等しい場合、true -
—a
<b
a
がb
未満の場合、true -
—a
<=b
a
がb
以下である場合、true -
—a
>b
a
がb
より大きい場合、true -
—a
>=b
a
がb
以上である場合、true -
—a
BETWEENb
ANDc
a
がb
以上で、c
以下である場合、true。
次の関数もサポートされます。
-
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 のデータを取得できます。この制限は、フィルタ式を評価する前に適用されます。
フィルタ式には、パーティションキーまたはソートキーの属性を含めることはできません。フィルタ式ではなく、キー条件式のこれらの属性を指定する必要があります。
フィルター式の構文は、キー条件式の構文と似ています。フィルター式は、キー条件式と同じコンパレータ、関数および論理演算子を使用できます。さらに、フィルター式では、非等号演算子 (<>
)、OR
演算子、CONTAINS
演算子、IN
演算子、BEGINS_WITH
演算子、BETWEEN
演算子、EXISTS
演算子、および SIZE
演算子を使用できます。詳細については、「キー条件式」および「フィルター式と条件式の構文」を参照してください。
例
以下に、AWS CLI テーブルで特定の Thread
(パーティションキー) および ForumName
(ソートキー) に対する Subject
のサンプルクエリを示します。見つかった項目のうち、最も一般的なディスカッションスレッド (つまり、一定以上の数の 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
パラメータに項目の最大数を設定します。
たとえば、フィルタ式を使用せず、Query
値を Limit
として、テーブルを 6
するとします。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 は ... からの読み込み容量単位を消費します。 |
---|---|
表 | テーブルのプロビジョニングされた読み込みキャパシティー。 |
グローバルセカンダリインデックス | インデックスのプロビジョニングされた読み込みキャパシティー。 |
ローカルセカンダリインデックス | ベーステーブルのプロビジョニングされた読み込みキャパシティー。 |
デフォルトでは、Query
オペレーションはどのくらいの読み込みキャパシティーを消費するかについてのデータを返しません。ただし、この情報を取得するために ReturnConsumedCapacity
リクエストで Query
パラメータを指定できます。ReturnConsumedCapacity
の有効な設定を以下に示します。
-
NONE
— 消費された容量データは返されません。(これがデフォルトです) -
TOTAL
— レスポンスには消費された読み込み容量単位の合計値が含まれます。 -
INDEXES
— レスポンスは、アクセスする各テーブルとインデックスの消費される容量とともに、消費される読み込み容量単位の合計値を示します。
DynamoDB はアプリケーションに返されるデータ量ではなく、項目のサイズに基づいて、消費される読み込み容量単位の数を計算します。このため、消費されるキャパシティーユニットの数は、(射影式を使用して) 属性のすべてをリクエストしても (デフォルトの動作) 一部をリクエストしても、同じになります。数は、フィルタ式を使用していてもいなくても同じです。
クエリの読み込み整合性
Query
オペレーションは、結果的に整合性のある読み込みをデフォルトで行います。つまり、Query
結果が、最近完了した PutItem
または UpdateItem
オペレーションによる変更を反映しない場合があります。詳細については、「読み込み整合性」を参照してください。
強力な整合性のある読み込みが必要な場合は、ConsistentRead
リクエストで true
パラメータを Query
に設定します。