# DynamoDB でのクエリオペレーションのフィルター式
<a name="Query.FilterExpression"></a>

`Query` 結果の絞り込みが必要な場合は、オプションでフィルタ式を指定できます。*フィルタ式*によって、`Query` 結果の内、どの項目を返すべきか確定します。他のすべての結果は破棄されます。

フィルタ式は、`Query` の完了後、結果が返される前に適用されます。そのため、`Query` は、フィルタ式があるかどうかにかかわらず、同じ量の読み込みキャパシティーを消費します。

1 回の `Query` オペレーションで、最大 1 MB のデータを取得できます。この制限は、フィルタ式を評価する前に適用されます。

フィルタ式には、パーティションキーまたはソートキーの属性を含めることはできません。フィルタ式ではなく、キー条件式でこれらの属性を指定する必要があります。

フィルター式の構文は、キー条件式の構文と似ています。フィルター式は、キー条件式と同じコンパレータ、関数および論理演算子を使用できます。さらに、フィルター式では、非等号演算子 (`<>`)、`OR` 演算子、`CONTAINS` 演算子、`IN` 演算子、`BEGINS_WITH` 演算子、`BETWEEN` 演算子、`EXISTS` 演算子、および `SIZE` 演算子を使用できます。詳細については、「[DynamoDB でのクエリオペレーションのキー条件式](Query.KeyConditionExpressions.md)」および「[フィルター式と条件式の構文](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax)」を参照してください。

**Example**  
以下の AWS CLI の例では、`Thread` テーブルに対して、特定の `ForumName` (パーティションキー) および `Subject` (ソートキー) についてのクエリを実行します。見つかった項目のうち、最も一般的なディスカッションスレッド (つまり、一定数以上の `Views` があるスレッド) のみが返されます。  

```
aws dynamodb query \
    --table-name Thread \
    --key-condition-expression "ForumName = :fn and Subject begins_with :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 の予約語](ReservedWords.md) を参照)、この例では `#v` をプレースホルダーとして使用することにご注意ください。詳細については、「[DynamoDB の式の属性名 (エイリアス)](Expressions.ExpressionAttributeNames.md)」を参照してください。

**注記**  
フィルタ式は、`Query` 結果セットから項目を削除します。可能であれば、大量の項目を取得してもそのほとんどを破棄する必要がある場合、 `Query` の使用は避けてください。