Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Utiliser des expressions
<a name="ddb-mapper-expressions"></a>

****  
**DynamoDB Mapper est une version préliminaire pour les développeurs. Les fonctionnalités ne sont pas complètes et sont susceptibles d'être modifiées.**

Certaines opérations DynamoDB [acceptent](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html) des expressions que vous pouvez utiliser pour spécifier des contraintes ou des conditions. DynamoDB Mapper fournit un DSL Kotlin idiomatique pour créer des expressions. Le DSL améliore la structure et la lisibilité de votre code et facilite également l'écriture d'expressions. 

Cette section décrit la syntaxe DSL et fournit divers exemples. 

## Utiliser des expressions dans les opérations
<a name="ddb-mapper-expressions-basic-usage"></a>

Vous utilisez des expressions dans des opérations telles que`scan`, où elles filtrent les éléments renvoyés en fonction de critères que vous définissez. Pour utiliser des expressions avec DynamoDB Mapper, ajoutez le composant d'expression dans la demande d'opération. 

L'extrait suivant montre un exemple d'expression de filtre utilisée dans une `scan` opération. Il utilise un argument lambda pour décrire les critères de filtre qui limitent les éléments à renvoyer à ceux dont la valeur d'`year`attribut est 2001 :

```
val table = // A table instance.

table.scanPaginated {
    filter {
        attr("year") eq 2001
    }
}
```

L'exemple suivant montre une `query` opération qui prend en charge les expressions à deux endroits : le filtrage par clé de tri et le filtrage non par clé :

```
table.queryPaginated {
    keyCondition = KeyFilter(partitionKey = 1000) { sortKey startsWith "M" }
    filter {
        attr("year") eq 2001
    }
}
```

Le code précédent filtre les résultats selon ceux qui répondent aux trois critères :
+ La valeur de l'attribut de clé de partition est 1000 *-AND-*
+ La valeur de l'attribut clé de tri commence par la lettre *M* *-AND-*
+ la valeur de l'attribut de l'année est 2001

## Composants DSL
<a name="ddb-mapper-expressions-dsl"></a>

La syntaxe DSL expose plusieurs types de composants, décrits ci-dessous, que vous utilisez pour créer des expressions.

### Attributes
<a name="ddb-mapper-expressions-dsl-attrs"></a>

La plupart des conditions font référence à des attributs, qui sont identifiés par leur clé ou leur chemin de document. Avec le DSK, vous créez toutes les références d'attributs à l'aide de la `attr` fonction et vous pouvez éventuellement apporter des modifications supplémentaires. 

Le code suivant montre une série d'exemples de références d'attributs allant du plus simple au plus complexe, tels que le déréférencement de listes par index et le déréférencement de cartes par clé :

```
attr("foo")           // Refers to the value of top-level attribute `foo`.

attr("foo")[3]        // Refers to the value at index 3 in the list value of
                      // attribute `foo`.

attr("foo")[3]["bar"] // Refers to the value of key `bar` in the map value at
                      // index 3 of the list value of attribute `foo`.
```

### Égalités et inégalités
<a name="ddb-mapper-expressions-dsl-eq-and-ineq"></a>

Vous pouvez comparer les valeurs d'attribut d'une expression par égalités et inégalités. Vous pouvez comparer les valeurs d'attribut à des valeurs littérales ou à d'autres valeurs d'attribut. Les fonctions que vous utilisez pour définir les conditions sont les suivantes :
+ `eq`: est égal à (équivalent à`==`)
+ `neq`: n'est pas égal à (équivalent à`!=`)
+ `gt`: est supérieur à (équivalent à`>`)
+ `gte`: est supérieur ou égal à (équivalent à`>=`)
+ `lt`: est inférieur à (équivalent à`<`)
+ `lte`: est inférieur ou égal à (équivalent à`<=`)

Vous combinez la fonction de comparaison avec des arguments en utilisant la notation infixe, comme indiqué dans les exemples suivants :

```
attr("foo") eq 42           // Uses a literal. Specifies that the attribute value `foo` must be
                            // equal to 42.

attr("bar") gte attr("baz") // Uses another attribute value. Specifies that the attribute 
                            // value `bar` must be greater than or equal to the
                            // attribute value of `baz`.
```

### Gammes et sets
<a name="ddb-mapper-expressions-dsl-ranges-sets"></a>

Outre les valeurs uniques, vous pouvez comparer les valeurs attributaires à plusieurs valeurs dans des plages ou des ensembles. Vous utilisez la `[isIn](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-in.html)` fonction infix pour effectuer la comparaison, comme indiqué dans les exemples suivants :

```
attr("foo") isIn 0..99  // Specifies that the attribute value `foo` must be
                        // in the range of `0` to `99` (inclusive).

attr("foo") isIn setOf( // Specifies that the attribute value `foo` must be
    "apple",            // one of `apple`, `banana`, or `cherry`.
    "banana",
    "cherry",
)
```

