Conditions d'écriture avec des paramètres hérités

Note

Dans la mesure du possible, nous vous recommandons d'utiliser les nouveaux paramètres d'expression plutôt que ces paramètres hérités. Pour de plus amples informations, veuillez consulter Utilisation d'expressions dans DynamoDB.

La section suivante décrit comment écrire des conditions pour une utilisation avec des paramètres hérités, tels que Expected, QueryFilter et ScanFilter.

Note

Les nouvelles applications doivent utiliser des paramètres d'expression à la place. Pour de plus amples informations, veuillez consulter Utilisation d'expressions dans DynamoDB.

Conditions simples

Avec des valeurs d'attribut, vous pouvez écrire des conditions pour des comparaisons par rapport à des attributs de table. Une condition produit toujours un résultat true (vrai) ou false (faux), et comprend les éléments suivants :

• ComparisonOperator – Supérieur, inférieur, égal, etc.

• AttributeValueList (facultatif) – Valeur(s) d'attribut à comparer. En fonction de l'opérateur ComparisonOperator utilisé, la liste AttributeValueList peut contenir une ou plusieurs valeurs  ou être totalement absente.

Les sections suivantes décrivent les différents opérateurs de comparaison, et fournissent des exemples d'utilisation de ceux-ci dans des conditions.

Opérateurs de comparaison sans valeur d'attribut

• NOT_NULL – true si un attribut existe.

• NULL – true si aucun attribut n'existe.

Utilisez ces opérateurs pour vérifier si un attribut existe ou non. À défaut de valeur à comparer, ne spécifiez pas AttributeValueList.

Exemple

L'expression suivante a la valeur true si l'attribut Dimensions existe.

...
    "Dimensions": {
         ComparisonOperator: "NOT_NULL"
    }
...

Opérateurs de comparaison avec une seule valeur d'attribut

• EQ – true si un attribut est égal à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre, Binaire, Ensemble de chaînes, Ensemble de nombres ou Ensemble de binaires. Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas. Par exemple, la chaîne "3" n'est pas égale au nombre 3. En outre, le nombre 3 n'est pas égal à l'ensemble de nombres [3, 2, 1].

• NE – true si un attribut n'est pas égal à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre, Binaire, Ensemble de chaînes, Ensemble de nombres ou Ensemble de binaires. Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

• LE – true si un attribut est inférieur ou égal à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si un élément contient une AttributeValue d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

• LT – true si un attribut est inférieur à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

• GE – true si un attribut est supérieur ou égal à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

• GT – true si un attribut est supérieur à une valeur.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

• CONTAINS – true si une valeur est présente dans un ensemble, ou si une valeur en contient une autre.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si l'attribut cible de la comparaison est de type Chaîne, l'opérateur vérifie la présence d'une sous-chaîne correspondante. Si l'attribut cible de la comparaison est de type Binaire, l'opérateur vérifie la présence d'une sous-séquence de la cible correspondant à l'entrée. Si l'attribut cible de la comparaison est un ensemble, l'opérateur évalue true s'il trouve une correspondance exacte avec un membre de l'ensemble.

• NOT_CONTAINS – true si une valeur n'est pas présente dans un ensemble, ou si une valeur n'en contient pas une autre.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne, Nombre ou Binaire (pas Ensemble). Si l'attribut cible de la comparaison est de type Chaîne, l'opérateur vérifie l'absence de sous-chaîne correspondante. Si l'attribut cible de la comparaison est de type Binaire, l'opérateur vérifie l'absence d'une sous-séquence de la cible correspondant à l'entrée. Si l'attribut cible de la comparaison est un ensemble, l'opérateur évalue true s'il ne trouve pas une correspondance exacte avec un membre de l'ensemble.

• BEGINS_WITH – true si les premiers caractères d'un attribut correspondent à la valeur fournie. N'utilisez pas cet opérateur pour comparer des nombres.

  AttributeValueList ne peut contenir qu'une seule valeur de type Chaîne ou Binaire (pas Nombre ou Ensemble). L'attribut cible de la comparaison doit être une chaîne ou un binaire (pas un nombre ou un ensemble).

