ACAL Lynxus RecordPath 指南

当我们引用一个 Array 字段时，该字段的值可能是包含多个元素的数组，但我们可能只需要其中几个元素。例如，我们可能只想引用第一个元素；只有最后一个元素；或者可能是第一个、第二个、第三个和最后一个元素。我们可以通过使用方括号内元素的索引（索引从 0 开始）来引用特定元素。因此，让我们考虑上述 Record 的修改版本：

我们现在可以使用 RecordPath /addresses[0] 引用 addresses 数组中的第一个元素。我们可以使用 RecordPath /addresses[1] 访问第二个元素。但是，有时我们不知道数组中会有多少元素。因此我们可以使用负索引从数组末尾向前计数。例如，我们可以使用 /addresses[-1] 访问最后一个元素，或使用 /addresses[-2] 访问倒数第二个元素。如果我们想引用多个元素，可以使用逗号分隔的元素列表，如 /addresses[0, 1, 2, 3]。或者，要访问第 0 到第 8 个元素，我们可以使用 range 运算符（..），如 /addresses[0..8]。我们也可以混合使用这些方式，并使用语法 /addresses[0..-1] 引用所有元素，甚至 /addresses[0, 1, 4, 6..-1]。当然，并非此处引用的所有索引都会匹配上述 Record，因为 addresses 数组只有 2 个元素。不匹配的索引将被简单地跳过。

与 Array 字段类似，Map 字段可能由多个不同的值组成。RecordPath 为我们提供了根据其键选择一组值的能力。我们通过在方括号内使用带引号的字符串来实现这一点。作为示例，让我们重新审视上面的原始 Record：

不过，现在让我们假设与 Record 关联的 Schema 指示 address 字段不是 Record 而是一个 Map 字段。在这种情况下，如果我们尝试使用 RecordPath /details/address/zip 引用 zip，RecordPath 将不匹配，因为 address 字段不是 Record，因此没有名为 zip 的子 Record。相反，它是一个 Map 字段，键和值都是 String 类型。不幸的是，在查看 JSON 时，这看起来可能有点令人困惑，因为 JSON 并没有真正的类型系统。但是，当我们将 JSON 转换为 Record 对象以操作数据时，这种区别可能很重要。

在上面描述的情况下，我们仍然可以使用 RecordPath 访问 zip 字段。不过，我们必须使用稍微不同的语法：/details/address['zip']。这告诉 RecordPath 我们想在最高层访问 details 字段。然后我们想访问其 address 字段。由于 address 字段是 Map 字段，我们可以使用方括号来指示我们想指定一个 Map 键，然后可以在引号中指定键。

此外，我们可以使用逗号分隔的列表选择多个 Map 键：/details/address['city', 'state', 'zip']。如果愿意，我们还可以使用通配符运算符（*）选择所有字段：/details/address[*]。Map 字段不包含任何类型的排序，因此不可能通过数字索引引用键。

到目前为止，我们已经讨论了两种不同类型的过滤器。它们中的每一种都允许我们从允许多个值的字段中选择一个或多个元素。然而，通常我们需要应用一个过滤器来限制选择哪些 Record 字段。例如，如果我们想选择 zip 字段但仅限于 state 不是 New York 的 address 字段呢？上述示例没有提供任何方法来做到这一点。

RecordPath 为用户提供了指定谓词的能力。谓词简单来说就是可以应用于字段以确定该字段是否应包含在结果中的过滤器。与其他过滤器一样，谓词在方括号内指定。谓词的语法为 <相对 RecordPath> <运算符> <表达式>。相对 RecordPath 的工作方式与任何其他 RecordPath 一样，但必须以 .（引用当前字段）或 ..（引用当前字段的父级）开头，而不是斜杠，并引用相对于谓词所应用字段的字段。运算符 必须是以下之一：

表达式 可以是字面值，如 50 或 Hello，也可以是另一个 RecordPath。

为了说明这一点，让我们以下面的 Record 为例：

现在我们可以使用谓词仅选择 state 不是 New York 的字段。例如，我们可以使用 /[./state != 'NY']。这将选择任何具有 state 字段的 Record 字段，前提是该 state 的值不是 "NY"。请注意，details Record 不会被返回，因为它没有名为 state 的字段。因此在此示例中，RecordPath 将仅选择 homeAddress 字段。一旦我们选择了该字段，就可以继续我们的 RecordPath。正如我们在上面所说的，我们可以选择 zip 字段：/[./state != 'NY']/zip。此 RecordPath 将仅从 homeAddress 字段中选择 zip 字段。

我们还可以将一个字段中的值与另一个字段中的值进行比较。例如，我们可以通过使用 RecordPath /*[./state = /details/preferredState] 选择位于用户偏好 state 的地址。在此示例中，此 RecordPath 将检索 workAddress 字段，因为其 state 字段与 preferredState 字段的值匹配。

此外，我们可以通过使用父级运算符（..）编写引用 state 为 "NJ" 的任何记录的 "city" 字段的 RecordPath：/*/city[../state = 'NJ']。

