json-functions
有两组函数用于解析 JSON：
simpleJSON*(visitParam*) 旨在以极快的速度解析一个有限子集的 JSON。JSONExtract*旨在解析普通 JSON。
simpleJSON (visitParam) 函数
ClickHouse 提供了一些专用于简化 JSON 的特殊函数。所有这些 JSON 函数都是基于对 JSON 的强假设。它们尽量做最少的工作，以便尽快完成任务。
以下假设成立：
- 字段名称（函数参数）必须是常量。
- 字段名称在 JSON 中以某种方式是规范编码的。例如：
simpleJSONHas('{"abc":"def"}', 'abc') = 1，但simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0 - 在任意嵌套级别上无差别地搜索字段。如果有多个匹配的字段，将使用第一个出现的字段。
- JSON 中字符串文字之外不应有空格字符。
simpleJSONHas
检查是否存在名为 field_name 的字段。结果为 UInt8。
语法
别名：visitParamHas。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 如果字段存在则返回
1，否则返回0。 UInt8。
示例
查询：
结果：
simpleJSONExtractUInt
从名为 field_name 的字段值中解析 UInt64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或者存在但不包含数字，则返回 0。
语法
别名：visitParamExtractUInt。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 如果字段存在并且包含数字，则返回从字段中解析出的数字，反之返回
0。 UInt64。
示例
查询：
结果：
simpleJSONExtractInt
从名为 field_name 的字段值中解析 Int64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或者存在但不包含数字，则返回 0。
语法
别名：visitParamExtractInt。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 如果字段存在并且包含数字，则返回从字段中解析出的数字，反之返回
0。 Int64。
示例
查询：
结果：
simpleJSONExtractFloat
从名为 field_name 的字段值中解析 Float64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或者存在但不包含数字，则返回 0。
语法
别名：visitParamExtractFloat。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 如果字段存在并且包含数字，则返回从字段中解析出的数字，反之返回
0。 Float64.
示例
查询：
结果：
simpleJSONExtractBool
从名为 field_name 的字段值中解析一个 true/false 值。结果为 UInt8。
语法
别名：visitParamExtractBool。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
如果字段的值为 true，则返回 1，否则返回 0。这意味着该函数将返回 0 的情况包括（但不限于）：
- 如果字段不存在。
- 如果字段以字符串形式包含
true，例如：{"field":"true"}。 - 如果字段以数字值
1包含。
示例
查询：
结果：
simpleJSONExtractRaw
将名为 field_name 的字段的值作为 String 返回，包括分隔符。
语法
别名：visitParamExtractRaw。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 如果字段存在，则返回字段的值作为字符串（包括分隔符）；否则返回空字符串。
String
示例
查询：
结果：
simpleJSONExtractString
从名为 field_name 的字段值中解析出带双引号的 String。
语法
别名：visitParamExtractString。
参数
json— 要搜索字段的 JSON。 Stringfield_name— 要搜索的字段名称。 String literal
返回值
- 返回字段的未转义值作为字符串，包括分隔符。如果字段不包含双引号字符串、解除转义失败或字段不存在，则返回空字符串。 String。
实施细节
目前不支持格式为 \uXXXX\uYYYY 的代码点，它们未从基本多语言平面（基本多语言平面）转换为 CESU-8 而不是 UTF-8。
示例
查询：
结果：
JSONExtract 函数
以下函数基于 simdjson 并设计用于更复杂的 JSON 解析需求。
isValidJSON
检查传入字符串是否为有效的 JSON。
语法
示例
JSONHas
如果值存在于 JSON 文档中，则返回 1。如果值不存在，则返回 0。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 如果值存在于
json中，返回1，否则返回0。 UInt8。
示例
查询：
元素的最小索引为 1。因此，元素 0 不存在。您可以使用整数访问 JSON 数组和 JSON 对象。例如：
JSONLength
返回 JSON 数组或 JSON 对象的长度。如果值不存在或类型错误，则返回 0。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 返回 JSON 数组或 JSON 对象的长度。如果值不存在或类型错误，则返回
0。 UInt64。
示例
JSONType
返回 JSON 值的类型。如果值不存在，则返回 Null=0（不是通常的 Null，而是 Enum8('Null' = 0, 'String' = 34,...)。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 返回 JSON 值的类型作为字符串，如果值不存在则返回
Null=0。 Enum。
示例
JSONExtractUInt
解析 JSON 并提取 UInt 类型的值。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 如果存在，则返回UInt值，否则返回
0。 UInt64。
示例
查询：
结果：
JSONExtractInt
解析 JSON 并提取 Int 类型的值。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 如果存在，则返回Int值，否则返回
0。 Int64。
示例
查询：
结果：
JSONExtractFloat
解析 JSON 并提取 Float 类型的值。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 如果存在，则返回 Float 值，否则返回
0。 Float64。
示例
查询：
结果：
JSONExtractBool
解析 JSON 并提取布尔值。如果值不存在或类型错误，则返回 0。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 如果存在，则返回布尔值，否则返回
0。 Bool。
示例
查询：
结果：
JSONExtractString
解析 JSON 并提取字符串。该函数与 visitParamExtractString 函数类似。如果值不存在或类型错误，则返回空字符串。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 返回 JSON 中的未转义字符串。如果解除转义失败，值不存在或类型错误，则返回空字符串。 String。
示例
JSONExtract
解析 JSON 并提取给定的 ClickHouse 数据类型的值。该函数是之前 JSONExtract<type> 函数的通用版本。意味着：
JSONExtract(..., 'String') 的返回值与 JSONExtractString() 完全相同，
JSONExtract(..., 'Float64') 的返回值与 JSONExtractFloat() 完全相同。
语法
参数
json— 要解析的 JSON 字符串。 String。indices_or_keys— 一个参数列表，可以是零或多个参数，每个参数可以是字符串或整数。 String， Int*。return_type— 字符串，指定要提取的值的类型。 String。
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
示例
通过传递多个 indices_or_keys 参数引用嵌套值：
结果：
JSONExtractKeysAndValues
从 JSON 中解析键值对，其中值是给定的 ClickHouse 数据类型。
语法
参数
json— 要解析的 JSON 字符串。 String。indices_or_keys— 一个参数列表，可以是零或多个参数，每个参数可以是字符串或整数。 String， Int*。value_type— 字符串，指定要提取的值的类型。 String。
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
示例
JSONExtractKeys
解析 JSON 字符串并提取键。
语法
参数
json— String 中的有效 JSON。a, b, c...— 逗号分隔的索引或键，指定嵌套 JSON 对象中内字段的路径。每个参数可以是字符串（通过键获取字段）或整数（获取第 N 个字段，索引从 1 开始，负整数从末尾计数）。如果未设置，则将整个 JSON 解析为顶级对象。可选参数。
返回值
示例
查询：
结果：
JSONExtractRaw
将 JSON 的一部分作为未解析的字符串返回。如果部分不存在或类型错误，则返回空字符串。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
- 将 JSON 的一部分作为未解析的字符串返回。如果部分不存在或类型错误，则返回空字符串。 String。
示例
JSONExtractArrayRaw
返回包含 JSON 数组元素的数组，每个元素表示为未解析的字符串。如果部分不存在或不是数组，则返回空数组。
语法
参数
indices_or_keys 类型：
- 字符串 = 按键访问对象成员。
- 正整数 = 从开头访问第 n 个成员/键。
- 负整数 = 从末尾访问第 n 个成员/键。
返回值
示例
JSONExtractKeysAndValuesRaw
从 JSON 对象中提取原始数据。
语法
参数
json— String 中的有效 JSON。p, a, t, h— 逗号分隔的索引或键，指定嵌套 JSON 对象中内字段的路径。每个参数可以是字符串（通过键获取字段）或整数（获取第 N 个字段，索引从 1 开始，负整数从末尾计数）。如果未设置，则将整个 JSON 解析为顶级对象。可选参数。
返回值
- 包含
('key', 'value')元组的数组。两个元组成员都是字符串。 Array(Tuple(String, String))。 - 如果请求的对象不存在或输入 JSON 无效，则返回空数组。 Array(Tuple(String, String))。
示例
查询：
结果：
查询：
结果：
查询：
结果：
JSON_EXISTS
如果值存在于 JSON 文档中，则返回 1。如果值不存在，则返回 0。
语法
参数
在 21.11 版本之前，参数的顺序是错误的，即 JSON_EXISTS(path, json)
返回值
- 如果值存在于 JSON 文档中，则返回
1，否则返回0。
示例
JSON_QUERY
解析 JSON 并将其值提取为 JSON 数组或 JSON 对象。如果值不存在，则返回空字符串。
语法
参数
在 21.11 版本之前，参数的顺序是错误的，即 JSON_EXISTS(path, json)
返回值
- 返回提取的值作为 JSON 数组或 JSON 对象。如果值不存在，则返回空字符串。 String。
示例
查询：
结果：
JSON_VALUE
解析 JSON 并提取一个 JSON 标量值。如果该值不存在，默认将返回一个空字符串。
此函数受以下设置控制：
- 通过设置
function_json_value_return_type_allow_nullable=true，将返回NULL。如果该值是复杂类型（例如：结构体、数组、映射），默认将返回一个空字符串。 - 通过设置
function_json_value_return_type_allow_complex=true，将返回复杂值。
语法
参数
在版本 21.11 之前，参数的顺序是错误的，即 JSON_EXISTS(path, json)
返回值
- 如果提取的值存在，则以 JSON 标量形式返回，否则将返回一个空字符串。 字符串。
示例
查询：
结果：
toJSONString
将值序列化为其 JSON 表示。支持各种数据类型和嵌套结构。
64 位 整数 或更大的整数（如 UInt64 或 Int128）默认用引号括起来。 output_format_json_quote_64bit_integers 控制此行为。
特殊值 NaN 和 inf 被替换为 null。启用 output_format_json_quote_denormals 设置以显示它们。
序列化 枚举 值时，函数输出其名称。
语法
参数
value— 要序列化的值。值可以是任何数据类型。
返回值
- 值的 JSON 表示。 字符串。
示例
第一个示例显示 映射 的序列化。 第二个示例显示一些特殊值被包装在 元组 中。
查询：
结果：
另请参阅
JSONArrayLength
返回最外层 JSON 数组中的元素数量。如果输入的 JSON 字符串无效，函数返回 NULL。
语法
别名： JSON_ARRAY_LENGTH(json)。
参数
json— 字符串，包含有效 JSON。
返回值
- 如果
json是有效的 JSON 数组字符串，则返回数组元素的数量，否则返回 NULL。 Nullable(UInt64)。
示例
jsonMergePatch
返回合并多个 JSON 对象形成的合并 JSON 对象字符串。
语法
参数
json— 字符串，包含有效 JSON。
返回值
- 如果 JSON 对象字符串有效，则返回合并后的 JSON 对象字符串。 字符串。
示例
JSONAllPaths
返回存储在每个行中的 JSON 列的所有路径列表。
语法
参数
json— JSON。
返回值
- 一个路径数组。 数组(字符串)。
示例
JSONAllPathsWithTypes
返回存储在每个行中的 JSON 列的所有路径及其数据类型的映射。
语法
参数
json— JSON。
返回值
- 一个路径数组。 映射(字符串, 字符串)。
示例
JSONDynamicPaths
返回存储为 JSON 列中单独子列的动态路径列表。
语法
参数
json— JSON。
返回值
- 一个路径数组。 数组(字符串)。
示例
JSONDynamicPathsWithTypes
返回存储为 JSON 列中单独子列的动态路径及其类型的映射。
语法
参数
json— JSON。
返回值
- 一个路径数组。 映射(字符串, 字符串)。
示例
JSONSharedDataPaths
返回存储在共享数据结构中的路径列表，列在 JSON 列中。
语法
参数
json— JSON。
返回值
- 一个路径数组。 数组(字符串)。
示例
JSONSharedDataPathsWithTypes
返回存储在共享数据结构中的路径及其类型的映射，列在 JSON 列中。
语法
参数
json— JSON。
返回值
- 一个路径数组。 映射(字符串, 字符串)。
示例