Utilisez ces opérateurs pour comparer un attribut avec une valeur. Vous devez spécifier une AttributeValueList contenant une valeur unique. Pour la plupart des opérateurs, cette valeur doit être un scalaire, mais les opérateurs EQ et NE prennent également en charge des ensembles.

Exemples

Les expressions suivantes prennent la valeur true si :

• Le prix d'un produit est supérieur à 100.

  ...
      "Price": {
          ComparisonOperator: "GT",
          AttributeValueList: [ {"N":"100"} ]
      }
  ...

• Une catégorie de produits commence par « Bo ».

  ...
      "ProductCategory": {
          ComparisonOperator: "BEGINS_WITH",
          AttributeValueList: [ {"S":"Bo"} ]
      }
  ...

• Un produit est disponible en rouge, vert ou noir :

  ...
      "Color": {
          ComparisonOperator: "EQ",
          AttributeValueList: [
              [ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ]
          ]
      }
  ...

  Note

  Lors de la comparaison de types de données d'ensemble, l'ordre des éléments n'a pas d'importance. DynamoDB renvoie uniquement les éléments ayant le même ensemble de valeurs, quel que soit l'ordre dans lequel vous les spécifiez dans votre demande.

Opérateurs de comparaison avec deux valeurs d'attribut

• BETWEEN – true si une valeur s'inscrit entre une limite inférieure et une limite supérieure, points de terminaison inclus.

  AttributeValueList doit contenir deux éléments du même type, Chaîne, Nombre ou Binaire (pas Ensemble). Un attribut cible correspond si la valeur cible est supérieure ou égale au premier élément, et inférieure ou égale au deuxième. Si un élément contient une valeur d'un type différent de celui spécifié dans la demande, la valeur ne correspond pas.

Utilisez cet opérateur pour déterminer si une valeur d'attribut s'inscrit dans une plage. AttributeValueList doit contenir deux éléments scalaires du même type, Chaîne, Nombre ou Binaire.

Exemple

L'expression suivante prend la valeur true si le prix d'un produit est compris entre 100 et 200.

...
    "Price": {
        ComparisonOperator: "BETWEEN",
        AttributeValueList: [ {"N":"100"}, {"N":"200"} ]
    }
...

Opérateurs de comparaison avec n valeurs d'attribut

• IN – true si une valeur est égale à l'une des valeurs d'une liste énumérée. Seules les valeurs scalaires sont prises en charge dans la liste, pas les ensembles. Pour correspondre, l'attribut cible doit être du même type et avoir exactement la même valeur.

  AttributeValueList peut contenir un ou plusieurs éléments de type Chaîne, Nombre ou Binaire (pas Ensemble). Ces attributs sont comparés à un attribut de type autre qu'Ensemble existant d'un élément. Si des éléments de l'ensemble en entrée sont présents dans l'attribut de l'élément, l'expression prend la valeur true.

  AttributeValueList peut contenir une ou plusieurs valeurs de type Chaîne, Nombre ou Binaire (pas Ensemble). Pour correspondre, l'attribut cible de la comparaison doit être du même type et avoir exactement la même valeur. Une chaîne ne correspond jamais à un ensemble de chaîne.

Utilisez cet opérateur pour déterminer si la valeur fournie figure dans une liste énumérée. Vous pouvez spécifier n'importe quel nombre de valeurs scalaires dans AttributeValueList, mais elles doivent toutes être du même type de données.

Exemple

L'expression suivante prend la valeur true si la valeur d'Id est 201, 203 ou 205.

...
    "Id": {
        ComparisonOperator: "IN",
        AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ]
    }
...

Utilisation de plusieurs conditions

DynamoDB permet de combiner plusieurs conditions pour former des expressions complexes. Pour cela, fournissez au moins deux expressions avec un opérateur ConditionalOperator (héritage) facultatif.