substring 函数返回字符串值的一部分。该函数需要 3 个参数：要截取一部分的值、从 0 开始的起始索引（包含）和从 0 开始的结束索引（不包含）。起始索引和结束索引可以是 0 表示字符串的第一个字符，正整数表示字符串中的第 n 个索引，或负整数。如果值是负整数，比如 -n，则表示从末尾数第 n 个字符。-1 表示字符串中的最后一个字符。因此，例如 substring( 'hello world', 0, -1 ) 表示取字符串 hello，并返回字符 0 到最后一个字符，所以返回值将是 hello world。

返回字符串值中在某个其他值首次出现之后的部分。

返回字符串值中在某个其他值最后一次出现之后的部分。

返回字符串值中在某个其他值首次出现之前的部分。

返回字符串值中在某个其他值最后一次出现之前的部分。

将一个字符串的所有出现替换为另一个字符串。

对字符串值的内容评估正则表达式，并将任何匹配替换为另一个值。此函数需要 3 个参数：要运行正则表达式的字符串、要运行的正则表达式和替换值。替换值可以选择性地使用反向引用，如 $1 和 ${named_group}。

当第一个参数非空时返回其值。如果第一个参数评估为 null，该函数返回替换值。

将所有参数连接在一起。

使用分隔符将多个值连接在一起。

允许在将根上下文锚定到子记录的同时评估 RecordPath。

此外，这可以与数组结合使用。例如，如果我们有以下记录：

我们可以评估以下 RecordPath：

通常，当给出到 Record 中特定字段的路径时，返回的是该字段的值。然而，有时获取字段名称而不是值可能很有用。为此，我们可以使用 fieldName 函数。

在上面的示例中，第一个 RecordPath 返回两个单独的字段名："workAddress" 和 "homeAddress"。第二个 RecordPath 则返回 "city" 字段的值，并使用 fieldName 函数作为谓词。第二个 RecordPath 找到一个 "city" 字段，其父级名称不以 "work" 开头。这意味着它将返回父级为 "homeAddress" 的 "city" 字段的值，但不会返回父级为 "workAddress" 的 "city" 字段的值。

将字符串转换为日期。例如，给定如下模式：

以及如下记录：

以下记录路径将把 eventDate 字段解析为日期：

toDate( /eventDate, "yyyy-MM-dd’T’HH:mm:ss’Z'")

toDate( /eventDate, "yyyy-MM-dd’T’HH:mm:ss’Z'", "GMT+8:00")

将值转换为字符串，如果输入类型为 "bytes" 则使用给定的字符集。例如，给定如下模式：

以及如下记录：

以下记录路径将把 bytes 字段解析为字符串：

toString( /bytes, "UTF-8")

使用给定的字符集将字符串转换为 byte[]。例如，给定如下模式：

以及如下记录：

以下记录路径将使用 UTF-16 编码将字符串字段转换为字节数组：

toBytes( /s, "UTF-16")

从给定参数中返回第一个非空值。例如，给定如下记录：

以下记录路径将返回 "John Doe"：

coalesce(/id, /name)

给定记录：

相同的记录路径将返回 "1234"。

给定记录：

记录路径将返回 null。

给定记录：

记录路径将返回字符串 "null"。请注意这里非常重要的区别，即 id 字段没有 null 值，而是该字段的值是字面字符串 "null"。

给定记录：

记录路径将返回 null。由于 id 字段不存在，它被视为 null 值。

给定记录：

记录路径将返回 "1234"。但是，记录路径 coalesce(/name, /id) 将返回 "John Doe"，因为给定的两个字段都非空，所以 coalesce 函数返回其参数中引用的第一个值，而不是 Record 本身中遇到的第一个值。

将日期转换为给定格式的字符串，可选时区。当不提供第二个参数时，该函数默认使用系统本地时区。

此函数的第一个参数必须是 Date 或 Number，第二个参数必须是遵循 Java DateTimeFormatter 的格式字符串，第三个参数（可选）必须是格式字符串，可以是缩写（如 "PST"）、全名（如 "America/Los_Angeles"）或自定义 ID（如 "GMT-8:00"）。

例如，给定如下模式：

以及如下记录：

以下记录路径表达式将把日期格式化为字符串：

如果字段声明为 String，则必须在格式化之前调用 toDate 函数。

例如，给定如下模式：

以及如下记录：

以下记录路径表达式将重新格式化日期字符串：

删除字符串开头和结尾的空格。

以及如下记录：

以下记录路径表达式将删除多余的空格：

将整个字符串转换为大写。

以及如下记录：

以下记录路径表达式将小写字母转换为大写：

将整个字符串转换为小写。

以及如下记录：

以下记录路径表达式将大写字母转换为小写：

使用 UTF-8 字符集将字符串或 byte[] 进行 Base64 编码。例如，给定如下模式：

以及如下记录：

以下记录路径表达式将使用 Base64 编码字符串：