La `isIn` fonction fournit des surcharges pour les collections (par exemple`Set<String>`) et pour les limites que vous pouvez exprimer sous forme de Kotlin `[ClosedRange<T>](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-closed-range/)` (par exemple). `[IntRange](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/)` Pour les limites que vous ne pouvez pas exprimer sous forme de a `ClosedRange<T>` (comme des tableaux d'octets ou d'autres références d'attributs), vous pouvez utiliser la `[isBetween](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-between.html)` fonction :

```
val lowerBytes = byteArrayOf(0x48, 0x65, 0x6c)  // Specifies that the attribute value
val upperBytes = byteArrayOf(0x6c, 0x6f, 0x21)  // `foo` is between the values
attr("foo").isBetween(lowerBytes, upperBytes)   // `0x48656c` and `0x6c6f21`

attr("foo").isBetween(attr("bar"), attr("baz")) // Specifies that the attribute value
                                                // `foo` is between the values of
                                                // attributes `bar` and `baz`.
```

### Logique booléenne
<a name="ddb-mapper-expressions-dsl-boolean"></a>

Vous pouvez combiner des conditions individuelles ou les modifier à l'aide de la logique booléenne à l'aide des fonctions suivantes :
+ `and`: chaque condition doit être vraie (équivalent à` &&`)
+ `or`: au moins une condition doit être vraie (équivalent à`||`)
+ `not`: la condition donnée doit être fausse (équivalente à`!`)

Les exemples suivants illustrent chaque fonction :

```
and(                           // Both conditions must be met:
    attr("foo") eq "banana",   // * attribute value `foo` must equal `banana`
    attr("bar") isIn 0..99,    // * attribute value `bar` must be between
)                              //   0 and 99 (inclusive)

or(                            // At least one condition must be met:
    attr("foo") eq "cherry",   // * attribute value `foo` must equal `cherry`
    attr("bar") isIn 100..199, // * attribute value `bar` must be between
)                              //   100 and 199 (inclusive)

not(                           // The attribute value `foo` must *not* be
    attr("baz") isIn setOf(    // one of `apple`, `banana`, or `cherry`.
        "apple",               // Stated another way, the attribute value
        "banana",              // must be *anything except* `apple`, `banana`,
        "cherry",              // or `cherry`--including potentially a
    ),                         // non-string value or no value at all.
)
```

Vous pouvez également combiner des conditions booléennes par des fonctions booléennes pour créer une logique imbriquée, comme indiqué dans l'expression suivante :

```
or(
    and(
        attr("foo") eq 123,
        attr("bar") eq "abc",
    ),
    and(
        attr("foo") eq 234,
        attr("bar") eq "bcd",
    ),
)
```

L'expression précédente filtre les résultats en fonction de ceux qui répondent à l'une des conditions suivantes : 
+  Ces deux conditions sont vraies :
  + `foo`la valeur de l'attribut est 123 *-AND-*
  + `bar`la valeur de l'attribut est « abc » 
+ Ces deux conditions sont vraies :
  + `foo`la valeur de l'attribut est 234 *-AND-*
  + `bar`la valeur de l'attribut est « bcd » 

Cela équivaut à l'expression booléenne Kotlin suivante :

```
(foo == 123 && bar == "abc") || (foo == 234 && bar == "bcd")
```

### Fonctions et propriétés
<a name="ddb-mapper-expressions-dsl-functions"></a>

Les fonctions et propriétés suivantes fournissent des fonctionnalités d'expression supplémentaires :
+ `[contains](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/contains.html)`: vérifie si une valeur d' string/list attribut contient une valeur donnée
+ `[exists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/exists.html)`: vérifie si un attribut est défini et contient une valeur quelconque (y compris`null`)
+ `[notExists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/not-exists.html)`: vérifie si un attribut n'est pas défini
+ `[isOfType](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-of-type.html)`: vérifie si la valeur d'un attribut est d'un type donné, tel qu'une chaîne, un nombre, un booléen, etc.
+ `[size](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/size.html)`: obtient la taille d'un attribut, comme le nombre d'éléments d'une collection ou la longueur d'une chaîne
+ `[startsWith](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/starts-with.html)`: vérifie si la valeur d'un attribut de chaîne commence par une sous-chaîne donnée

Les exemples suivants montrent l'utilisation de fonctions et de propriétés supplémentaires que vous pouvez utiliser dans des expressions :

```
attr("foo") contains "apple" // Specifies that the attribute value `foo` must be
                             // a list that contains an `apple` element or a string
                             // which contains the substring `apple`.

attr("bar").exists()         // Specifies that the `bar` must exist and have a
                             // value (including potentially `null`).

attr("baz").size lt 100      // Specifies that the attribute value `baz` must have
                             // a size of less than 100.

attr("qux") isOfType AttributeType.String // Specifies that the attribute `qux`
                                          // must have a string value.
```

### Trier les filtres clés
<a name="ddb-mapper-expressions-dsl-sort-key"></a>

Les expressions de filtre sur les clés de tri (comme dans le `keyCondition` paramètre de l'`query`opération) n'utilisent pas de valeurs d'attributs nommées. Pour utiliser une clé de tri dans un filtre, vous devez utiliser le mot-clé `sortKey` dans toutes les comparaisons. Le `sortKey` mot clé est remplacé `attr("<sort key name>")` comme indiqué dans les exemples suivants :

```
sortKey startsWith "abc" // The sort key attribute value must begin with the
                         // substring `abc`.

sortKey isIn 0..99       // The sort key attribute value must be between 0
                         // and 99 (inclusive).
```

Vous ne pouvez pas combiner les filtres par clé de tri avec la logique booléenne et ils ne prennent en charge qu'un sous-ensemble des comparaisons décrites ci-dessus :
+ [Égalités et inégalités](#ddb-mapper-expressions-dsl-eq-and-ineq) : toutes les comparaisons sont fondées
+ [Plages et ensembles](#ddb-mapper-expressions-dsl-ranges-sets) : toutes les comparaisons sont prises en charge
+ [Logique booléenne](#ddb-mapper-expressions-dsl-boolean) : non prise en charge
+ [Fonctions et propriétés](#ddb-mapper-expressions-dsl-functions) : seules les fonctions `startsWith` sont prises en charge