JSON 函数
以下是对 ClickHouse 文档文本的中文翻译，遵循了提交时设置的所有规则：
有两组用于解析 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。
参数
返回值
- 如果字段存在，返回
1，否则返回0。 UInt8。
示例
查询：
结果：
simpleJSONExtractUInt
从名为 field_name 的字段的值中解析 UInt64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或字段存在但不包含数字，则返回 0。
语法
别名：visitParamExtractUInt。
参数
返回值
- 如果字段存在且包含数字，则返回解析出的数字，其他情况返回
0。 UInt64。
示例
查询：
结果：
simpleJSONExtractInt
从名为 field_name 的字段的值中解析 Int64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或字段存在但不包含数字，则返回 0。
语法
别名：visitParamExtractInt。
参数
返回值
- 如果字段存在且包含数字，则返回解析出的数字，其他情况返回
0。 Int64。
示例
查询：
结果：
simpleJSONExtractFloat
从名为 field_name 的字段的值中解析 Float64。如果这是一个字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或字段存在但不包含数字，则返回 0。
语法
别名：visitParamExtractFloat。
参数
返回值
- 如果字段存在且包含数字，则返回解析出的数字，其他情况返回
0。 Float64。
示例
查询：
结果：
simpleJSONExtractBool
从名为 field_name 的字段的值中解析真/假值。结果为 UInt8。
语法
别名：visitParamExtractBool。
参数
返回值
如果字段的值为 true，则返回 1，否则返回 0。这意味着此功能将返回 0，包括（而不仅仅是）以下情况：
- 字段不存在。
- 字段以字符串形式包含
true，例如：{"field":"true"}。 - 字段以数值形式包含
1。
示例
查询：
结果：
simpleJSONExtractRaw
将名为 field_name 的字段的值作为 String 返回，包括分隔符。
语法
别名：visitParamExtractRaw。
参数
返回值
- 如果字段存在，返回字段的值（包括分隔符）作为字符串，否则返回空字符串。
String
示例
查询：
结果：
simpleJSONExtractString
从名为 field_name 的字段的值中解析用双引号括起来的 String。
语法
别名：visitParamExtractString。
参数
返回值
- 返回字段的未转义值作为字符串，包括分隔符。如果字段不包含用双引号括起来的字符串、如果解转义失败，或字段不存在，则返回空字符串。 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 个成员/键。
返回值
- 将值的类型作为字符串返回，若值不存在，则返回
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 对象中的内部字段的逗号分隔索引或键。每个参数可以是 String 通过密钥获取字段或 Integer 以获取第 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 对象中的内部字段。每个参数可以是 string 通过密钥获取字段或 integer 以获取第 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 标量。如果值不存在，则默认返回空字符串。
此函数受以下设置控制：
- 通过 SET
function_json_value_return_type_allow_nullable=true，将返回NULL。如果值为复杂类型（例如：结构、数组、映射），则默认返回空字符串。 - 通过 SET
function_json_value_return_type_allow_complex=true，将返回复杂值。
语法
参数
在 21.11 版本之前，参数顺序是错误的，即 JSON_EXISTS(path, json)
返回值
- 如果存在，则返回提取的值作为 JSON 标量，否则返回空字符串。 String。
示例
查询：
结果：
toJSONString
将值序列化为其 JSON 表示形式。支持各种数据类型和嵌套结构。
64 位 整数 或更大（如 UInt64 或 Int128）默认为带引号。 output_format_json_quote_64bit_integers 控制此行为。
特殊值 NaN 和 inf 被替换为 null。启用 output_format_json_quote_denormals 设置以显示它们。
当序列化 Enum 值时，该函数输出其名称。
语法
参数
value— 要序列化的值。值可以是任何数据类型。
返回值
- 值的 JSON 表示形式。 String。
示例
第一个示例显示对 Map 的序列化。 第二个示例显示一些特殊值包装成 Tuple。
查询：
结果：
另见
JSONArrayLength
返回最外层 JSON 数组中的元素数量。如果输入 JSON 字符串无效，则该函数返回 NULL。
语法
别名：JSON_ARRAY_LENGTH(json)。
参数
json— String 有效的 JSON。
返回值
- 如果
json是有效的 JSON 数组字符串，则返回数组元素的数量，否则返回 NULL。 Nullable(UInt64)。
示例
jsonMergePatch
返回通过合并多个 JSON 对象形成的合并后的 JSON 对象字符串。
语法
参数
json— String 有效的 JSON。
返回值
- 如果 JSON 对象字符串有效，则返回合并后的 JSON 对象字符串。 String。
示例
JSONAllPaths
返回存储在每行 JSON 列中的所有路径的列表。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Array(String)。
示例
JSONAllPathsWithTypes
返回存储在每行 JSON 列中的所有路径及其数据类型的映射。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Map(String, String)。
示例
JSONDynamicPaths
返回作为独立子列存储在 JSON 列中的动态路径的列表。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Array(String)。
示例
JSONDynamicPathsWithTypes
返回存储为独立子列的动态路径及其类型的映射，在每行的 JSON 列中。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Map(String, String)。
示例
JSONSharedDataPaths
返回存储在 JSON 列中共享数据结构中的路径列表。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Array(String)。
示例
JSONSharedDataPathsWithTypes
返回存储在共享数据结构中的路径及其类型的映射，在每行的 JSON 列中。
语法
参数
json— JSON。
返回值
- 一个路径的数组。 Map(String, String)。
示例