解码 Base64 编码的字符串或 byte[]。例如，给定如下模式：

以及如下记录：

以下记录路径表达式将使用 Base64 解码字符串：

使用 UTF-8 字符集将 Record、Array 或简单字段（如 String）转为 JSON 字符串。例如，给定如下模式：

以及如下记录：

以下记录路径表达式将把记录转换为转义的 JSON 字符串：

使用 UTF-8 字符集将 JSON 字符串化的元素转换为 Record、Array 或简单字段（如 String）。

此函数最多接受三个参数：

注意：RecordSetWriter 无法序列化 Map，因此如果不转换为 Record，字段可能会被省略。例如，在 UpdateRecord 中使用 unescapeJson 替换 Record 的根（"/"）而不使用 Record 转换，将导致空输出，因为 RecordSetWriter 无法将结果 Map 内容匹配到 RecordSchema。

例如，给定如下模式：

以及如下记录：

以下记录路径表达式将用取消转义的 JSON 字段填充记录：

给定如下记录：

以下记录路径表达式将返回：

给定如下记录：

以下记录路径表达式将返回：

给定如下记录：

以下记录路径表达式将返回：

注意，如果要取消转义的 JSON 要设置在 Record 的字段中，则必须预先定义目标模式 - 推断模式目前不会自动执行此操作。

使用哈希算法转换字符串。例如，给定如下模式：

以及如下记录：

以下记录路径表达式将使用以下算法之一对字符串进行哈希：[SHA-384, SHA-224, SHA-256, MD2, SHA, SHA-512, MD5]。

在输入字符串前面添加字符，直到达到所需长度。

以及如下记录：

以下记录路径表达式将在输入字符串前面添加 '@' 字符：

在输入字符串后面添加字符，直到达到所需长度。

以及如下记录：

以下记录路径表达式将在输入字符串后面添加 '@' 字符：

将 UUID v5 插入目标字段。

此函数有两种使用方式：使用或不使用命名空间。给定以下模式：

以及如下记录：

此函数有两种使用方式：

uuid5(/input)

uuid5(/input, /id_ns)

第一个选项将生成一个简单的 UUID v5，在生成过程中不使用命名空间。第二个将获取所提供记录路径的值并将其用作命名空间。

请注意，命名空间必须始终是有效的 UUID 字符串。空字符串、其他数据类型等将导致错误。这是设计使然，因为 UUID v5 最常见的用例是跨数据集唯一标识记录。

返回元素数量。这通常与数组结合使用。例如，如果我们有以下记录：

我们可以使用 count 函数确定 elements 的数量。使用：

将得到值 2。我们还可以将其用作过滤器，如：

这将返回值为 1234 的 id 元素。

使用给定参数创建字符串的 Map。例如，如果我们有以下记录：

我们可以使用 UpdateRecord 处理器配合

这将给我们类似：

此函数需要偶数个参数，记录路径必须表示简单字段值。

使用给定参数创建嵌套记录。例如，如果我们有以下记录：

我们可以使用 UpdateRecord 处理器配合

这将给我们类似：

此函数需要偶数个参数。每对参数类似于新记录中的一个字段。每个奇数参数（每对的第一个）用作字段名并强制转换为字符串值。每个偶数参数（每对的第二个）用作字段值。

从多个值创建数组。

我们可以使用 arrayOf 函数结合 unescapeJson 函数向 elements 数组追加一个新元素。给定此示例输入，arrayOf(/elements[*], unescapeJson('{"name":"phone","color":"blue"}')) 的 RecordPath 将返回以下数组：

我们还可以使用 arrayOf 函数向数组追加多个元素。给定输入记录：

arrayOf(/friends[*], 'Joe', 'Jim', 'Jeremy') 的 RecordPath 将返回以下数组：

我们还可以简单地从任意值创建数组，如 arrayOf('good-bye', 'adios', 'au revoir') 将返回以下数组：

如果字符串值包含所提供的子字符串则返回 true，否则返回 false。

对字符串值的内容评估正则表达式，如果字符串值包含匹配正则表达式的子字符串则返回 true，否则返回 false。此函数需要 2 个参数：要运行正则表达式的字符串和要运行的正则表达式。

对字符串值的内容评估正则表达式，如果正则表达式完全匹配字符串值则返回 true，否则返回 false。此函数需要 2 个参数：要运行正则表达式的字符串和要运行的正则表达式。

如果字符串值以所提供的子字符串开头则返回 true，否则返回 false。

如果字符串值以所提供的子字符串结尾则返回 true，否则返回 false。

反转传递给 not 函数的函数或表达式的值。

如果所提供的值为 null 或空字符串则返回 true。

如果所提供的值为 null、空字符串或仅由空白字符（空格、制表符、回车符和换行符）组成的字符串则返回 true。

将字符串或日期值强制转换为数字。如果参数已经是数字，则原样返回，保留原始类型。

计算两个数字的和。

计算两个数字的差。

计算两个数字的积。

计算两个数字的商。