Par défaut, lorsque vous spécifiez plusieurs conditions, toutes les conditions doivent avoir la valeur true pour que l'expression entière prenne la valeur true. En d'autres termes, une ANDopération implicite a lieu.

Exemple

L'expression suivante prend la valeur true si un produit est un livre qui contient au moins 600 pages. Les deux conditions doivent être considérées comme vraies, puisqu'elles sont implicitement liées ANDensemble.

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

Vous pouvez l'ConditionalOperator (héritage)utiliser pour préciser qu'une ANDopération aura lieu. L'exemple suivant se comporte de la même manière que le précédent.

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

Vous pouvez également définir l'opérateur ConditionalOperator sur OR, ce qui signifie que le résultat d'au moins une des conditions doit être true.

Exemple

L'expression suivante prend la valeur true si un produit est un VTT (mountain bike), s'il est d'une marque particulière ou si son prix est supérieur à 100.

... 
    ConditionalOperator : "OR",
    "BicycleType": { 
        "ComparisonOperator": "EQ",
        "AttributeValueList": [ {"S":"Mountain" ]
    },
    "Brand": { 
        "ComparisonOperator": "EQ",
        "AttributeValueList": [ {"S":"Brand-Company A" ]
    },
    "Price": { 
        "ComparisonOperator": "GT",
        "AttributeValueList": [ {"N":"100"} ]
    }
...

Note

Dans une expression complexe, les conditions sont traitées dans l'ordre, de la première à la dernière.

Vous ne pouvez pas utiliser à la fois AND et OU dans une seule expression.

Autres opérateurs conditionnels

Dans les versions précédentes de DynamoDB, le paramètre Expected se comportait différemment pour les écritures conditionnelles. Chaque élément du mappage Expected représentait un nom d'attribut à vérifier par DynamoDB, ainsi que les éléments suivants :

• Value – Valeur à laquelle comparer l'attribut.

• Exists – Détermine si la valeur existe avant de tenter l'opération.

Les options Value et Exists sont toujours prises en charge dans DynamoDB. Toutefois, elles vous permettent uniquement de tester une condition d'égalité ou l'existence d'un attribut. Nous vous recommandons d'utiliser ComparisonOperator et AttributeValueList à la place, car ces options vous permettent de construire un éventail beaucoup plus large de conditions.

Exemple

Une opération DeleteItem peut vérifier si un livre n'est plus publié, et ne le supprimer que si le résultat de cette condition est true. Voici un exemple AWS CLI utilisant une condition héritée :

aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{
        "Id": {"N":"600"}
    }' \
    --expected '{
        "InPublication": { 
            "Exists": true, 
            "Value": {"BOOL":false} 
        } 
    }'

L'exemple suivant fait la même chose, mais n'utilise pas de condition héritée :

aws dynamodb delete-item \
    --table-name ProductCatalog \
    --key '{
        "Id": {"N":"600"}
    }' \
    --expected '{
        "InPublication": { 
            "ComparisonOperator": "EQ", 
            "AttributeValueList": [ {"BOOL":false} ]
        } 
    }'

Exemple

Une opération PutItem peut protéger contre le remplacement d'un élément existant par les mêmes attributs de clé primaire. Voici un exemple utilisant une condition héritée :

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item '{
      "Id": {"N":"500"},
        "Title": {"S":"Book 500 Title"}
    }' \
    --expected '{
        "Id": { "Exists": false } 
    }'

L'exemple suivant fait la même chose, mais n'utilise pas de condition héritée :

aws dynamodb put-item \
    --table-name ProductCatalog \
    --item '{
      "Id": {"N":"500"},
        "Title": {"S":"Book 500 Title"}
    }' \
    --expected '{
        "Id": { "ComparisonOperator": "NULL" } 
    }'

Note

Pour les conditions dans le mappage Expected, n'utilisez pas les options Value et Exists héritées avec ComparisonOperator et AttributeValueList. Si vous le faites, votre écriture conditionnelle échouera.