レガシーパラメータを使用した条件の記述

注記

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

このセクションでは、Expected、QueryFilter、ScanFilter などのレガシーパラメータで使用するための条件を書き込む方法について説明します。

注記

新しいアプリケーションでは、式パラメータを使用する必要があります。詳細については、「DynamoDB での式の使用」を参照してください。

シンプルな条件

属性値を使用すると、テーブル属性との比較条件を記述できます。条件は常に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 (レガシー) を使用して、少なくとも 2 つの式を指定します。

デフォルトでは、複数の条件を指定した場合、式全体が true に評価されるには、すべての条件が true に評価される必要があります。言い換えると、暗黙の AND オペレーションが行われます。

例

商品が 600 ページ以上の本の場合、次の表現は true と評価されます。どちらの条件も暗黙的に AND で処理されるので、true と評価される必要があります。


... 
    "ProductCategory": { 
        ComparisonOperator: "EQ",
        AttributeValueList: [ {"S":"Book"} ]
    },
    "PageCount": { 
        ComparisonOperator: "GE",
        AttributeValueList: [ {"N":600"} ]
    }
...

ConditionalOperator (レガシー) を使用して、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 オプションを使用すると、より広い範囲の条件を構築できるので、これらのオプションを使用することをお勧めします。

例

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} ]
        } 
    }'

例

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 と一緒に使用しないでください。一緒に使用すると、条件付き書き込みは失敗します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

ScanFilter

以前の低レベル API バージョン (2011-12-05)