As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Use expressões
<a name="ddb-mapper-expressions"></a>

****  
**O DynamoDB Mapper é uma versão prévia para desenvolvedores. O recurso não está completo e está sujeito a alterações.**

Algumas operações do DynamoDB [aceitam](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html) expressões que você pode usar para especificar restrições ou condições. O DynamoDB Mapper fornece uma DSL Kotlin idiomática para criar expressões. A DSL traz maior estrutura e legibilidade ao seu código e também facilita a escrita de expressões. 

Esta seção descreve a sintaxe DSL e fornece vários exemplos. 

## Use expressões em operações
<a name="ddb-mapper-expressions-basic-usage"></a>

Você usa expressões em operações como`scan`, onde elas filtram os itens retornados com base nos critérios que você define. Para usar expressões com o DynamoDB Mapper, adicione o componente de expressão na solicitação de operação. 

O trecho a seguir mostra um exemplo de uma expressão de filtro usada em uma `scan` operação. Ele usa um argumento lambda para descrever os critérios de filtro que limitam os itens a serem retornados àqueles com um valor de `year` atributo de 2001:

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

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

O exemplo a seguir mostra uma `query` operação que oferece suporte a expressões em dois lugares: filtragem por chave de classificação e filtragem sem chave:

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

O código anterior filtra os resultados para aqueles que atendem aos três critérios:
+ O valor do atributo da chave de partição é 1000 *-AND-*
+ O valor do atributo chave de classificação começa com a letra *M* *-AND-*
+ o valor do atributo do ano é 2001

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

A sintaxe DSL expõe vários tipos de componentes, descritos abaixo, que você usa para criar expressões.

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

A maioria das condições faz referência a atributos, que são identificados por sua chave ou caminho do documento. Com o DSK, você cria todas as referências de atributos usando a `attr` função e, opcionalmente, faz modificações adicionais. 

O código a seguir mostra uma variedade de exemplos de referências de atributos, do simples ao complexo, como desreferenciamento de listas por índice e desreferenciamento de mapas por chave:

```
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`.
```

### Igualdades e desigualdades
<a name="ddb-mapper-expressions-dsl-eq-and-ineq"></a>

Você pode comparar valores de atributos em uma expressão por igualdades e desigualdades. Você pode comparar valores de atributos com valores literais ou outros valores de atributos. As funções que você usa para especificar as condições são:
+ `eq`: é igual a (equivalente a`==`)
+ `neq`: não é igual a (equivalente a`!=`)
+ `gt`: é maior que (equivalente a`>`)
+ `gte`: é maior ou igual a (equivalente a`>=`)
+ `lt`: é menor que (equivalente a`<`)
+ `lte`: é menor ou igual a (equivalente a`<=`)

Você combina a função de comparação com argumentos usando a notação infixa, conforme mostrado nos exemplos a seguir:

```
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`.
```

### Intervalos e conjuntos
<a name="ddb-mapper-expressions-dsl-ranges-sets"></a>

Além dos valores únicos, você pode comparar valores de atributos com vários valores em intervalos ou conjuntos. Você usa a `[isIn](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-in.html)` função infix para fazer a comparação, conforme mostrado nos exemplos a seguir:

```
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",
)
```

A `isIn` função fornece sobrecargas para coleções (como`Set<String>`) e para limites que você pode expressar como um Kotlin `[ClosedRange<T>](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-closed-range/)` (como). `[IntRange](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/)` Para limites que você não pode expressar como a `ClosedRange<T>` (como matrizes de bytes ou outras referências de atributos), você pode usar a função: `[isBetween](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-between.html)`

```
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`.
```

### Lógica booleana
<a name="ddb-mapper-expressions-dsl-boolean"></a>

Você pode combinar condições individuais ou alteradas usando a lógica booleana usando as seguintes funções:
+ `and`: toda condição deve ser verdadeira (equivalente a` &&`)
+ `or`: pelo menos uma condição deve ser verdadeira (equivalente a`||`)
+ `not`: a condição dada deve ser falsa (equivalente a`!`)

Os exemplos a seguir mostram cada função:

```
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.
)
```

Você também pode combinar condições booleanas por meio de funções booleanas para criar uma lógica aninhada, conforme mostrado na expressão a seguir:

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

A expressão anterior filtra os resultados para aqueles que atendem a uma dessas condições: 
+  Ambas as condições são verdadeiras:
  + `foo`o valor do atributo é 123 *-AND-*
  + `bar`o valor do atributo é “abc” 
+ Ambas as condições são verdadeiras:
  + `foo`o valor do atributo é 234 *-AND-*
  + `bar`o valor do atributo é “bcd” 

Isso é equivalente à seguinte expressão booleana Kotlin:

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

### Funções e propriedades
<a name="ddb-mapper-expressions-dsl-functions"></a>

As funções e propriedades a seguir fornecem recursos adicionais de expressão:
+ `[contains](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/contains.html)`: verifica se um valor de string/list atributo contém um determinado valor
+ `[exists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/exists.html)`: verifica se um atributo está definido e contém algum valor (incluindo`null`)
+ `[notExists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/not-exists.html)`: verifica se um atributo é indefinido
+ `[isOfType](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-of-type.html)`: verifica se um valor de atributo é de um determinado tipo, como string, número, booleano e assim por diante
+ `[size](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/size.html)`: obtém o tamanho de um atributo, como o número de elementos em uma coleção ou o comprimento de uma string
+ `[startsWith](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/starts-with.html)`: verifica se o valor de um atributo de string começa com uma determinada substring

Os exemplos a seguir mostram o uso de funções e propriedades adicionais que você pode usar em expressões:

```
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.
```

### Filtros de chave de classificação
<a name="ddb-mapper-expressions-dsl-sort-key"></a>

As expressões de filtro nas chaves de classificação (como no `keyCondition` parâmetro da `query` operação) não usam valores de atributos nomeados. Para usar uma chave de classificação em um filtro, você deve usar a palavra-chave `sortKey` em todas as comparações. A `sortKey` palavra-chave substitui `attr("<sort key name>")` conforme mostrado nos exemplos a seguir:

```
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).
```

Você não pode combinar filtros de chave de classificação com a lógica booleana e eles oferecem suporte apenas a um subconjunto das comparações descritas acima:
+ [Igualdades e desigualdades](#ddb-mapper-expressions-dsl-eq-and-ineq): todas as comparações são suportadas
+ [Intervalos e conjuntos](#ddb-mapper-expressions-dsl-ranges-sets): todas as comparações são suportadas
+ [Lógica booleana](#ddb-mapper-expressions-dsl-boolean): não suportada
+ [Funções e propriedades](#ddb-mapper-expressions-dsl-functions): somente `startsWith` é suportado