Vector VRL 迭代支持深度解析map_keys、map_values 与 for_each 闭包设计、函数签名与实战场景【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vectorVRLVector Remap Language自推出后长期保持核心语法稳定直到 Vector 0.22.0PR #12317才正式补上集合映射这块拼图。本文基于仓库中的发布公告与 RFC 8381 完整设计文档系统讲解 VRL 的闭包closure语法、三个内置迭代函数map_keys、map_values、for_each的签名与递归行为以及为什么故意不提供通用map和无限循环的设计取舍帮助你在动态字段重映射、键名规范化、批量统计等场景中写出既安全又高效的 VRL 程序。一、为什么 VRL 需要迭代支持VRL 的定位是把事件从当前状态重映射remap到期望状态核心操作是修改已有字段或新增字段。发布公告见 2022-05-18-vrl-iteration-support.md指出的语言缺口是事件里可能包含编译期无法预知的动态字段例如想把对象里所有键统一大写map_keys想把所有空字符串值置为nullmap_values想统计某个数组中各元素出现的次数for_each手写累加。没有迭代能力时这类字段名不确定的转换只能写死字段列表或回退到 Lua 运行时 transform。RFC 8381见 rfcs/2021-08-29-8381-vrf-iteration-support.md 中的 Scope/Pain 章节把需求收敛为能遍历对象和数组、为遍历提供必要的语言构件、并给出一组覆盖既有社区 use-case 的枚举函数。同时明确划出范围外内容reduce/filter等其他特化迭代形式、对象与数组之外的类型遍历、break/return控制流、以及无界迭代loop。这一克制的迭代边界正是后文设计取舍的出发点。二、完整走查官方示例一次看懂闭包语法发布公告用一个 JSON 事件演示了三类任务。输入{ foo: true, bar: { bar: }, baz: , qux: [a, b, a, c] }目标是1对象内所有键大写2所有空字符串值改为null3统计qux数组元素频次。完整 VRL 程序如下原样继承自发布公告# 1. Upcase all keys in the object. . map_keys(., recursive: true) - |key| { upcase(key) } # 2. Change all empty string values to null. . map_values(., recursive: true) - |value| { if value { null } else { value } } # 3. Count the frequency of elements in the .qux array. .qux_tally {} for_each(.qux) - |_index, value| { tally int(get!(.qux_tally, [value])) ?? 0 .qux_tally set!(.qux_tally, [value], tally 1) }运行结果{ FOO: true, BAR: { BAR: null }, BAZ: null, QUX: [a, b, a, c], qux_tally: { a: 2, b: 1, c: 1 } }几个语法要点值得注意闭包绑定在函数调用上- |参数| { 语句 }这段闭包不是独立变量不能赋值传递。这直接排除了尾调用递归从而杜绝看似合法、实际永不结束的程序RFC 在 User Experience 章节明确说明此意图。for_each不修改被遍历集合它的闭包返回什么都会被丢弃函数本身恒返回null。示例中真正的累加是通过对外部变量.qux_tally的set!完成的——这是 RFC 所称的trap door逃生舱用法先初始化空集合再在迭代中填充。递归由参数显式开启recursive: true才会深入嵌套对象与数组。三、三个迭代函数的签名与行为细节RFC 8381 给出了每个函数的精确签名见 rfcs/2021-08-29-8381-vrl-iteration-support.md 的 Functions 章节map_keys重命名对象键map_keys(value: object, recursive: bool) - |string| { string }只接受object闭包接收键名string并返回新键名。recursive: true时会先返回即将被递归进入的集合自身的键再处理其内部元素数组也会被递归穿透使得对象里套数组里再套对象的深层键也能被统一映射。典型场景RFC Use Cases 原例# 把键中的点替换为下划线适配 Elasticsearch 等系统 . map_keys(., recursive: true) - |key| { replace(key, ., _) } # 给所有键加前缀 . map_keys(., recursive: true) - |key| { my_ key }map_values映射对象值或数组元素map_values(value: object|array, recursive: bool) - |any| { any }与map_keys对称但操作的是值且同时支持对象和数组闭包参数与返回值类型均为any可把值改成任意其他类型如示例中的空字符串 →null。RFC 给出的典型用例包括# 数组中每个对象内删除 ttl 字段 . {answers:[{class:IN,ttl:264},{class:IN,ttl:264}],other:data} .answers map_values(.answers) - |value| { del(value.ttl); value } # 给数组中的每个对象注入外部字段 . { foo: bar, items: [{}, {}] } .items map_values(.items) - |value| { value.foo .foo; value } # 批量解析 CloudTrail 记录的时间戳 . map_values(.) - |value| { value.timestamp parse_timestamp(value.eventTime, %Y-%m-%dT%H:%M:%SZ) ?? now() value }for_each通用遍历逃生舱for_each(value: object|array, recursive: bool) - |string OR integer, any| { any }它是通用性最强的迭代函数对对象遍历时闭包收到|key, value|两个参数对数组遍历时收到|index, value|下标为整数。它不修改传入集合、恒返回null价值在于允许你在闭包内手动编写映射、过滤、归约、计数逻辑。RFC Use Cases 中若干一函数不够用的场景都靠它解决# 把对象解压缩成两个平行数组 keys [] values [] for_each(.) - |key, value| { keys push(keys, key) values push(values, value) } # 用一组 Grok 模式逐个尝试直到某一个匹配 matched false for_each(patterns) - |_index, pattern| { if !matched (parsed, err parse_grok(.message, pattern); err null) { matched true . | parsed } } # 把 [{key, value}, ...] 数组压缩回一个对象 data [{ key: name, value: value }, { key: key, value: otherValue }] for_each(data) - |_index, value| { . set(., [value.key], value.value) }为什么没有通用的 map 函数RFC 专设一节 why nomapfunction exists 解释map在处理递归时语义复杂且对象与数组两种遍历目标要求闭包签名不同必须在编译期确定遍历目标的确切类型。既然当时社区所有已知 use-case 都能被上述三函数覆盖团队选择推迟map的设计直到真实需求出现。发布公告同样强调这三个函数只是起点标准库中已有更多特化迭代函数未来还会按是否契合可观测数据重映射这一语言目的的标准持续增补。四、设计哲学把安全放进语法层发布公告的 Design Details 章节总结了选择普通函数调用 新闭包语法而非for语句的三条理由可扩展性以后可以在标准库中继续添加更特化的迭代函数而不动语言核心防事故迭代是性能与可靠性 bug尤其无限循环的常见来源闭包绑定函数调用、无尾递归、无loop、无break/return从语言层面封死了程序合法但永不返回的可能——每次迭代都必然跑完RFC 的 Alternatives 章节也对比并否决了 for-loop 方案理由是它会引入无限循环与提前退出控制流灵活性刚好够用对可观测数据重映射来说三个特化函数 通用for_each足以覆盖需求无需引入过度复杂的专用迭代语法。配套的递归策略是VRL 不允许自定义函数、也不支持尾调用因此用户无法用语法直接写出直接/间接递归但多级别递归在可观测数据中确有需求所以递归能力被封装进函数实现内部以可选的recursive: bool参数显式开启。这是一个能力内聚于标准库、语法保持扁平的典型工程取舍。RFC 的 Future Improvements 章节则列出了尚未实现的方向迭代控制流break/return类语义、更多特化函数any、all等——Use Cases 中已用假想的any(array) - |...|展示了它们的预期形态、Schema 支持、管道算子支持、动态字段赋值支持。五、在本仓库中的落点VRL 作为外部 crate 的集成方式从当前仓库源码结构看迭代函数本身的实现并不在本仓库内而是由官方独立的 VRL 语言 crate 提供根 Cargo.toml 中以 git 依赖方式引入vrl { git https://github.com/vectordotdev/vrl.git, branch main, default-features false, features [arbitrary, cli, test, test_framework, stdlib-base] }本仓库的lib/vector-vrl/目录是围绕该 crate 的适配层lib/vector-vrl/functions/ 中仅存放少量本地专属函数如set_secret、remove_secret、set_semantic_meaning、get_secret而map_keys/map_values/for_each等枚举函数属于vrlcrate 的标准库stdlib-basefeature随remaptransform 编译进最终二进制。发布公告中提到的测试脚手架RFC 8381 的回归用例集同样位于该外部 crate 的tests/tests/rfcs/8381目录下不在本仓库内——这意味着若要在上游验证迭代函数的边界行为需要到 vrl 仓库中查阅。六、对使用者的实操建议键名规范化统一大小写、去前缀、点转下划线、加命名空间前缀一律优先map_keys(., recursive: true)一行完成深层递归值批量清洗/类型转换空串转 null、批量parse_timestamp、把子对象encode_json优先map_values(., recursive: true)需要看得到但改不了的遍历计数、探测是否存在某值、构造平行数组、逐条尝试匹配规则用for_each 外部初始化集合注意它恒返回null结果必须写到闭包外的字段上想写break/无限循环/自定义递归函数当前语法不支持也是刻意不支持的——把这类逻辑改写成集合上的多次函数调用或升级到 Lua transform 之外再评估需要any/all/filter/reduce这类函数时本仓库公告明确标准库仍在按需求增补特化函数可以先用for_each手工实现等价逻辑作为过渡。迭代支持落地后此前必须依赖 Lua 运行时的动态字段重映射场景都可以留在 VRL 内完成并获得 VRL 提供的性能与运行时正确性保证——这正是该功能在 Vector 0.22.0 中被定位为补齐最后一块拼图的原因。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vector VRL 迭代支持深度解析map_keys、map_values 与 for_each 闭包设计、函数签名与实战场景【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vectorVRLVector Remap Language自推出后长期保持核心语法稳定直到 Vector 0.22.0PR #12317才正式补上集合映射这块拼图。本文基于仓库中的发布公告与 RFC 8381 完整设计文档系统讲解 VRL 的闭包closure语法、三个内置迭代函数map_keys、map_values、for_each的签名与递归行为以及为什么故意不提供通用map和无限循环的设计取舍帮助你在动态字段重映射、键名规范化、批量统计等场景中写出既安全又高效的 VRL 程序。一、为什么 VRL 需要迭代支持VRL 的定位是把事件从当前状态重映射remap到期望状态核心操作是修改已有字段或新增字段。发布公告见 2022-05-18-vrl-iteration-support.md指出的语言缺口是事件里可能包含编译期无法预知的动态字段例如想把对象里所有键统一大写map_keys想把所有空字符串值置为nullmap_values想统计某个数组中各元素出现的次数for_each手写累加。没有迭代能力时这类字段名不确定的转换只能写死字段列表或回退到 Lua 运行时 transform。RFC 8381见 rfcs/2021-08-29-8381-vrf-iteration-support.md 中的 Scope/Pain 章节把需求收敛为能遍历对象和数组、为遍历提供必要的语言构件、并给出一组覆盖既有社区 use-case 的枚举函数。同时明确划出范围外内容reduce/filter等其他特化迭代形式、对象与数组之外的类型遍历、break/return控制流、以及无界迭代loop。这一克制的迭代边界正是后文设计取舍的出发点。二、完整走查官方示例一次看懂闭包语法发布公告用一个 JSON 事件演示了三类任务。输入{ foo: true, bar: { bar: }, baz: , qux: [a, b, a, c] }目标是1对象内所有键大写2所有空字符串值改为null3统计qux数组元素频次。完整 VRL 程序如下原样继承自发布公告# 1. Upcase all keys in the object. . map_keys(., recursive: true) - |key| { upcase(key) } # 2. Change all empty string values to null. . map_values(., recursive: true) - |value| { if value { null } else { value } } # 3. Count the frequency of elements in the .qux array. .qux_tally {} for_each(.qux) - |_index, value| { tally int(get!(.qux_tally, [value])) ?? 0 .qux_tally set!(.qux_tally, [value], tally 1) }运行结果{ FOO: true, BAR: { BAR: null }, BAZ: null, QUX: [a, b, a, c], qux_tally: { a: 2, b: 1, c: 1 } }几个语法要点值得注意闭包绑定在函数调用上- |参数| { 语句 }这段闭包不是独立变量不能赋值传递。这直接排除了尾调用递归从而杜绝看似合法、实际永不结束的程序RFC 在 User Experience 章节明确说明此意图。for_each不修改被遍历集合它的闭包返回什么都会被丢弃函数本身恒返回null。示例中真正的累加是通过对外部变量.qux_tally的set!完成的——这是 RFC 所称的trap door逃生舱用法先初始化空集合再在迭代中填充。递归由参数显式开启recursive: true才会深入嵌套对象与数组。三、三个迭代函数的签名与行为细节RFC 8381 给出了每个函数的精确签名见 rfcs/2021-08-29-8381-vrl-iteration-support.md 的 Functions 章节map_keys重命名对象键map_keys(value: object, recursive: bool) - |string| { string }只接受object闭包接收键名string并返回新键名。recursive: true时会先返回即将被递归进入的集合自身的键再处理其内部元素数组也会被递归穿透使得对象里套数组里再套对象的深层键也能被统一映射。典型场景RFC Use Cases 原例# 把键中的点替换为下划线适配 Elasticsearch 等系统 . map_keys(., recursive: true) - |key| { replace(key, ., _) } # 给所有键加前缀 . map_keys(., recursive: true) - |key| { my_ key }map_values映射对象值或数组元素map_values(value: object|array, recursive: bool) - |any| { any }与map_keys对称但操作的是值且同时支持对象和数组闭包参数与返回值类型均为any可把值改成任意其他类型如示例中的空字符串 →null。RFC 给出的典型用例包括# 数组中每个对象内删除 ttl 字段 . {answers:[{class:IN,ttl:264},{class:IN,ttl:264}],other:data} .answers map_values(.answers) - |value| { del(value.ttl); value } # 给数组中的每个对象注入外部字段 . { foo: bar, items: [{}, {}] } .items map_values(.items) - |value| { value.foo .foo; value } # 批量解析 CloudTrail 记录的时间戳 . map_values(.) - |value| { value.timestamp parse_timestamp(value.eventTime, %Y-%m-%dT%H:%M:%SZ) ?? now() value }for_each通用遍历逃生舱for_each(value: object|array, recursive: bool) - |string OR integer, any| { any }它是通用性最强的迭代函数对对象遍历时闭包收到|key, value|两个参数对数组遍历时收到|index, value|下标为整数。它不修改传入集合、恒返回null价值在于允许你在闭包内手动编写映射、过滤、归约、计数逻辑。RFC Use Cases 中若干一函数不够用的场景都靠它解决# 把对象解压缩成两个平行数组 keys [] values [] for_each(.) - |key, value| { keys push(keys, key) values push(values, value) } # 用一组 Grok 模式逐个尝试直到某一个匹配 matched false for_each(patterns) - |_index, pattern| { if !matched (parsed, err parse_grok(.message, pattern); err null) { matched true . | parsed } } # 把 [{key, value}, ...] 数组压缩回一个对象 data [{ key: name, value: value }, { key: key, value: otherValue }] for_each(data) - |_index, value| { . set(., [value.key], value.value) }为什么没有通用的 map 函数RFC 专设一节 why nomapfunction exists 解释map在处理递归时语义复杂且对象与数组两种遍历目标要求闭包签名不同必须在编译期确定遍历目标的确切类型。既然当时社区所有已知 use-case 都能被上述三函数覆盖团队选择推迟map的设计直到真实需求出现。发布公告同样强调这三个函数只是起点标准库中已有更多特化迭代函数未来还会按是否契合可观测数据重映射这一语言目的的标准持续增补。四、设计哲学把安全放进语法层发布公告的 Design Details 章节总结了选择普通函数调用 新闭包语法而非for语句的三条理由可扩展性以后可以在标准库中继续添加更特化的迭代函数而不动语言核心防事故迭代是性能与可靠性 bug尤其无限循环的常见来源闭包绑定函数调用、无尾递归、无loop、无break/return从语言层面封死了程序合法但永不返回的可能——每次迭代都必然跑完RFC 的 Alternatives 章节也对比并否决了 for-loop 方案理由是它会引入无限循环与提前退出控制流灵活性刚好够用对可观测数据重映射来说三个特化函数 通用for_each足以覆盖需求无需引入过度复杂的专用迭代语法。配套的递归策略是VRL 不允许自定义函数、也不支持尾调用因此用户无法用语法直接写出直接/间接递归但多级别递归在可观测数据中确有需求所以递归能力被封装进函数实现内部以可选的recursive: bool参数显式开启。这是一个能力内聚于标准库、语法保持扁平的典型工程取舍。RFC 的 Future Improvements 章节则列出了尚未实现的方向迭代控制流break/return类语义、更多特化函数any、all等——Use Cases 中已用假想的any(array) - |...|展示了它们的预期形态、Schema 支持、管道算子支持、动态字段赋值支持。五、在本仓库中的落点VRL 作为外部 crate 的集成方式从当前仓库源码结构看迭代函数本身的实现并不在本仓库内而是由官方独立的 VRL 语言 crate 提供根 Cargo.toml 中以 git 依赖方式引入vrl { git https://github.com/vectordotdev/vrl.git, branch main, default-features false, features [arbitrary, cli, test, test_framework, stdlib-base] }本仓库的lib/vector-vrl/目录是围绕该 crate 的适配层lib/vector-vrl/functions/ 中仅存放少量本地专属函数如set_secret、remove_secret、set_semantic_meaning、get_secret而map_keys/map_values/for_each等枚举函数属于vrlcrate 的标准库stdlib-basefeature随remaptransform 编译进最终二进制。发布公告中提到的测试脚手架RFC 8381 的回归用例集同样位于该外部 crate 的tests/tests/rfcs/8381目录下不在本仓库内——这意味着若要在上游验证迭代函数的边界行为需要到 vrl 仓库中查阅。六、对使用者的实操建议键名规范化统一大小写、去前缀、点转下划线、加命名空间前缀一律优先map_keys(., recursive: true)一行完成深层递归值批量清洗/类型转换空串转 null、批量parse_timestamp、把子对象encode_json优先map_values(., recursive: true)需要看得到但改不了的遍历计数、探测是否存在某值、构造平行数组、逐条尝试匹配规则用for_each 外部初始化集合注意它恒返回null结果必须写到闭包外的字段上想写break/无限循环/自定义递归函数当前语法不支持也是刻意不支持的——把这类逻辑改写成集合上的多次函数调用或升级到 Lua transform 之外再评估需要any/all/filter/reduce这类函数时本仓库公告明确标准库仍在按需求增补特化函数可以先用for_each手工实现等价逻辑作为过渡。迭代支持落地后此前必须依赖 Lua 运行时的动态字段重映射场景都可以留在 VRL 内完成并获得 VRL 提供的性能与运行时正确性保证——这正是该功能在 Vector 0.22.0 中被定位为补齐最后一块拼图的原因。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
