结构化与半结构化函数
Databend 中的结构化与半结构化函数能够高效处理数组（Array）、对象（Object）、映射（Map）、JSON 以及其他结构化数据格式。这些函数为创建、解析、查询、转换和操作结构化及半结构化数据提供了全面的能力。
JSON 函数
解析与验证
| 函数 | 描述 | 示例 |
|---|---|---|
| PARSE_JSON | 将 JSON 字符串解析为 VARIANT 值 | PARSE_JSON('[1,2,3]') |
| CHECK_JSON | 验证字符串是否为有效 JSON | CHECK_JSON('{"a":1}') |
| JSON_TYPEOF | 返回 JSON 值的类型 | JSON_TYPEOF(PARSE_JSON('[1,2,3]')) |
基于路径的查询
| 函数 | 描述 | 示例 |
|---|---|---|
| JSON_PATH_EXISTS | 检查 JSON 路径是否存在 | JSON_PATH_EXISTS(json_obj, '$.name') |
| JSON_PATH_QUERY | 使用 JSONPath 查询 JSON 数据 | JSON_PATH_QUERY(json_obj, '$.items[*]') |
| JSON_PATH_QUERY_ARRAY | 查询 JSON 数据并以数组形式返回结果 | JSON_PATH_QUERY_ARRAY(json_obj, '$.items') |
| JSON_PATH_QUERY_FIRST | 返回 JSON 路径查询的第一个结果 | JSON_PATH_QUERY_FIRST(json_obj, '$.items[*]') |
| JSON_PATH_MATCH | 根据路径模式匹配 JSON 值 | JSON_PATH_MATCH(json_obj, '$.age') |
| JQ | 使用 jq 语法进行高级 JSON 处理 | JQ('.name', json_obj) |
值提取
| 函数 | 描述 | 示例 |
|---|---|---|
| GET | 通过键从 JSON 对象或通过索引从数组中获取值 | GET(PARSE_JSON('[1,2,3]'), 0) |
| GET_PATH | 使用路径表达式从 JSON 对象中获取值 | GET_PATH(json_obj, 'user.name') |
| GET_IGNORE_CASE | 以不区分大小写的键匹配方式获取值 | GET_IGNORE_CASE(json_obj, 'NAME') |
| JSON_EXTRACT_PATH_TEXT | 使用路径从 JSON 中提取文本值 | JSON_EXTRACT_PATH_TEXT(json_obj, 'name') |
转换与输出
| 函数 | 描述 | 示例 |
|---|---|---|
| JSON_TO_STRING | 将 JSON 值转换为字符串 | JSON_TO_STRING(PARSE_JSON('{"a":1}')) |
| JSON_PRETTY | 使用适当缩进格式化 JSON | JSON_PRETTY(PARSE_JSON('{"a":1}')) |
| STRIP_NULL_VALUE | 从 JSON 中移除 null 值 | STRIP_NULL_VALUE(PARSE_JSON('{"a":1,"b":null}')) |
数组/对象展开
| 函数 | 描述 | 示例 |
|---|---|---|
| JSON_EACH | 将 JSON 对象展开为键值对 | JSON_EACH(PARSE_JSON('{"a":1,"b":2}')) |
| JSON_ARRAY_ELEMENTS | 将 JSON 数组展开为单个元素 | JSON_ARRAY_ELEMENTS(PARSE_JSON('[1,2,3]')) |
数组函数
| 函数 | 描述 | 示例 |
|---|---|---|
| ARRAY_CONSTRUCT | 从单个值创建数组 | ARRAY_CONSTRUCT(1, 2, 3) |
| RANGE | 生成连续数字的数组 | RANGE(1, 5) |
| GET | 通过索引从数组中获取元素 | GET(PARSE_JSON('[1,2,3]'), 0) |
| ARRAY_GET | GET 函数的别名 | ARRAY_GET([1,2,3], 1) |
| CONTAINS | 检查数组是否包含特定值 | CONTAINS([1,2,3], 2) |
| ARRAY_CONTAINS | 检查数组是否包含特定值 | ARRAY_CONTAINS([1,2,3], 2) |
| ARRAY_APPEND | 将元素追加到数组末尾 | ARRAY_APPEND([1,2], 3) |
| ARRAY_PREPEND | 将元素前插到数组开头 | ARRAY_PREPEND([2,3], 1) |
| ARRAY_INSERT | 在指定位置插入元素 | ARRAY_INSERT([1,3], 1, 2) |
| ARRAY_REMOVE | 移除所有出现的指定元素 | ARRAY_REMOVE([1,2,2,3], 2) |
| ARRAY_REMOVE_FIRST | 从数组中移除第一个元素 | ARRAY_REMOVE_FIRST([1,2,3]) |
| ARRAY_REMOVE_LAST | 从数组中移除最后一个元素 | ARRAY_REMOVE_LAST([1,2,3]) |
| ARRAY_CONCAT | 连接多个数组 | ARRAY_CONCAT([1,2], [3,4]) |
| ARRAY_SLICE | 提取数组的一部分 | ARRAY_SLICE([1,2,3,4], 1, 2) |
| SLICE | ARRAY_SLICE 函数的别名 | SLICE([1,2,3,4], 1, 2) |
| ARRAYS_ZIP | 按元素方式组合多个数组 | ARRAYS_ZIP([1,2], ['a','b']) |
| ARRAY_DISTINCT | 从数组中返回唯一元素 | ARRAY_DISTINCT([1,2,2,3]) |
| ARRAY_UNIQUE | ARRAY_DISTINCT 函数的别名 | ARRAY_UNIQUE([1,2,2,3]) |
| ARRAY_INTERSECTION | 返回数组之间的共同元素 | ARRAY_INTERSECTION([1,2,3], [2,3,4]) |
| ARRAY_EXCEPT | 返回存在于第一个数组但不存在于第二个数组中的元素 | ARRAY_EXCEPT([1,2,3], [2,3]) |
| ARRAY_OVERLAP | 检查数组是否有共同元素 | ARRAY_OVERLAP([1,2], [2,3]) |
| ARRAY_TRANSFORM | 对每个数组元素应用函数 | ARRAY_TRANSFORM([1,2,3], x -> x * 2) |
| ARRAY_FILTER | 根据条件筛选数组元素 | ARRAY_FILTER([1,2,3,4], x -> x > 2) |
| ARRAY_REDUCE | 使用聚合将数组归约为单个值 | ARRAY_REDUCE([1,2,3], 0, (acc, x) -> acc + x) |
| ARRAY_AGGREGATE | 使用函数聚合数组元素 | ARRAY_AGGREGATE([1,2,3], 'sum') |
| ARRAY_COMPACT | 从数组中移除 null 值 | ARRAY_COMPACT([1, NULL, 2, NULL, 3]) |
| ARRAY_FLATTEN | 将嵌套数组展平为单个数组 | ARRAY_FLATTEN([[1,2], [3,4]]) |
| ARRAY_REVERSE | 反转数组元素的顺序 | ARRAY_REVERSE([1,2,3]) |
| ARRAY_INDEXOF | 返回元素首次出现的索引 | ARRAY_INDEXOF([1,2,3,2], 2) |
| UNNEST | 将数组展开为单独的行 | UNNEST([1,2,3]) |
对象函数
| 函数 | 描述 | 示例 |
|---|---|---|
| OBJECT_CONSTRUCT | 从键值对创建 JSON 对象 | OBJECT_CONSTRUCT('name', 'John', 'age', 30) |
| OBJECT_CONSTRUCT_KEEP_NULL | 创建 JSON 对象并保留 null 值 | OBJECT_CONSTRUCT_KEEP_NULL('a', 1, 'b', NULL) |
| OBJECT_KEYS | 以数组形式返回 JSON 对象的所有键 | OBJECT_KEYS(PARSE_JSON('{"a":1,"b":2}')) |
| OBJECT_INSERT | 在 JSON 对象中插入或更新键值对 | OBJECT_INSERT(json_obj, 'new_key', 'value') |
| OBJECT_DELETE | 从 JSON 对象中移除键值对 | OBJECT_DELETE(json_obj, 'key_to_remove') |
| OBJECT_PICK | 使用指定键创建新对象 | OBJECT_PICK(json_obj, 'name', 'age') |
映射函数
| 函数 | 描述 | 示例 |
|---|---|---|
| MAP_CAT | 将多个映射合并为单个映射 | MAP_CAT({'a':1}, {'b':2}) |
| MAP_KEYS | 以数组形式返回映射的所有键 | MAP_KEYS({'a':1, 'b':2}) |
| MAP_VALUES | 以数组形式返回映射的所有值 | MAP_VALUES({'a':1, 'b':2}) |
| MAP_SIZE | 返回映射中键值对的数量 | MAP_SIZE({'a':1, 'b':2}) |
| MAP_CONTAINS_KEY | 检查映射是否包含特定键 | MAP_CONTAINS_KEY({'a':1}, 'a') |
| MAP_INSERT | 向映射中插入键值对 | MAP_INSERT({'a':1}, 'b', 2) |
| MAP_DELETE | 从映射中移除键值对 | MAP_DELETE({'a':1, 'b':2}, 'b') |
| MAP_TRANSFORM_KEYS | 对映射中的每个键应用函数 | MAP_TRANSFORM_KEYS(map, k -> UPPER(k)) |
| MAP_TRANSFORM_VALUES | 对映射中的每个值应用函数 | MAP_TRANSFORM_VALUES(map, v -> v * 2) |
| MAP_FILTER | 根据谓词筛选键值对 | MAP_FILTER(map, (k, v) -> v > 10) |
| MAP_PICK | 使用指定键创建新映射 | MAP_PICK({'a':1, 'b':2, 'c':3}, 'a', 'c') |
类型转换函数
| 函数 | 描述 | 示例 |
|---|---|---|
| AS_BOOLEAN | 将 VARIANT 值转换为 BOOLEAN | AS_BOOLEAN(PARSE_JSON('true')) |
| AS_INTEGER | 将 VARIANT 值转换为 BIGINT | AS_INTEGER(PARSE_JSON('42')) |
| AS_FLOAT | 将 VARIANT 值转换为 DOUBLE | AS_FLOAT(PARSE_JSON('3.14')) |
| AS_DECIMAL | 将 VARIANT 值转换为 DECIMAL | AS_DECIMAL(PARSE_JSON('12.34')) |
| AS_STRING | 将 VARIANT 值转换为 STRING | AS_STRING(PARSE_JSON('"hello"')) |
| AS_BINARY | 将 VARIANT 值转换为 BINARY | AS_BINARY(TO_BINARY('abcd')::VARIANT) |
| AS_DATE | 将 VARIANT 值转换为 DATE | AS_DATE(TO_DATE('2025-10-11')::VARIANT) |
| AS_ARRAY | 将 VARIANT 值转换为 ARRAY | AS_ARRAY(PARSE_JSON('[1,2,3]')) |
| AS_OBJECT | 将 VARIANT 值转换为 OBJECT | AS_OBJECT(PARSE_JSON('{"a":1}')) |
类型谓词函数
| 函数 | 描述 | 示例 |
|---|---|---|
| IS_ARRAY | 检查 JSON 值是否为 ARRAY | IS_ARRAY(PARSE_JSON('[1,2,3]')) |
| IS_OBJECT | 检查 JSON 值是否为 OBJECT | IS_OBJECT(PARSE_JSON('{"a":1}')) |
| IS_STRING | 检查 JSON 值是否为 STRING | IS_STRING(PARSE_JSON('"hello"')) |
| IS_INTEGER | 检查 JSON 值是否为整数 | IS_INTEGER(PARSE_JSON('42')) |
| IS_FLOAT | 检查 JSON 值是否为浮点数 | IS_FLOAT(PARSE_JSON('3.14')) |
| IS_BOOLEAN | 检查 JSON 值是否为 BOOLEAN | IS_BOOLEAN(PARSE_JSON('true')) |
| IS_NULL_VALUE | 检查 JSON 值是否为 null | IS_NULL_VALUE(PARSE_JSON('null')) |
