使用表达式 - 适用于 Kotlin 的 AWS SDK

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

使用表达式

DynamoDB Mapper 是开发者预览版。它功能不完整,可能会发生变化。

某些 DynamoDB 操作接受可用于指定约束或条件的表达式。DynamoDB Mapper 提供了一种惯用的 Kotlin DSL 来创建表达式。DSL 为您的代码带来了更好的结构和可读性,还可以更轻松地编写表达式。

本节介绍了 DSL 语法并提供了各种示例。

在操作中使用表达式

你可以在诸如这样的操作中使用表达式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-开头

  • 年份属性值为 2001

DSL 组件

DSL 语法公开了几种用于构建表达式的组件(如下所述)。

Attributes

大多数条件都引用属性,这些属性由其密钥或文档路径标识。使用 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`.

平等与不平等

可以按等式和不等式比较表达式中的属性值。您可以将属性值与文字值或其他属性值进行比较。用于指定条件的函数有:

  • eq: 等于(等于==

  • neq: 不等于(等于!=

  • gt: 大于(等于>

  • gte: 大于或等于(等于>=

  • lt: 小于(等于<

  • lte: 小于或等于(等于<=

您可以使用中缀表示法将比较函数与参数组合在一起,如以下示例所示:

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

范围和套装

除了单个值外,您还可以将属性值与范围或集合中的多个值进行比较。您可以使用中缀isIn函数进行比较,如以下示例所示:

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>(例如)提供重载。IntRange对于无法表示为 a 的边界ClosedRange<T>(例如字节数组或其他属性引用),可以使用以下isBetween函数:

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

布尔逻辑

您可以使用以下函数组合单个条件或使用布尔逻辑进行更改:

  • and: 每个条件都必须为真(等同于 &&

  • or: 至少有一个条件必须为真(等同于||

  • not: 给定条件必须为假(等同于!

以下示例显示了每个函数:

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

前面的表达式将结果筛选为满足以下任一条件的结果:

  • 这两个条件都成立:

    • foo属性值为 123 -AND-

    • bar属性值为 “abc”

  • 这两个条件都成立:

    • foo属性值为 234 -AND-

    • bar属性值为 “bcd”

这等同于以下 Kotlin 布尔表达式:

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

函数和属性

以下函数和属性提供了额外的表达式功能:

  • contains: 检查字符串/列表属性值是否包含给定值

  • exists: 检查属性是否已定义并包含任何值(包括null

  • notExists: 检查属性是否未定义

  • isOfType: 检查属性值是否为给定类型,例如字符串、数字、布尔值等

  • size: 获取属性的大小,例如集合中元素的数量或字符串的长度

  • startsWith: 检查字符串属性值是否以给定的子字符串开头

以下示例说明了可以在表达式中使用的其他函数和属性的用法:

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.

对关键筛选器进行排序

排序键上的筛选表达式(例如在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).

不能将排序键过滤器与布尔逻辑结合使用,它们仅支持上述比较的子集: