Working with Queries in DynamoDB - Amazon DynamoDB
Key Condition ExpressionFilter Expressions for QueryLimiting the Number of Items in the Result SetCounting the Items in the ResultsCapacity Units Consumed by QueryRead Consistency for Query

英語の翻訳が提供されている場合で、内容が矛盾する場合には、英語版がオリジナルとして取り扱われます。翻訳は機械翻訳により提供されています。

Working with Queries in DynamoDB

Amazon DynamoDB での Query オペレーションはプライマリキー値に基づいて項目を探します。

パーティション キー属性の名前と、その属性の単一値を指定する必要があります。Query そのパーティション キー値を持つすべてのアイテムを返します。必要に応じて、ソートキーの属性を指定し、比較演算子を使用して、検索結果をさらに絞り込むことができます。

トピック

Key Condition Expression

検索基準を指定するには、 key condition expression—テーブルまたはインデックスから読み取るアイテムを決定する文字列。

等価条件としてパーティションキーの名前と値を指定する必要があります。

オプションで、ソートキーに 2 番目の条件を指定できます (存在する場合)。ソートキーの条件では、次の比較演算子の 1 つを使用する必要があります。

  • a = b — true if the attribute a is equal to the value b

  • a < b — true if a is less than b

  • a <= b — true if a is less than or equal to b

  • a > b — true if a is greater than b

  • a >= b — true if a is greater than or equal to b

  • a BETWEEN b AND c — true if a is greater than or equal to b, and less than or equal to c.

次の関数もサポートされます。

  • begins_with (a, substr)— true if the value of attribute a begins with a particular substring.

キー条件式の使用方法を示す 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 以外の場合、結果セットをページ分割する必要があります (Paginating Table Query Results を参照)。

Filter Expressions for Query

Query 結果の絞り込みが必要な場合は、オプションでフィルタ式を指定できます。A filter expression は、 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 を使用するのは避けます。

Limiting the Number of Items in the Result Set

Query オペレーションは、読み取られる項目数を制限することができます。これを行うには、Limit パラメータに項目の最大数を設定します。

たとえば、フィルタ式を使用せず、Limit 値を 6 として、テーブルを Query するとします。Query 結果には、リクエストからのキー条件式に一致するテーブルからの最初 6 つの項目が含まれます。

ここで、フィルター式を Query。 この場合、 DynamoDB 最大 6 つのアイテムを読み取り、フィルター式に一致するアイテムのみを返します。DynamoDB がより多くの項目を読み続けた場合、最終的な Query 結果に含まれる項目数は、より多くの項目がフィルタ式にマッチしても 6 件以下です。

Counting the Items in the Results

Query レスポンスには、条件に一致する項目に加えて次の要素が含まれます。

  • ScannedCount — The number of items that matched the key condition expression before a filter expression (if present) was applied.

  • Count — The number of items that remain after a filter expression (if present) was applied.

注記

フィルタ式を使用しない場合、ScannedCount と Count は同じ値を持ちます。

Query 結果セットのサイズが 1 MB より大きい場合、ScannedCount および Count は、合計項目数の一部の数のみを表します。すべての結果を取得するためには、複数の Query オペレーションを実行する必要があります (Paginating Table Query Results を参照してください)。

各 Query レスポンスには、特定の ScannedCount によって処理された項目の Count および Query が含まれます。すべての Query リクエストの合計を取得するには、ScannedCount および Count の実行中の集計を維持することができます。

Capacity Units Consumed by Query

以下が可能です。 Query 任意のテーブルまたは セカンダリインデックス複合プライマリキー(パーティションキーとソートキー)がある場合。Query 次のように、読み取り容量単位が消費されます。

...を Query する場合 DynamoDB は ... からの読み込みキャパシティーユニットを消費します。
表 テーブルのプロビジョニングされた読み込みキャパシティー。
Global secondary index インデックスのプロビジョニングされた読み込みキャパシティー。
ローカルセカンダリインデックス ベーステーブルのプロビジョニングされた読み込みキャパシティー。

デフォルトでは、Queryオペレーションはどのくらいの読み込みキャパシティーを消費するかについてのデータを返しません。ただし、この情報を取得するために ReturnConsumedCapacity リクエストで Queryパラメータを指定できます。ReturnConsumedCapacity の有効な設定を以下に示します。

  • NONE — No consumed capacity data is returned. (This is the default.)

  • TOTAL — The response includes the aggregate number of read capacity units consumed.

  • INDEXES — The response shows the aggregate number of read capacity units consumed, together with the consumed capacity for each table and index that was accessed.

DynamoDB はアプリケーションに返されるデータ量ではなく、項目のサイズに基づいて、消費される読み込みキャパシティーユニットの数を計算します。このため、消費されるキャパシティーユニットの数は、(射影式を使用して) 属性のすべてをリクエストしても (デフォルトの動作) 一部をリクエストしても、同じになります。数は、フィルタ式を使用していてもいなくても同じです。

Read Consistency for Query

Query オペレーションは、結果的に整合性のある読み込みをデフォルトで行います。つまり、Query 結果が、最近完了した PutItem または UpdateItem オペレーションによる変更を反映しない場合があります。詳細については、「Read Consistency」を参照してください。

強力な整合性のある読み込みが必要な場合は、Query リクエストで ConsistentRead パラメータを true に設定します。