StarRocks 的 json_keys 函数从 JSON 对象中提取顶层键的完整指南【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本篇技术指南以 StarRocks 的json_keys函数为主题讲解如何从 JSON 对象中提取其顶层键并以 JSON 数组形式返回。你将掌握json_keys的完整语法、参数规则、返回值语义以及如何借助可选的path参数从嵌套 JSON 对象包括数组内嵌的对象中提取键并了解该函数在 StarRocks BE 端的真实实现路径与测试验证方式可直接用于日志解析、半结构化数据分析等实战场景。函数概述json_keys是 StarRocks 提供的 JSON 查询与处理函数 之一用于获取 JSON 对象的键集合。功能定义json_keys返回 JSON 对象的顶层键以 JSON 数组的形式呈现如果指定了path参数则返回该路径所指向的 JSON 对象的顶层键。典型场景当你面对以 JSON 格式存储的半结构化数据如日志事件、用户画像、埋点数据时常常需要先看清某个对象里有哪些字段再决定后续如何抽取。json_keys正是完成这种字段清单探测的轻量工具可与json_query、arrow function、json_exists等函数组合使用完整函数清单见 JSON functions overview。语法json_keys(json_doc[, path])参数说明参数是否必填说明json_doc必填需要提取键的 JSON 文档必须是一个 JSON 对象path可选路径表达式用于定位 JSON 文档中某个对象。路径一般以$开头以.作为路径分隔符[]用作数组下标下标从 0 开始关于path参数的更多细节$表示 JSON 文档的根节点。.用于逐层下钻对象例如$.c表示取顶层键c所对应的值。[]用于定位数组中的元素下标从 0 开始例如$[2]表示取数组的第 3 个元素。StarRocks 的 JSON path 语法并不完全等同于 SQL/JSON 标准路径规范具体的路径语法约定可参考 JSON path expressions。返回值json_keys的返回值遵循以下规则成功时返回一个 JSON 数组数组元素为 JSON 对象的所有顶层键以字符串形式。空对象如果 JSON 对象为空{}返回空数组[]。非对象输入如果json_doc本身不是 JSON 对象例如是数组、数值或字符串返回NULL。路径失效如果指定的path不能定位到文档中的任何值或定位到的值不是 JSON 对象返回NULL。嵌套对象如果 JSON 文档是数组且数组中嵌套了 JSON 对象可以通过path参数定位到该对象并提取其键。示例详解以下示例完整展示了json_keys的各种行为。示例 1空 JSON 对象返回空数组select json_keys({}); ----------------- | json_keys({}) | ----------------- | [] | -----------------示例 2返回 JSON 对象的顶层键select json_keys({a: 1, b: 2, c: 3}); ---------------- | json_keys(1) | ---------------- |[a, b, c] | ----------------注意json_keys只返回顶层键不包含嵌套对象的内部键。例如对于{a: {d: 1}}返回的是[a]而不是[d]。示例 3通过 path 返回嵌套对象的键select json_keys({a: 1, b: 2, c: {d: 3, e: 4, f: 5}}, $.c); --------------------------------------------------------------------- | json_keys({a: 1, b: 2, c: {d: 3, e: 4, f: 5}}, $.c) | --------------------------------------------------------------------- | [d, e, f] | ---------------------------------------------------------------------示例 4path 不存在时返回 NULLselect json_keys({a: 1, b: 2, c: {d: 3, e: 4, f: 5}}, $.e); --------------------------------------------------------------------- | json_keys({a: 1, b: 2, c: {d: 3, e: 4, f: 5}}, $.e) | --------------------------------------------------------------------- | NULL | ---------------------------------------------------------------------示例 5JSON 文档不是对象时返回 NULLselect json_keys([1, 2, {a: 1, b: 2}]); --------------------------------------- | json_keys([1, 2, {a: 1, b: 2}]) | --------------------------------------- | NULL | ---------------------------------------示例 6数组内嵌对象通过 path 提取键select json_keys([0, 1, {a: 1, b: 2}], $[2]); ----------------------------------------------- | json_keys([0, 1, {a: 1, b: 2}], $[2]) | ----------------------------------------------- | [a, b] | -----------------------------------------------底层实现原理源码级解析在 StarRocks 的 BEBackend端json_keys的实现位于 be/src/exprs/json_functions.cpp。其入口函数JsonFunctions::json_keys会根据调用方式与数据形态分派到三条实现路径无 path 调用_json_keys_without_pathbe/src/exprs/json_functions.cpp直接遍历json_doc的根节点。若根节点不是对象!vslice.isObject()则追加NULL否则通过vpack::ObjectIterator遍历对象的键值对把每个键iter.key.copyString()追加进一个vpack::ArrayBuilder最终构造出一个 JSON 数组。有 path 调用 常规 JSON_full_json_keys_with_pathbe/src/exprs/json_functions.cpp先通过get_prepared_or_parse解析并缓存路径表达式再调用JsonPath::extract从文档中取出path定位到的切片slice。只有定位结果isObject()时才提取键否则追加NULL包括 path 不存在或指向非对象两种情况。有 path 调用 扁平 JSONflat JSON_flat_json_keys_with_pathbe/src/exprs/json_functions.cpp针对 StarRocks 的扁平 JSON 列存储做了优化先通过_extract_from_flat_json把扁平列还原成常规 JSON再按完整匹配full match/ 部分匹配partial match两种状态分别处理随后走与常规路径相同的键提取逻辑。由此可以推断返回值NULL的判定发生在切片层只要path解析失败、定位结果为空或定位到的不是对象统一返回NULL。键的提取使用底层 JSON 引擎velocypack的ObjectIterator键以字符串形式按文档顺序写入数组示例输出中键的顺序与输入 JSON 中书写的顺序一致ObjectIterator的遍历顺序取决于底层 JSON 实现。函数通过ColumnBuilderTYPE_JSON构建返回列因此每一行的结果都是一个独立的JSON类型值可以直接参与后续 JSON 函数链式运算。测试验证json_keys的行为在 BE 端单元测试中得到完整验证见 be/test/exprs/json_functions_test.cpp。测试通过参数化方式覆盖了以下典型用例输入 JSONpath期望结果{ k1: 1, k2: 2 }无[k1, k2]{ k1: v1 }无[k1]{ k1: {k2: 1} }无[k1]不递归嵌套键{ }无[]空对象返回空数组[]无NULL数组不是对象1无NULL数值不是对象hehe无NULL字符串不是对象{ k1: v1 }$.k1NULL定位到标量非对象{ k1: v1 }$.k3NULLpath 不存在{ k1: {k2: 1} }$.k1[k2]定位到嵌套对象这些用例与文档中的示例相互印证尤其是定位到标量也返回 NULL这一细节示例 4 的变体在使用path提取嵌套键时值得特别注意。此外扁平 JSON 场景下json_keys的路径行为在 be/test/exprs/flat_json_functions_test.cpp 中有对应测试覆盖。使用建议与边界条件仅适用于对象json_keys的输入与path定位目标都必须是 JSON 对象否则返回NULL。若数据源中同一列混合了对象与数组建议先用json_exists或条件表达式过滤再调用json_keys。只取顶层键该函数不递归。需要深层字段清单时可以逐层指定path如$.a、$.a.b分别调用。与生成列配合加速如果经常对同一批 JSON 字段做键探测或后续抽取可以考虑使用 generated columns 将 JSON 字段解析结果物化从而加速查询。这是 StarRocks 官方推荐的 JSON 加速手段。结果可继续链式处理返回的 JSON 数组可以继续作为其他 JSON 函数或算子如json_length、json_query、cast的输入实现多级解析。相关参考JSON 函数与算子总览JSON 路径表达式生成列加速 JSON 查询源码实现be/src/exprs/json_functions.cpp单元测试be/test/exprs/json_functions_test.cpp【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考