Expected (レガシー)

注記

可能な限り、これらのレガシーパラメータの代わりに新しい式パラメータを使用することをお勧めします。詳細については、「DynamoDB での式の使用」を参照してください。このパラメータに代わる新しいパラメータの具体的な情報については、「代わりに ConditionExpression を使用します。」を参照してください。

レガシー条件パラメータ 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_CONTAINS はリストでサポートされています。「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"}
    }'