本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用表達式
<a name="ddb-mapper-expressions"></a>

****  
**DynamoDB Mapper 是開發人員預覽版本。其功能不完整，可能會有所變更。**

某些 DynamoDB 操作接受您可以用來指定限制條件或條件[的表達](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html)式。DynamoDB Mapper 提供慣用的 Kotlin DSL 來建立表達式。DSL 為您的程式碼提供更大的結構和可讀性，也可讓您更輕鬆地撰寫表達式。

本節說明 DSL 語法並提供各種範例。

## 在 操作中使用表達式
<a name="ddb-mapper-expressions-basic-usage"></a>

您可以在 等操作中使用表達式`scan`，它們會根據您定義的條件篩選傳回的項目。若要搭配 DynamoDB Mapper 使用表達式，請在操作請求中新增表達式元件。

下列程式碼片段顯示 `scan`操作中使用的篩選條件表達式範例。它使用 lambda 引數來描述篩選條件，限制項目傳回至`year`屬性值為 2001 的項目：

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

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

下列範例顯示支援兩個位置表達式`query`的操作：排序索引鍵篩選和非索引鍵篩選：

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

先前的程式碼會篩選符合所有三個條件的結果：
+ 分割區索引鍵屬性值為 1000 *-AND-*
+ 排序索引鍵屬性值以字母 *M* *-AND-* 開頭
+ year 屬性值為 2001

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

DSL 語法會公開您用來建置表達式的多種元件類型，如下所述。

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

大多數條件參考屬性，由其金鑰或文件路徑識別。使用 DSK，您可以使用 `attr`函數建立所有屬性參考，並選擇性地進行其他修改。

下列程式碼顯示從簡單到複雜的範例屬性參考範圍，例如索引的清單取消參考和索引鍵的映射取消參考：

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

### 等式和不等式
<a name="ddb-mapper-expressions-dsl-eq-and-ineq"></a>

您可以依等式和不等式比較表達式中的屬性值。您可以將屬性值與常值或其他屬性值進行比較。您用來指定條件的函數包括：
+ `eq`： 等於 （相當於 `==`)
+ `neq`： 不等於 （相當於 `!=`)
+ `gt`： 大於 （相當於 `>`)
+ `gte`：大於或等於 （相當於 `>=`)
+ `lt`： 小於 （相當於 `<`)
+ `lte`：小於或等於 （相當於 `<=`)

您可以使用 infix 標記法將比較函數與引數結合，如下列範例所示：

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

### 範圍和集
<a name="ddb-mapper-expressions-dsl-ranges-sets"></a>

除了單一值之外，您還可以將屬性值與範圍或集合中的多個值進行比較。您可以使用 infix `[isIn](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-in.html)`函數進行比較，如下列範例所示：

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

`isIn` 函數為集合 （例如 `Set<String>`) 和您可以表達為 Kotlin 的邊界 `[ClosedRange<T>](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-closed-range/)`（例如 `[IntRange](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/-int-range/)`) 提供過載。對於您無法表達為 的邊界 `ClosedRange<T>`（例如位元組陣列或其他屬性參考），您可以使用 `[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`.
```

### 布林值邏輯
<a name="ddb-mapper-expressions-dsl-boolean"></a>

您可以使用下列函數結合個別條件或使用布林邏輯進行修改：
+ `and`：每個條件都必須是 true （等於` &&`)
+ `or`：至少一個條件必須為 true （相當於 `||`)
+ `not`：指定的條件必須是 false （相當於 `!`)

下列範例顯示每個 函數：

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

您可以依布林函數進一步合併布林值條件，以建立巢狀邏輯，如下列表達式所示：

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

先前的表達式會篩選符合下列任一條件的結果：
+  這兩個條件都是 true：
  + `foo` 屬性值為 123 *-AND-*
  + `bar` 屬性值為 "abc"
+ 這兩個條件都是 true：
  + `foo` 屬性值為 234 *-AND-*
  + `bar` 屬性值為 "bcd"

這相當於下列 Kotlin 布林表達式：

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

### 函數和屬性
<a name="ddb-mapper-expressions-dsl-functions"></a>

下列函數和屬性提供額外的表達式功能：
+ `[contains](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/contains.html)`：檢查字串/清單屬性值是否包含指定的值
+ `[exists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/exists.html)`：檢查是否已定義屬性並保留任何值 （包括 `null`)
+ `[notExists](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/not-exists.html)`：檢查屬性是否未定義
+ `[isOfType](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/is-of-type.html)`：檢查屬性值是否為指定類型，例如字串、數字、布林值等
+ `[size](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/size.html)`：取得屬性的大小，例如集合中的元素數量或字串的長度
+ `[startsWith](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.expressions/-filter/starts-with.html)`：檢查字串屬性值是否以指定的子字串開頭

下列範例顯示您可以在表達式中使用的其他函數和屬性的使用：

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

### 排序金鑰篩選條件
<a name="ddb-mapper-expressions-dsl-sort-key"></a>

排序索引鍵 （例如在`query`操作的 `keyCondition` 參數中） 上的篩選條件表達式不會使用具名屬性值。若要在篩選條件中使用排序索引鍵，您必須在所有比較`sortKey`中使用 關鍵字。`sortKey` 關鍵字會取代 `attr("<sort key name>")`，如下列範例所示：

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

您不能將排序索引鍵篩選條件與布林邏輯結合，它們僅支援上述比較的子集：
+ [相等性和不相等性](#ddb-mapper-expressions-dsl-eq-and-ineq)：支援的所有比較
+ [範圍和集](#ddb-mapper-expressions-dsl-ranges-sets)：支援的所有比較
+ [布林值邏輯](#ddb-mapper-expressions-dsl-boolean)：不支援
+ [函數和屬性](#ddb-mapper-expressions-dsl-functions)：僅`startsWith`支援