本文介绍JSON函数的基本语法及示例。
日志服务支持如下JSON函数。
-
在日志服务分析语句中，表示字符串的字符必须使用单引号（''）包裹，无符号包裹或被双引号（""）包裹的字符表示字段名或列名。例如：
'status'表示字符串status，status或"status"表示日志字段status。 -
如果日志字段的值为JSON类型且需要展开为多行，请使用unnest语法。更多信息，请参见UNNEST子句。
-
如果字符串被解析成JSON类型失败，则返回null。
-
如果在采集过程中，JSON日志被截断，则在使用JSON函数进行查询与分析时，系统将报错且中止查询与分析。针对该错误，您可以使用TRY表达式捕获异常信息，使得系统继续执行查询和分析操作。例如
* | select message, try(json_parse(message))。更多信息，请参见TRY表达式。
|
函数名称 |
语法 |
说明 |
支持SQL |
支持SPL |
|
json_array_contains(x, value) |
判断JSON数组中是否包含某个值。 |
√ |
√ |
|
|
json_array_get(x, index) |
获取JSON数组中某个下标对应的元素。 |
√ |
× |
|
|
json_array_length(x) |
计算JSON数组中元素的数量。 |
√ |
√ |
|
|
json_extract(x, json_path) |
从JSON对象或JSON数组中提取一组JSON值（数组或对象）。 |
√ |
√ |
|
|
json_extract_scalar(x, json_path) |
从JSON对象或JSON数组中提取一组标量值（字符串、整数或布尔值）。类似于json_extract函数。 |
√ |
√ |
|
|
json_extract_bool(x, json_path) |
从JSON对象或JSON数组中提取boolean值。 |
√ |
× |
|
|
json_extract_long(x, json_path) |
从JSON对象或JSON数组中提取bigint值。 |
√ |
× |
|
|
json_extract_double(x, json_path) |
从JSON对象或JSON数组中提取double值。 |
√ |
× |
|
|
json_format(x) |
把JSON类型转换为字符串类型。 |
√ |
√ |
|
|
json_parse(x) |
把字符串类型转换为JSON类型。 |
√ |
√ |
|
|
json_size(x, json_path) |
计算JSON对象或数组中元素的数量。 |
√ |
√ |
|
|
json_object_flatten(x) |
将JSON对象压缩为单层键值结构。 |
√ |
× |
json_array_contains函数
json_array_contains函数用于判断JSON数组中是否包含某个值。
语法
json_array_contains(x, value)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON数组。 |
|
value |
数值。 |
返回值类型
boolean类型。
示例
判断JSON数组[1, 2, 3]中是否包含2。
-
查询和分析语句（调试）
* | SELECT json_array_contains('[1, 2, 3]', 2) -
查询和分析结果为true，表示JSON数组[1, 2, 3]中包含2。
json_array_get函数
json_array_get函数用于获取JSON数组下标对应的元素。
语法
json_array_get(x, index)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON数组。 |
|
index |
JSON下标，从0开始。 |
返回值类型
varchar类型。
示例
返回JSON数组["a", [3, 9], "c"]下标为1的元素。
-
查询和分析语句（调试）
* | SELECT json_array_get('["a", [3, 9], "c"]', 1) -
查询和分析结果为[3,9]。
json_array_length函数
json_array_length函数用于计算JSON数组中元素的数量。
语法
json_array_length(x)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON数组。 |
返回值类型
bigint类型。
示例
-
示例1：计算Results字段值中JSON元素的数量。
-
字段样例
Results:[{"EndTime":1626314920},{"FireResult":2}] -
查询和分析语句
* | SELECT json_array_length(Results) -
查询和分析结果为2。
-
-
示例2：计算time字段值中JSON元素的数量。
-
字段样例
time:["time_local","request_time","upstream_response_time"] -
查询和分析语句
* | SELECT json_array_length(time) -
查询和分析结果为3。
-
json_extract函数
json_extract函数用于从JSON对象或JSON数组中提取一组JSON值（数组或对象）。
针对非法的JSON类型，json_extract函数会报错，建议您使用json_extract_scalar函数。
语法
json_extract(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON对象或JSON数组。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
JSON格式的string类型。
示例
SQL
获取Results字段中EndTime字段的值。
-
字段样例
Results:[{"EndTime":1626314920},{"FireResult":2}] -
查询和分析语句
* | SELECT json_extract(Results, '$.0.EndTime') -
查询和分析结果为1626314920。
SPL
获取Results字段中EndTime字段的值。
-
字段样例
Results:[{"EndTime":1626314920},{"FireResult":2}]-
SPL语句
* | extend a = json_extract(Results, '$.0.EndTime')-
SPL结果
返回结果中，字段a的值为1626314920。
json_extract_scalar函数
json_extract_scalar函数用于从JSON对象或JSON数组中提取一组标量值（字符串、整数或布尔值）。
语法
json_extract_scalar(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON对象或JSON数组。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
varchar类型。
示例
SQL
从Results字段中获取RawResultCount字段的值，并将该值转换为bigint类型进行求和。
-
字段样例
Results:[{"EndTime":1626314920},{"RawResultCount":1}] -
查询和分析语句
* | SELECT sum(cast(json_extract_scalar(Results,'$.1.RawResultCount') AS bigint) ) -
查询和分析结果为288。
SPL
从Results字段中获取RawResultCount字段的值。
-
字段样例
Results:[{"EndTime":1626314920},{"RawResultCount":1}]-
SPL语句
* | extend a = json_extract_scalar(Results, '$.1.RawResultCount')-
SPL结果中，字段a的值为1。
json_extract_bool函数
json_extract_bool函数用于从JSON对象或JSON数组中提取boolean值，提取失败返回null。
语法
json_extract_bool(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON类型。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
boolean类型。
示例
从JSON数组Results中提取boolean值。
-
字段样例
Results:[{"ret":true},{"status":FALSE}] -
查询和分析语句
* | SELECT json_extract_bool(Results, '$.0.ret') -
查询和分析结果
返回结果为true。
json_extract_long函数
json_extract_long函数用于从JSON对象或JSON数组中提取bigint值，提取失败返回null。
语法
json_extract_long(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON类型。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
bigint类型。
示例
从JSON数组Results中提取bigint值。
-
字段样例
Results:[{"EndTime":1626314920},{"FireResult":2}] -
查询和分析语句
* | SELECT json_extract_long(Results, '$.0.EndTime') -
查询和分析结果
返回结果为1626314920。
json_extract_double函数
json_extract_double函数用于从JSON对象或JSON数组中提取double值，提取失败返回null。
语法
json_extract_double(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON类型。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
double类型。
示例
从JSON数组Results中提取double值。
-
字段样例
Results:[{"EndTime":1626314920},{"FireResult":2}] -
查询和分析语句
* | SELECT json_extract_double(Results, '$.0.EndTime') -
查询和分析结果
返回结果为1626314920.0。
json_format函数
json_format函数用于将JSON类型转化成字符串类型。
语法
json_format(x)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON类型。 |
返回值类型
varchar类型。
示例
将JSON数组[1,2,3]转换为字符串[1, 2, 3]。
-
查询和分析语句（调试）
* | SELECT json_format(json_parse('[1, 2, 3]')) -
查询和分析结果为[1,2,3]。
json_parse函数
json_parse函数只用于将字符串类型转化成JSON类型，判断是否符合JSON格式。一般情况下，json_parse函数使用意义不大，如果您需要从JSON中提取值，建议使用json_extract_scalar函数。
语法
json_parse(x)参数说明
|
参数 |
说明 |
|
x |
参数值为字符串。 |
返回值类型
JSON类型。
示例
SQL
-
示例1
将字符串[1,2,3]转换为JSON数组[1, 2, 3]。
-
查询和分析语句（调试）
* | SELECT json_parse('[1, 2, 3]') -
查询和分析结果为[1,2,3]。
-
-
示例2
提取
logging字段中的各个子字段。-
字段样例如下，logging字段为JSON对象，包含message、processName、thread、threadName、module、funcName、levelName、process等键值对。
-
查询和分析语句（调试）
*| SELECT map_keys(try_cast(json_parse(logging) AS map(varchar, json))) -
查询和分析结果为["funcName","levelname","message","module","process","processName","thread","threadName"]。
-
SPL
将字符串[1,2,3]转换为JSON数组[1, 2, 3]。
-
SPL语句
* | extend a = json_parse('[1, 2, 3]')-
SPL结果
返回结果中，字段a的值为[1, 2, 3]。
json_size函数
json_size函数用于计算JSON对象或JSON数组中元素的数量。
语法
json_size(x, json_path)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON对象或JSON数组。 |
|
json_path |
JSON路径，格式为$.store.book[0].title。更多信息，请参见如何设置json_path。 |
返回值类型
bigint类型。
示例
返回status字段中元素的数量。
-
字段样例
Results:[{"EndTime":1626314920,"FireResult":2,"RawResults":[{"_col0":"1094"}]}] -
查询和分析语句
* | SELECT json_size(Results, '$.0.RawResults') -
查询和分析结果为1。
json_object_flatten函数
json_object_flatten函数用于将JSON 对象压缩为单层键值结构。
语法
json_object_flatten(x)参数说明
|
参数 |
说明 |
|
x |
参数值为JSON类型。如果JSON对象非Object，则返回null。 |
返回值类型
map(varchar, varchar)类型。
示例
将content字段JSON内容压缩为1层键值对。
-
字段样例
content: '{"Time":1626314920,"Info":[{"count":"1"}],"Body":"this is test"}' -
查询和分析语句
select json_object_flatten(content) as data from (values '{"Time":1626314920,"Info":[{"count":"1"}],"Body":"this is test"}') t (content) limit 1; -
输出数据
如下，data字段的值为{"Time":"1626314920","Info":"[{\"count\":\"1\"}]","Body":"this is test"}，即原始JSON对象已被压缩为单层键值结构。