结构化与半结构化函数
TiDB Cloud Lake 中的结构化与半结构化函数可高效处理数组、对象、映射、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 空值转换为 SQL NULL 值 | STRIP_NULL_VALUE(parse_json('null')) → NULL |
| JSON_STRIP_NULLS | 从 JSON 对象中移除空值 | JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}')) → {"a":1} |
数组/对象展开
| 函数 | 描述 | 示例 |
|---|---|---|
| JSON_EACH | 将 JSON 对象展开为键值对 | JSON_EACH(PARSE_JSON('{"a":1,"b":2}')) |
| JSON_ARRAY_ELEMENTS | 将 JSON 数组展开为单独的元素 | JSON_ARRAY_ELEMENTS(PARSE_JSON('[1,2,3]')) |
数组函数
| 函数 | 描述 | 示例 |
|---|---|---|
| ARRAY | 从表达式构建数组 | ARRAY(1, 2, 3) |
| ARRAY_CONSTRUCT | 从单个值创建数组 | ARRAY_CONSTRUCT(1, 2, 3) |
| RANGE | 生成由连续数字组成的数组 | RANGE(1, 5) |
| ARRAY_GENERATE_RANGE | 生成可选步长的序列 | ARRAY_GENERATE_RANGE(0, 6, 2) |
| GET | 通过索引从数组中获取元素 | GET([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_SIZE | 返回数组长度（别名：ARRAY_LENGTH） | ARRAY_SIZE([1,2,3]) |
| ARRAY_COUNT | 统计非 NULL 元素的数量 | ARRAY_COUNT([1,NULL,2]) |
| ARRAY_ANY | 返回第一个非 NULL 条目 | ARRAY_ANY([NULL,'a','b']) |
| 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_SUM | 数值的总和 | ARRAY_SUM([1,2,3]) |
| ARRAY_AVG | 数值的平均值 | ARRAY_AVG([1,2,3]) |
| ARRAY_MEDIAN | 数值的中位数 | ARRAY_MEDIAN([1,3,2]) |
| ARRAY_MIN | 最小值 | ARRAY_MIN([1,2,3]) |
| ARRAY_MAX | 最大值 | ARRAY_MAX([1,2,3]) |
| ARRAY_STDDEV_POP | 总体标准差 | ARRAY_STDDEV_POP([1,2,3]) |
| ARRAY_STDDEV_SAMP | 样本标准差 | ARRAY_STDDEV_SAMP([1,2,3]) |
| ARRAY_KURTOSIS | 超额峰度 | ARRAY_KURTOSIS([1,2,3,4]) |
| ARRAY_SKEWNESS | 偏度 | ARRAY_SKEWNESS([1,2,3,10]) |
| ARRAY_APPROX_COUNT_DISTINCT | 近似去重计数 | ARRAY_APPROX_COUNT_DISTINCT([1,1,2]) |
| ARRAY_SORT | 对值进行排序；不同变体可控制顺序/空值处理 | ARRAY_SORT([3,1,2]) |
| ARRAY_TO_STRING | 连接数组元素 | ARRAY_TO_STRING(['a','b'], ',') |
| ARRAY_COMPACT | 从数组中移除空值 | 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 对象 | 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 函数
| 函数 | 描述 | 示例 |
|---|---|---|
| MAP_CAT | 将多个 map 合并为一个 map | MAP_CAT({'a':1}, {'b':2}) |
| MAP_KEYS | 以数组形式返回 map 中的所有键 | MAP_KEYS({'a':1, 'b':2}) |
| MAP_VALUES | 以数组形式返回 map 中的所有值 | MAP_VALUES({'a':1, 'b':2}) |
| MAP_SIZE | 返回 map 中键值对的数量 | MAP_SIZE({'a':1, 'b':2}) |
| MAP_CONTAINS_KEY | 检查 map 是否包含指定键 | MAP_CONTAINS_KEY({'a':1}, 'a') |
| MAP_INSERT | 向 map 中插入键值对 | MAP_INSERT({'a':1}, 'b', 2) |
| MAP_DELETE | 从 map 中移除键值对 | MAP_DELETE({'a':1, 'b':2}, 'b') |
| MAP_TRANSFORM_KEYS | 对 map 中的每个键应用一个函数 | MAP_TRANSFORM_KEYS(map, k -> UPPER(k)) |
| MAP_TRANSFORM_VALUES | 对 map 中的每个值应用一个函数 | MAP_TRANSFORM_VALUES(map, v -> v * 2) |
| MAP_FILTER | 根据谓词过滤键值对 | MAP_FILTER(map, (k, v) -> v > 10) |
| MAP_PICK | 创建仅包含指定键的新 map | 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 值是否为数组 | IS_ARRAY(PARSE_JSON('[1,2,3]')) |
| IS_OBJECT | 检查 JSON 值是否为对象 | IS_OBJECT(PARSE_JSON('{"a":1}')) |
| IS_STRING | 检查 JSON 值是否为字符串 | 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 值是否为布尔值 | IS_BOOLEAN(PARSE_JSON('true')) |
| IS_NULL_VALUE | 检查 JSON 值是否为空值 | IS_NULL_VALUE(PARSE_JSON('null')) |