# レガシー DynamoDB 条件パラメータ
このドキュメントでは、DynamoDB のレガシー条件パラメータの概要を示し、代わりに新しい式パラメータの使用を推奨します。AttributesToGet、AttributeUpdates、ConditionalOperator、Expected、KeyConditions、QueryFilter、ScanFilter などのパラメータの詳細と、新しい式パラメータを代わりに使用する方法の例を示します。
**重要**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。
さらに、DynamoDB では、1 つの呼び出しでレガシー条件パラメータと式パラメータを混在させることはできません。例えば、`AttributesToGet` と `ConditionExpression` で `Query` オペレーションを呼び出すとエラーになります。
次の表は、これらのレガシーパラメータを引き続きサポートする DynamoDB API オペレーション、および代替として使用が推奨される式パラメータを示しています。このテーブルは、式パラメータを使用するようにアプリケーションを更新することを検討している場合に役立ちます。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/LegacyConditionalParameters.html)
以下のセクションでは、レガシー条件パラメータについて詳しく説明します。
**Topics**
+ [AttributesToGet (レガシー)](LegacyConditionalParameters.AttributesToGet.md)
+ [AttributeUpdates (レガシー)](LegacyConditionalParameters.AttributeUpdates.md)
+ [ConditionalOperator (レガシー)](LegacyConditionalParameters.ConditionalOperator.md)
+ [Expected (レガシー)](LegacyConditionalParameters.Expected.md)
+ [KeyConditions (レガシー)](LegacyConditionalParameters.KeyConditions.md)
+ [QueryFilter (レガシー)](LegacyConditionalParameters.QueryFilter.md)
+ [ScanFilter (レガシー)](LegacyConditionalParameters.ScanFilter.md)
+ [レガシーパラメータを使用した条件の記述](LegacyConditionalParameters.Conditions.md)
# AttributesToGet (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *ProjectionExpression* を使用](#ProjectionExpression.instead)」を参照してください。
レガシー条件パラメータ `AttributesToGet` は、DynamoDB から取得する 1 つ以上の属性の配列です。属性名が指定されていない場合、すべての属性が返されます。リクエストした属性が見つからない場合、その属性は結果に表示されません。
`AttributesToGet` では、リストまたはマップ型の属性を取得できますが、リストまたはマップ内の個々の要素を取得することはできません。
`AttributesToGet` は、プロビジョニングされたスループットの消費には影響しません。DynamoDB は、アプリケーションに返されるデータ量ではなく、項目のサイズに基づいて、消費される読み込み容量ユニットの数を決定します。
## 代わりに *ProjectionExpression* を使用 - 例
*Music* テーブルから項目を取得する際、一部の属性のみが返されるようにする場合を考えてみます。次の AWS CLI の例に示すように、`AttributesToGet` パラメータを含む `GetItem` リクエストを使用できます。
```
aws dynamodb get-item \
--table-name Music \
--attributes-to-get '["Artist", "Genre"]' \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
代わりに `ProjectionExpression` を使用できます。
```
aws dynamodb get-item \
--table-name Music \
--projection-expression "Artist, Genre" \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}'
```
# AttributeUpdates (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *UpdateExpression* を使用します。](#UpdateExpression.instead)」を参照してください。
`UpdateItem` オペレーションでは、レガシー条件パラメータ `AttributeUpdates` に、変更する属性の名前、それぞれに対して実行するアクション、およびそれぞれの新しい値が含まれます。そのテーブル上のインデックスのインデックスキー属性である属性を更新する場合、属性の型は、テーブルの説明の `AttributesDefinition` で定義されたインデックスキーの型に一致する必要があります。`UpdateItem` を使用して非キー属性を更新できます。
属性値を null にすることはできません。文字列型およびバイナリ型属性の長さは、ゼロより大きくなければなりません。セット型の属性を空にすることはできません。空の値を持つリクエストは、`ValidationException` 例外で拒否されます。
各 `AttributeUpdates` 要素は、変更する属性名と次の属性で構成されます。
+ `Value` - この属性の新しい値 (該当する場合)。
+ `Action` - 更新の実行方法を指定する値。このアクションは、データ型が数値またはセットである既存の属性に対してのみ有効です。`ADD` は他のデータ型に使用しないでください。
指定したプライマリキーを持つ項目がテーブル内に見つかった場合、次の値によって以下のアクションが実行されます。
+ `PUT` - 指定した属性を項目に追加します。属性がすでに存在する場合は、新しい値で置き換えられます。
+ `DELETE` - の値が指定されていない場合、属性とその値を削除します。`DELETE`指定した値のデータ型は、既存の値のデータ型と一致する必要があります。
値のセットが指定されている場合、それらの値が古いセットから削除されます。例えば、属性値が `[a,b,c]` のセットの場合に `DELETE` アクションで `[a,c]` を指定すると、最終的な属性値は `[b]` になります。空のセットを指定するとエラーになります。
+ `ADD` - 属性が存在しない場合、指定された値を項目に追加します。属性が存在する場合、`ADD` の動作は属性のデータ型によって決まります。
+ 既存の属性が数値で、`Value` も数値である場合、`Value` は既存の属性に数学的に追加されます。`Value` が負の数値である場合は、既存の属性から削除されます。
**注記**
`ADD` を使用して、更新の前に存在しない項目の数値をインクリメントまたはデクリメントした場合、DynamoDB は初期値として 0 を使用します。
同様に、更新の前に存在しない属性値をインクリメントまたはデクリメントするために既存の項目に対して `ADD` を使用した場合、DynamoDB は初期値として `0` を使用します。例えば、*itemcount* という属性を持たない項目を更新する際に `ADD` を使用して、この属性に `3` を追加する場合を考えています。この場合、DynamoDB によって *itemcount* 属性が作成され、その初期値が `0` に設定されます。最後に `3` が追加されます。結果は、`3` の値を含む新しい *itemcount* 属性になります。
+ 既存のデータ型がセットで、`Value` もセットである場合、`Value` が既存のセットに追加されます。例えば、属性値が `[1,2]` のセットで、`ADD` アクションで `[3]` が指定されている場合、最終的な属性値は `[1,2,3]` になります。セット属性に対して `ADD` アクションが指定されていて、指定した属性の型が既存のセット型に一致しない場合、エラーが発生します。
両方のセットは同じプリミティブデータ型を持つ必要があります。例えば、既存のデータ型が文字列のセットである場合、`Value` も文字列のセットである必要があります。
指定されたキーを持つ項目がテーブルに見つからない場合、次の値は次のアクションを実行します。
+ `PUT` - DynamoDB で、指定されたプライマリキーで新しい項目が作成され、属性が追加されます。
+ `DELETE` - 存在しない項目から属性を削除することはできないので何の処理も行われません。オペレーションは成功しますが、DynamoDB は新しい項目を作成しません。
+ `ADD` - DynamoDB で、指定されたプライマリキーと属性値の番号 (または数字のセット) を持つ項目を作成します。使用できるデータ型は、数値型と数値セット型のみです。
インデックスキーの一部である属性を指定する場合、それらの属性のデータ型は、テーブルの属性定義内のスキーマのデータ型と一致する必要があります。
## 代わりに *UpdateExpression* を使用 - 例
*Music* テーブル内の項目を変更する場合を考えてみます。次の AWS CLI の例に示すように、`AttributeUpdates` パラメータを含む `UpdateItem` リクエストを使用できます。
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--attribute-updates '{
"Genre": {
"Action": "PUT",
"Value": {"S":"Rock"}
}
}'
```
代わりに `UpdateExpression` を使用できます。
```
aws dynamodb update-item \
--table-name Music \
--key '{
"SongTitle": {"S":"Call Me Today"},
"Artist": {"S":"No One You Know"}
}' \
--update-expression 'SET Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# ConditionalOperator (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。
レガシー条件パラメータ `ConditionalOperator` は、`Expected`、`QueryFilter`、または `ScanFilter` マップ内の条件に適用するために使用される論理演算子です。
+ AND - すべての条件が true に評価された場合、マップ全体が true に評価されます。
+ OR - 条件の少なくとも 1 つが true に評価された場合、マップ全体が true に評価されます。
`ConditionalOperator` を省略した場合、`AND` がデフォルトです。
オペレーションは、マップ全体が true と評価された場合にのみ成功します。
**注記**
このパラメータは、リストおよびマップ型の属性をサポートしません。
# Expected (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *ConditionExpression* を使用します。](#Expected.instead)」を参照してください。
レガシー条件パラメータ `Expected` は `UpdateItem` オペレーションの条件付きブロックです。`Expected` は属性/条件ペアのマップです。マップの各要素は、属性名、比較演算子、および 1 つ以上の値で構成されます。DynamoDB は、比較演算子を使用して、指定した値と属性を比較します。各 `Expected` 要素に対して、評価の結果は true または false のいずれかです。
`Expected` マップで複数の要素を指定すると、デフォルトでは、すべての条件が true に評価される必要があります。つまり、条件は `AND` 演算子を使用して結合されます (`ConditionalOperator` パラメータを使用して条件を OR に設定できます。その場合、すべての条件ではなく、少なくとも 1 つの条件が true に評価される必要があります)。
`Expected` マップが true に評価された場合、オペレーションは成功します。それ以外の場合、オペレーションは失敗します。
`Expected` には以下の要素が含まれます。
+ `AttributeValueList` - 指定された属性に対して評価する 1 つ以上の値。リストの値の数は、使用される `ComparisonOperator` エンジンによって異なります。
数値型の場合、値の比較は数値です。
より大きい、等しい、またはより小さいの文字列値の比較は、UTF-8 バイナリエンコーディングの Unicode に基づきます。例えば、`a` は `A` より大きく、`a` は `B` より大きいと評価されます。
バイナリの場合、DynamoDB がバイナリ値を比較する際、バイナリデータの各バイトは符号なしとして扱われます。
+ `ComparisonOperator` - の属性を評価するためのコンパレータ。`AttributeValueList`比較を実行する際、DynamoDB は強力な整合性のある読み込みを使用します。
次の比較演算子がサポートされています。
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
各比較演算子の説明は、以下のとおりです。
+ `EQ`: 等しい。`EQ` は、リストやマップなど、すべてのデータ型でサポートされます。
`AttributeValueList` には、文字列、数値、バイナリ、文字列セット、数値セット、またはバイナリセットの方の 1 つの `AttributeValue` 要素のみを含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と等しくありません。
+ `NE`: 等しくない。`NE` は、リストやマップを始めとするすべてのデータ型でサポートされています。
`AttributeValueList` には、文字列、数値、バイナリ、文字列セット、数値セット、またはバイナリセットの型の 1 つの `AttributeValue` のみを含めることができます。項目に含まれる `AttributeValue` の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と等しくありません。
+ `LE`: より小さい、または等しい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `LT`: より小さい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `GE`: より大きい、または等しい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `GT`: より大きい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `NOT_NULL`: 属性が存在します。`NOT_NULL` は、リストやマップを始めとするすべてのデータ型でサポートされています。
**注記**
この演算子は、データ型ではなく、属性が存在することをテストします。`NOT_NULL` を使用して属性のデータ型「`a`」を評価する場合、結果はブール値の `true` です。この結果理由は、属性「`a`」が存在するからです。そのデータ型は `NOT_NULL` 比較演算子に関係ありません。
+ `NULL`: 属性は存在しません。`NULL` は、リストやマップを始めとするすべてのデータ型でサポートされています。
**注記**
この演算子は、データ型ではなく、属性が存在しないことをテストします。`a` を使用して属性のデータ型「`NULL`」を評価する場合、結果はブール値の `false` です。この理由は、属性「`a`」が存在するからです。そのデータ型は `NULL` 比較演算子に関係ありません。
+ `CONTAINS`: サブシーケンス、またはセット内の値をチェックします。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。比較のターゲット属性が文字列型である場合、演算子は部分文字列の一致をチェックします。比較のターゲット属性が型バイナリの場合、演算子は入力に一致するターゲットのサブシーケンスを検索します。比較のターゲット属性がセット (「`SS`」、「`NS`」、または「`BS`」) の場合、セットのいずれかの要素との完全一致が見つかったときに true に評価されます。
CONTAINS はリストでサポートされています。「`a CONTAINS b`」を評価するとき、「`a`」はリストである可能性があります。しかし、「`b`」が、セット、マップ、およびリストになることはありません。
+ `NOT_CONTAINS`: サブシーケンスの欠如、またはセット内の値の欠如をチェックします。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。比較のターゲット属性が文字列の場合、演算子は部分文字列の一致の欠如をチェックします。比較のターゲット属性がバイナリである場合、演算子は、入力に一致するターゲットのサブシーケンスの欠如をチェックします。比較のターゲット属性がセット (「`SS`」、「`NS`」、または「`BS`」) のとき、セットのいずれか要素の完全一致が見つから`does not`場合、true に評価されます。
NOT\$1CONTAINS はリストでサポートされています。「`a NOT CONTAINS b`」を評価するとき、「`a`」はリストである可能性があります。しかし、「`b`」は、セット、マップ、およびリストになることはありません。
+ `BEGINS_WITH`: プレフィックスを確認します。
`AttributeValueList` には、文字列またはバイナリ型の 1 つの `AttributeValue` のみを含めることができます (数値やセットではありません)。比較のターゲット属性は、文字列型またはバイナリ型である必要があります (数値型またはセット型ではありません)。
+ `IN`: 2 つのセット内で一致する要素をチェックします。
`AttributeValueList` には、文字列、数値、またはバイナリ型の 1 つ以上の `AttributeValue` 要素を含むことができます (セット型ではありません)。これらの属性は、項目の既存のセット型属性と比較されます。入力セットのいずれかの要素が項目の属性に存在する場合、式は true に評価されます。
+ `BETWEEN`: 最初の値よりも大きいか等しく、2 番目の値よりも小さいか等しくなります。
`AttributeValueList` には、文字列、数値、またはバイナリ (セットではありません) のいずれかの同じ型の 2 つの `AttributeValue` 要素を含む必要があります。ターゲット属性は、ターゲット値が最初の要素より大きいか等しく、2番目の要素より小さいか等しい場合に一致します。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と比較されません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
次のパラメータは、`AttributeValueList` および `ComparisonOperator` の代わりに使用できます。
+ `Value` - DynamoDB が属性と比較する値。
+ `Exists` - 条件付きオペレーションを実行する前に DynamoDB が値を評価するブール値。
+ `Exists` が `true` の場合、DynamoDB は、その属性値がテーブル内にすでに存在するかどうかを確認します。見つかった場合、条件は true に評価されます。それ以外の場合、条件は false に評価されます。
+ `Exists` が `false` の場合、DynamoDB は属性値がテーブル内に存在`not`ことが予期されます。実際に値が存在しない場合、仮定は有効であり、条件は true に評価されます。存在しないという仮定にもかかわらず値が見つかった場合、条件は false に評価されます。
`Exists` のデフォルト値は `true` です。
`Value` パラメータと `Exists` パラメータは、`AttributeValueList` および `ComparisonOperator` と互換性がありません。両方のパラメータセットを同時に使用すると、DynamoDB は `ValidationException` 例外を返します。
**注記**
このパラメータは、リストおよびマップ型の属性をサポートしません。
## 代わりに *ConditionExpression* を使用 - 例
特定の条件が true の場合のみに *Music* テーブル内の項目を変更する場合を考えてみます。次の AWS CLI の例に示すように、`Expected` パラメータを含む `UpdateItem` リクエストを使用できます。
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--attribute-updates '{
"Price": {
"Action": "PUT",
"Value": {"N":"1.98"}
}
}' \
--expected '{
"Price": {
"ComparisonOperator": "LE",
"AttributeValueList": [ {"N":"2.00"} ]
}
}'
```
代わりに `ConditionExpression` を使用できます。
```
aws dynamodb update-item \
--table-name Music \
--key '{
"Artist": {"S":"No One You Know"},
"SongTitle": {"S":"Call Me Today"}
}' \
--update-expression 'SET Price = :p1' \
--condition-expression 'Price <= :p2' \
--expression-attribute-values '{
":p1": {"N":"1.98"},
":p2": {"N":"2.00"}
}'
```
# KeyConditions (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *KeyConditionExpression* を使用します。](#KeyConditionExpression.instead)」を参照してください。
レガシー条件パラメータ `KeyConditions` には、`Query` オペレーションの選択基準が含まれています。テーブルに対するクエリでは、テーブルのプライマリキー属性に対してのみ条件を設定できます。`EQ` 条件としてパーティションキーの名前と値を指定する必要があります。ソートキーを参照する 2 番目の条件を指定できます (オプション)。
**注記**
ソートキー条件を指定しない場合、パーティションキーに一致するすべての項目が取得されます。`FilterExpression` または `QueryFilter` が存在する場合、これは項目が取得された後に適用されます。
インデックスに対するクエリでは、インデックスキー属性に対してのみ条件を設定できます。`EQ` 条件としてインデックスパーティションキーの名前と値を指定する必要があります。インデックスソートキーを参照する 2 番目の条件を指定できます (オプション)。
各 `KeyConditions` 要素は、比較する属性名と次の属性で構成されます。
+ `AttributeValueList` - 指定された属性に対して評価する 1 つ以上の値。リストの値の数は、使用される `ComparisonOperator` エンジンによって異なります。
数値型の場合、値の比較は数値です。
より大きい、等しい、またはより小さいの文字列値の比較は、UTF-8 バイナリエンコーディングの Unicode に基づきます。例えば、`a` は `A` より大きく、`a` は `B` より大きいと評価されます。
バイナリの場合、DynamoDB がバイナリ値を比較する際、バイナリデータの各バイトは符号なしとして扱われます。
+ `ComparisonOperator` - 属性を評価するためのコンパレータ。例えば、等しい、より大きい、より小さいなどです。
`KeyConditions` の場合、次の比較演算子がサポートされています。
`EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN`
これらの比較演算子の説明を次に示します。
+ `EQ`: 等しい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` のみ含めることができます。リクエストで指定されているもの以外の型の `AttributeValue` 要素が項目に含まれる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と等しくありません。
+ `LE`: より小さい、または等しい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `LT`: より小さい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `GE`: より大きい、または等しい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `GT`: より大きい。
`AttributeValueList` には、文字列、数値、またはバイナリの型 (セット型ではありません) の 1 つの `AttributeValue` 要素のみ含めることができます。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と等しくありません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
+ `BEGINS_WITH`: プレフィックスを確認します。
`AttributeValueList` には、文字列またはバイナリ型の 1 つの `AttributeValue` のみを含めることができます (数値やセットではありません)。比較のターゲット属性は、文字列型またはバイナリ型である必要があります (数値型またはセット型ではありません)。
+ `BETWEEN`: 最初の値よりも大きいか等しく、2 番目の値よりも小さいか等しくなります。
`AttributeValueList` には、文字列、数値、またはバイナリ (セットではありません) のいずれかの同じ型の 2 つの `AttributeValue` 要素を含む必要があります。ターゲット属性は、ターゲット値が最初の要素より大きいか等しく、2番目の要素より小さいか等しい場合に一致します。項目に含まれる `AttributeValue` 要素の型がリクエストで指定されている型と異なる場合、値は一致しません。例えば、`{"S":"6"}` は `{"N":"6"}` と比較されません。また、`{"N":"6"}` は `{"NS":["6", "2", "1"]}` と比較されません。
## 代わりに *KeyConditionExpression* を使用 - 例
同じパーティションキーを持つ複数の項目を *Music* テーブルから取得する場合を考えてみます。次の AWS CLI の例に示すように、`Query` パラメータを含む `KeyConditions` リクエストを使用できます。
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist":{
"ComparisonOperator":"EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
},
"SongTitle":{
"ComparisonOperator":"BETWEEN",
"AttributeValueList": [ {"S": "A"}, {"S": "M"} ]
}
}'
```
代わりに `KeyConditionExpression` を使用できます。
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a AND SongTitle BETWEEN :t1 AND :t2' \
--expression-attribute-values '{
":a": {"S": "No One You Know"},
":t1": {"S": "A"},
":t2": {"S": "M"}
}'
```
# QueryFilter (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *FilterExpression* を使用します。](#FilterExpression.instead)」を参照してください。
`Query` オペレーションでは、レガシー条件パラメータ `QueryFilter` は、項目が読み込まれた後にクエリ結果を評価し、目的の値のみを返す条件です。
このパラメータは、リストおよびマップ型の属性をサポートしません。
**注記**
`QueryFilter` は、項目が読み込まれた後に適用されます。フィルタリングのプロセスでは、追加の読み込み容量ユニットは消費されません。
`QueryFilter` マップで複数の条件を指定すると、デフォルトでは、すべての条件が true に評価される必要があります。つまり、条件は `AND` 演算子を使用して結合されます ([ConditionalOperator (レガシー)](LegacyConditionalParameters.ConditionalOperator.md) パラメータを使用して条件を OR に設定できます。その場合、すべての条件ではなく、少なくとも 1 つの条件が true に評価される必要があります)。
`QueryFilter` ではキー属性を使用できません。パーティションキーまたはソートキーでフィルター条件を定義することはできません。
各 `QueryFilter` 要素は、比較する属性名と次の属性で構成されます。
+ `AttributeValueList` - 指定された属性に対して評価する 1 つ以上の値。リスト内の値の数は、`ComparisonOperator` で指定されている演算子により異なります。
数値型の場合、値の比較は数値です。
より大きい、等しい、より小さい文字列値の比較は、UTF-8 バイナリエンコーディングに基づいています。例えば、`a` は `A` より大きく、`a` は `B` より大きいと評価されます。
バイナリの場合、DynamoDB がバイナリ値を比較する際、バイナリデータの各バイトは符号なしとして扱われます。
JSON でのデータ型指定については、「[DynamoDB 低レベル API](Programming.LowLevelAPI.md)」を参照してください。
+ `ComparisonOperator` - 属性を評価するためのコンパレータ。例えば、等しい、より大きい、より小さいなどです。
次の比較演算子がサポートされています。
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## 代わりに *FilterExpression* を使用 - 例
*Music* テーブルをクエリし、一致する項目に条件を適用する場合を考えてみます。次の AWS CLI の例に示すように、`Query` パラメータを含む `QueryFilter` リクエストを使用できます。
```
aws dynamodb query \
--table-name Music \
--key-conditions '{
"Artist": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S": "No One You Know"} ]
}
}' \
--query-filter '{
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N": "1.00"} ]
}
}'
```
代わりに `FilterExpression` を使用できます。
```
aws dynamodb query \
--table-name Music \
--key-condition-expression 'Artist = :a' \
--filter-expression 'Price > :p' \
--expression-attribute-values '{
":p": {"N":"1.00"},
":a": {"S":"No One You Know"}
}'
```
# ScanFilter (レガシー)
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「[代わりに *FilterExpression* を使用します。](#FilterExpression2.instead)」を参照してください。
`Scan` オペレーションでは、レガシー条件パラメータ `ScanFilter` は、スキャン結果を評価し、目的の値のみを返す条件です。
**注記**
このパラメータは、リストおよびマップ型の属性をサポートしません。
複数の条件を指定すると、`ScanFilter` マップの場合、デフォルトでは、すべての条件が true に評価される必要があります。つまり、すべての条件が一緒に AND 処理されます。([ConditionalOperator (レガシー)](LegacyConditionalParameters.ConditionalOperator.md) パラメータを使用して条件を OR に設定できます。その場合、すべての条件ではなく、少なくとも 1 つの条件が true に評価される必要があります)。
各 `ScanFilter` 要素は、比較する属性名と次の属性で構成されます。
+ `AttributeValueList` - 指定された属性に対して評価する 1 つ以上の値。リスト内の値の数は、`ComparisonOperator` で指定されている演算子により異なります。
数値型の場合、値の比較は数値です。
より大きい、等しい、より小さい文字列値の比較は、UTF-8 バイナリエンコーディングに基づいています。例えば、`a` は `A` より大きく、`a` は `B` より大きいと評価されます。
バイナリの場合、DynamoDB がバイナリ値を比較する際、バイナリデータの各バイトは符号なしとして扱われます。
JSON でのデータ型指定については、「[DynamoDB 低レベル API](Programming.LowLevelAPI.md)」を参照してください。
+ `ComparisonOperator` - 属性を評価するためのコンパレータ。例えば、等しい、より大きい、より小さいなどです。
次の比較演算子がサポートされています。
`EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN`
## 代わりに *FilterExpression* を使用 - 例
*Music* テーブルをスキャンし、一致する項目に条件を適用する場合を考えてみます。次の AWS CLI の例に示すように、`Scan` パラメータを含む `ScanFilter` リクエストを使用できます。
```
aws dynamodb scan \
--table-name Music \
--scan-filter '{
"Genre":{
"AttributeValueList":[ {"S":"Rock"} ],
"ComparisonOperator": "EQ"
}
}'
```
代わりに `FilterExpression` を使用できます。
```
aws dynamodb scan \
--table-name Music \
--filter-expression 'Genre = :g' \
--expression-attribute-values '{
":g": {"S":"Rock"}
}'
```
# レガシーパラメータを使用した条件の記述
**注記**
可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。
このセクションでは、`Expected`、`QueryFilter`、`ScanFilter` などのレガシーパラメータで使用するための条件を書き込む方法について説明します。
**注記**
新しいアプリケーションでは、式パラメータを使用する必要があります。詳細については、「[DynamoDB での式の使用](Expressions.md)」を参照してください。
## シンプルな条件
属性値を使用すると、テーブル属性との比較条件を記述できます。条件は常にtrueまたはfalseに評価され、以下のもので構成されます。
+ `ComparisonOperator` — より大きい、より小さい、等しいなど。
+ `AttributeValueList` (オプション) — 比較対象の属性値。使用する `ComparisonOperator` に応じて、`AttributeValueList` には、1 つ、2 つ、またはそれ以上の値が含まれることがあります。まったく存在しないこともあります。
このセクションでは、さまざまな比較演算子と、条件での使用方法の例について説明します。
### 属性値を含まない比較演算子
+ `NOT_NULL` - 属性が存在する場合は true です。
+ `NULL` - 属性が存在しない場合は true です。
これらの演算子を使用して、属性が存在するか、存在しないかをチェックします。比較する値がないので、`AttributeValueList` は指定しません。
**例**
*Dimensions* 属性が存在する場合、次の式は true と評価されます。
```
...
"Dimensions": {
ComparisonOperator: "NOT_NULL"
}
...
```
### 属性値を 1 つ含む比較演算子
+ `EQ` - 属性が値と等しい場合、true です。
`AttributeValueList` には、文字列、数値、バイナリ、文字列セット、数値セット、またはバイナリセットの型の 1 つの値のみを含めることができます。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。例えば、文字列 `"3"` は数値 `3` と等しくありません。また、数値 `3` は数値セット `[3, 2, 1]` と等しくありません。
+ `NE` - 属性が値と等しくない場合、true です。
`AttributeValueList` には、文字列、数値、バイナリ、文字列セット、数値セット、またはバイナリセットの型の 1 つの値のみを含めることができます。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。
+ `LE` - 属性が値より小さいか、等しい場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の `AttributeValue` が項目に含まれる場合、値は一致しません。
+ `LT` - 属性が値より小さい場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。
+ `GE` - 属性が値より大きいか、等しい場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。
+ `GT` - 属性が値より大きい場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。
+ `CONTAINS` - 値がセット内に存在する場合、またはある値に別の値が含まれている場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。比較のターゲット属性が文字列の場合、演算子は部分文字列の一致をチェックします。比較のターゲット属性がバイナリの場合、演算子は入力に一致するターゲットのサブシーケンスを検索します。比較のターゲット属性がセットの場合、セットのいずれかの要素との完全一致が見つかると、演算子は true と評価されます。
+ `NOT_CONTAINS` - 値がセット内に存在*しない*場合、またはある値に別の値が含まれている場合、true です。
`AttributeValueList` は、文字列、数値、またはバイナリのうち 1 つの値のみを含むことができます (セットではありません)。比較のターゲット属性が文字列の場合、演算子は部分文字列の一致の欠如をチェックします。比較のターゲット属性がバイナリである場合、演算子は、入力に一致するターゲットのサブシーケンスの欠如をチェックします。比較のターゲット属性がセットの場合、セットのいずれかの要素との完全一致が見つから*ない*と、演算子は true と評価されます。
+ `BEGINS_WITH` - 属性の最初の数文字が指定された値と一致する場合、true です。この演算子は数値の比較に使用しないでください。
`AttributeValueList` には、文字列またはバイナリ型の 1 つの値のみを含めることができます (数値やセットではありません)。比較のターゲット属性は、(数値またはセットではなく) 文字列またはバイナリである必要があります。
これらの演算子を使用して、属性と値を比較します。1 つの値で構成される `AttributeValueList` を指定する必要があります。ほとんどの演算子では、この値はスカラーである必要があります。ただし、`EQ` 演算子と `NE` 演算子はセットもサポートします。
**例**
以下の条件が満たされる場合、次の式は true と評価されます。
+ 商品の価格が 100 より大きい。
```
...
"Price": {
ComparisonOperator: "GT",
AttributeValueList: [ {"N":"100"} ]
}
...
```
+ 商品カテゴリが「Bo」で始まる。
```
...
"ProductCategory": {
ComparisonOperator: "BEGINS_WITH",
AttributeValueList: [ {"S":"Bo"} ]
}
...
```
+ 製品には、赤、緑、または黒がある。
```
...
"Color": {
ComparisonOperator: "EQ",
AttributeValueList: [
[ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
]
}
...
```
**注記**
セットデータ型を比較する場合、要素の順序は関係ありません。DynamoDB は、リクエストで指定した順序に関係なく、同じ値のセットを持つ項目のみを返します。
### 属性値を 2 つ含む比較演算子
+ `BETWEEN` - 値が下限と上限の間にある場合 (エンドポイントを含む) は true です。
`AttributeValueList` には、文字列、数値、またはバイナリ (セットではありません) のいずれかの同じ型の 2 つの要素を含む必要があります。ターゲット属性は、ターゲット値が最初の要素より大きいか等しく、2番目の要素より小さいか等しい場合に一致します。リクエストで指定されているもの以外の型の値が項目に含まれる場合、値は一致しません。
この演算子を使用して、属性値が範囲内にあるかどうかを判断します。`AttributeValueList` は、同じ型 (文字列、数値、またはバイナリ) の 2 つのスカラー要素を含む必要があります。
**例**
製品の料金が 100 ～ 200 の場合、次の表現は true と評価されます。
```
...
"Price": {
ComparisonOperator: "BETWEEN",
AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
}
...
```
### 属性値 *N* を含む比較演算子
+ `IN` - 値が列挙リスト内のいずれかの値と等しい場合、true です。リストではスカラー値のみがサポートされ、セットはサポートされません。一致するには、ターゲット属性は、同じ型と値である必要があります。
`AttributeValueList` は、文字列、数値、またはバイナリの 1 つ以上の要素を含むことができます (セットではありません)。これらの属性は、項目の既存の非セット型属性と比較されます。入力セットの*いずれか*の要素が項目の属性に存在する場合、式は true に評価されます。
`AttributeValueList` は、文字列、数値、またはバイナリの 1 つまたは複数の値を含むことができます (セットではありません)。比較のターゲット属性は、一致対象と同じ型および同じ値である必要があります。文字列は、文字列セットと一致しません。
この演算子を使用して、指定された値が列挙リスト内にあるかどうかを判断します。`AttributeValueList` ではスカラー値はいくつでも指定できますが、すべて同じデータ型である必要があります。
**例**
*ID* の値が 201、203、205 の場合、次の式は true と評価されます。
```
...
"Id": {
ComparisonOperator: "IN",
AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
}
...
```
## 複数の条件の使用
DynamoDB では、複数の条件を組み合わせて、複雑な表現を作成できます。これを行うには、オプションの [ConditionalOperator (レガシー)](LegacyConditionalParameters.ConditionalOperator.md) を使用して、少なくとも 2 つの式を指定します。
デフォルトでは、複数の条件を指定した場合、式全体が true に評価されるには、*すべて*の条件が true に評価される必要があります。言い換えると、暗黙の *AND* オペレーションが行われます。
**例**
商品が 600 ページ以上の本の場合、次の表現は true と評価されます。どちらの条件も暗黙的に *AND* で処理されるので、true と評価される必要があります。
```
...
"ProductCategory": {
ComparisonOperator: "EQ",
AttributeValueList: [ {"S":"Book"} ]
},
"PageCount": {
ComparisonOperator: "GE",
AttributeValueList: [ {"N":600"} ]
}
...
```
[ConditionalOperator (レガシー)](LegacyConditionalParameters.ConditionalOperator.md) を使用して、*AND* オペレーションが行われることを明確にすることができます。次の例は、前の例と同様に動作します。
```
...
"ConditionalOperator" : "AND",
"ProductCategory": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"N":"Book"} ]
},
"PageCount": {
"ComparisonOperator": "GE",
"AttributeValueList": [ {"N":600"} ]
}
...
```
`ConditionalOperator` を *OR* に設定することもできます。その場合、*少なくとも 1 つ*の条件が true に評価される必要があります。
**例**
製品がマウンテンバイクの場合、特定のブランド名である場合、または価格が 100 より大きい場合、次の表現は true と評価されます。
```
...
ConditionalOperator : "OR",
"BicycleType": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Mountain" ]
},
"Brand": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"S":"Brand-Company A" ]
},
"Price": {
"ComparisonOperator": "GT",
"AttributeValueList": [ {"N":"100"} ]
}
...
```
**注記**
複雑な表現では、条件は最初の条件から最後の条件まで順番に処理されます。
1 つの表現で AND と OR の両方を使用することはできません。
## その他の条件演算子
DynamoDB の以前のリリースでは、`Expected` パラメータの動作は、条件付き書き込みでは異なりました。`Expected` マップ内の各項目は、以下とともに、チェックする DynamoDB の属性名を表していました。
+ `Value` - 属性に対して比較する値。
+ `Exists` — オペレーションを試みる前に値が存在するかどうかを調べます。
`Value` と `Exists` のオプションは、引き続き DynamoDB でサポートされていますが、等価条件または属性が存在するかどうかのテストのみが可能です。`ComparisonOperator` と `AttributeValueList` オプションを使用すると、より広い範囲の条件を構築できるので、これらのオプションを使用することをお勧めします。
**Example**
`DeleteItem` は、本が出版されていないかどうかを確認し、この条件が true である場合にのみ削除できます。レガシー条件を使用する AWS CLI の例を次に示します。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"Exists": true,
"Value": {"BOOL":false}
}
}'
```
次の例では、同じことを実行しますが、レガシー条件は使用しません。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{
"Id": {"N":"600"}
}' \
--expected '{
"InPublication": {
"ComparisonOperator": "EQ",
"AttributeValueList": [ {"BOOL":false} ]
}
}'
```
**Example**
`PutItem` オペレーションは、同じプライマリキー属性を持つ既存の項目を上書きしないように保護できます。レガシー条件を使用する例を次に示します。
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "Exists": false }
}'
```
次の例では、同じことを実行しますが、レガシー条件は使用しません。
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item '{
"Id": {"N":"500"},
"Title": {"S":"Book 500 Title"}
}' \
--expected '{
"Id": { "ComparisonOperator": "NULL" }
}'
```
**注記**
`Expected` マップ内の条件には、レガシーの `Value` オプションと `Exists` オプションを `ComparisonOperator` と `AttributeValueList` と一緒に使用しないでください。一緒に使用すると、条件付き書き込みは失敗します。