JSON 函数的类型
有两种函数集用于解析 JSON
simpleJSON (visitParam) 函数
ClickHouse 有专门用于处理简化 JSON 的函数。所有这些 JSON 函数都基于对 JSON 可能性的强烈假设。它们尝试尽可能少地完成工作，以便尽快完成。
做出以下假设
- 字段名称（函数参数）必须是常量。
- 字段名称以某种规范方式编码在 JSON 中。例如：
simpleJSONHas('{"abc":"def"}', 'abc') = 1，但 simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0
- 字段会在任何嵌套级别被无差别地搜索。如果有多个匹配的字段，则使用第一次出现的字段。
- JSON 中字符串字面量之外没有空格字符。
这些函数基于 simdjson，专为更复杂的 JSON 解析需求而设计。
这些函数在从 JSON 对象中提取值时执行 ASCII 不区分大小写的键匹配。它们的工作方式与其区分大小写的对应函数完全相同，只是对象键在不考虑大小写的情况下进行匹配。当多个键以不同的方式匹配时，将返回第一个匹配项。
注意
这些函数可能比其区分大小写的对应函数性能更低，因此如果可能，请使用常规的 JSONExtract 函数。
JSONAllPaths
引入于：v24.8
返回 JSON 列中每行存储的所有路径的列表。
语法
参数
返回值
返回 JSON 列中的所有路径的数组。 Array(String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONAllPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONAllPaths(json)─┐
│ {"a":"42"} │ ['a'] │
│ {"b":"Hello"} │ ['b'] │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a','c'] │
└──────────────────────────────────────┴────────────────────┘
JSONAllPathsWithTypes
引入于：v24.8
返回 JSON 列中每行存储的所有路径及其数据类型列表。
语法
JSONAllPathsWithTypes(json)
参数
返回值
返回 JSON 列中所有路径及其数据类型的映射。 Map(String, String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONAllPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONAllPathsWithTypes(json)───────────────┐
│ {"a":"42"} │ {'a':'Int64'} │
│ {"b":"Hello"} │ {'b':'String'} │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'a':'Array(Nullable(Int64))','c':'Date'} │
└──────────────────────────────────────┴───────────────────────────────────────────┘
JSONArrayLength
引入版本: v23.2
返回最外层 JSON 数组中的元素数量。如果输入 JSON 字符串无效，该函数将返回 NULL。
语法
别名：JSON_ARRAY_LENGTH
参数
返回值
如果 json 是有效的 JSON 数组字符串，则返回数组元素的数量，否则返回 NULL。 Nullable(UInt64)
示例
使用示例
SELECT
JSONArrayLength(''),
JSONArrayLength('[1,2,3]');
┌─JSONArrayLength('')─┬─JSONArrayLength('[1,2,3]')─┐
│ ᴺᵁᴸᴸ │ 3 │
└─────────────────────┴────────────────────────────┘
JSONDynamicPaths
引入于：v24.8
返回作为 JSON 列中的单独子列存储的动态路径列表。
语法
参数
返回值
返回 JSON 列中的动态路径数组。 Array(String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONDynamicPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONDynamicPaths(json)─┐
│ {"a":"42"} │ ['a'] │
│ {"b":"Hello"} │ [] │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a'] │
└──────────────────────────────────────┴────────────────────────┘
JSONDynamicPathsWithTypes
引入于：v24.8
返回作为单独子列存储的动态路径列表及其类型，这些路径存储在 JSON 列中的每一行中。
语法
JSONDynamicPathsWithTypes(json)
参数
返回值
返回 JSON 列中动态路径及其数据类型的映射。 Map(String, String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONDynamicPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONDynamicPathsWithTypes(json)─┐
│ {"a":"42"} │ {'a':'Int64'} │
│ {"b":"Hello"} │ {} │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'a':'Array(Nullable(Int64))'} │
└──────────────────────────────────────┴─────────────────────────────────┘
引入于：v19.14
解析 JSON 并使用给定的 ClickHouse 数据类型提取一个值。
语法
JSONExtract(json[, indices_or_keys, ...], return_type)
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*return_type — 要返回的 ClickHouse 数据类型。 String
返回值
如果可能，则返回指定 ClickHouse 数据类型的值，否则返回该类型的默认值。
示例
使用示例
SELECT JSONExtract('{"a": "hello", "b": [-100, 200.0, 300]}', 'Tuple(String, Array(Float64))') AS res;
┌─res──────────────────────────────┐
│ ('hello',[-100,200,300]) │
└──────────────────────────────────┘
引入于: v20.1
返回一个数组，其中包含 JSON 数组的元素，每个元素都表示为未解析的字符串。
语法
JSONExtractArrayRaw(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
返回一个包含 JSON 数组元素的字符串数组。如果该部分不是数组或不存在，则返回一个空数组。 Array(String)
示例
使用示例
SELECT JSONExtractArrayRaw('{"a": "hello", "b": [-100, 200.0, "hello"]}', 'b') AS res;
┌─res──────────────────────────┐
│ ['-100','200.0','"hello"'] │
└──────────────────────────────┘
引入于: v25.8
返回一个数组，其中包含 JSON 数组的元素，每个元素都表示为未解析的字符串，使用不区分大小写的键匹配。此函数类似于 JSONExtractArrayRaw。
语法
JSONExtractArrayRawCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回一个原始 JSON 字符串数组。 Array(String)
示例
基本
SELECT JSONExtractArrayRawCaseInsensitive('{"Items": [1, 2, 3]}', 'ITEMS')
引入于: v20.1
解析 JSON 并提取一个 Bool 类型的值。
语法
JSONExtractBool(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
如果存在，则返回一个 Bool 值，否则返回 0。 Bool
示例
使用示例
SELECT JSONExtractBool('{"passed": true}', 'passed') AS res;
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取一个布尔值。此函数类似于 JSONExtractBool。
语法
JSONExtractBoolCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的布尔值（true 为 1，false 为 0），如果未找到则为 0。 UInt8
示例
基本
SELECT JSONExtractBoolCaseInsensitive('{"IsActive": true}', 'isactive')
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取给定 ClickHouse 数据类型的值。此函数类似于 JSONExtract。
语法
JSONExtractCaseInsensitive(json [, indices_or_keys...], return_type)
参数
json — 要解析的 JSON 字符串 Stringindices_or_keys — 可选。用于导航到该字段的索引或键。键使用不区分大小写的匹配 String 或 (U)Int*return_type — 要提取的 ClickHouse 数据类型 String
返回值
返回指定数据类型中提取的值。 Any
示例
int_type
SELECT JSONExtractCaseInsensitive('{"Number": 123}', 'number', 'Int32')
array_type
SELECT JSONExtractCaseInsensitive('{"List": [1, 2, 3]}', 'list', 'Array(Int32)')
引入于: v20.1
解析 JSON 并提取一个 Float 类型的值。
语法
JSONExtractFloat(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
如果存在，则返回一个 Float 值，否则返回 0。 Float64
示例
使用示例
SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取一个 Float 类型的值。此函数类似于 JSONExtractFloat。
语法
JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的 Float 值，如果未找到或无法转换则为 0。 Float64
示例
基本
SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')
引入于: v20.1
解析 JSON 并提取一个 Int 类型的值。
语法
JSONExtractInt(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
如果存在，则返回一个 Int 值，否则返回 0。 Int64
示例
使用示例
SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;
┌──res─┐
│ -100 │
└──────┘
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取一个 Int 类型的值。此函数类似于 JSONExtractInt。
语法
JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的 Int 值，如果未找到或无法转换则为 0。 Int64
示例
基本
SELECT JSONExtractIntCaseInsensitive('{"Value": 123}', 'value')
嵌套
SELECT JSONExtractIntCaseInsensitive('{"DATA": {"COUNT": 42}}', 'data', 'Count')
引入于：v21.11
解析 JSON 字符串并提取键。
语法
JSONExtractKeys(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
返回一个包含 JSON 对象键的数组。 Array(String)
示例
使用示例
SELECT JSONExtractKeys('{"a": "hello", "b": [-100, 200.0, 300]}') AS res;
┌─res─────────┐
│ ['a','b'] │
└─────────────┘
JSONExtractKeysAndValues
引入于: v20.1
从 JSON 中解析键值对，其中值的 ClickHouse 数据类型给定。
语法
JSONExtractKeysAndValues(json[, indices_or_keys, ...], value_type)
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*value_type — 值的 ClickHouse 数据类型。 String
返回值
返回一个包含解析后的键值对的数组。 Array(Tuple(String, value_type))
示例
使用示例
SELECT JSONExtractKeysAndValues('{"x": {"a": 5, "b": 7, "c": 11}}', 'Int8', 'x') AS res;
┌─res────────────────────┐
│ [('a',5),('b',7),('c',11)] │
└────────────────────────┘
JSONExtractKeysAndValuesCaseInsensitive
引入于: v25.8
使用不区分大小写的键匹配从 JSON 中解析键值对。此函数类似于 JSONExtractKeysAndValues。
语法
JSONExtractKeysAndValuesCaseInsensitive(json [, indices_or_keys...], value_type)
参数
json — 要解析的 JSON 字符串 Stringindices_or_keys — 可选。用于导航到对象的索引或键。键使用不区分大小写的匹配 String 或 (U)Int*value_type — 值的 ClickHouse 数据类型 String
返回值
返回一个包含键值对的元组数组。 Array(Tuple(String, T))
示例
基本
SELECT JSONExtractKeysAndValuesCaseInsensitive('{"Name": "Alice", "AGE": 30}', 'String')
[('Name','Alice'),('AGE','30')]
JSONExtractKeysAndValuesRaw
引入于：v20.4
返回一个包含来自 JSON 对象键和值的元组数组。所有值都表示为未解析的字符串。
语法
JSONExtractKeysAndValuesRaw(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
返回一个包含解析后的键值对的数组，其中值是未解析的字符串。 Array(Tuple(String, String))
示例
使用示例
SELECT JSONExtractKeysAndValuesRaw('{"a": [-100, 200.0], "b": "hello"}') AS res;
┌─res──────────────────────────────────┐
│ [('a','[-100,200.0]'),('b','"hello"')] │
└──────────────────────────────────────┘
JSONExtractKeysAndValuesRawCaseInsensitive
引入于: v25.8
使用不区分大小写的键匹配从 JSON 中提取原始键值对。此函数类似于 JSONExtractKeysAndValuesRaw。
语法
JSONExtractKeysAndValuesRawCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回包含键值对的原始字符串的元组数组。 Array(Tuple(String, String))
示例
基本
SELECT JSONExtractKeysAndValuesRawCaseInsensitive('{"Name": "Alice", "AGE": 30}')
[('Name','"Alice"'),('AGE','30')]
引入于: v25.8
解析 JSON 字符串并使用不区分大小写的键匹配提取键，以导航到嵌套对象。此函数类似于 JSONExtractKeys。
语法
JSONExtractKeysCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回 JSON 对象中的键数组。 Array(String)
示例
基本
SELECT JSONExtractKeysCaseInsensitive('{"Name": "Alice", "AGE": 30}')
嵌套
SELECT JSONExtractKeysCaseInsensitive('{"User": {"name": "John", "AGE": 25}}', 'user')
引入于: v20.1
以未解析的字符串形式返回 JSON 的一部分。
语法
JSONExtractRaw(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
返回 JSON 的一部分作为未解析的字符串。如果该部分不存在或类型错误，将返回一个空字符串。 String
示例
使用示例
SELECT JSONExtractRaw('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') AS res;
┌─res──────────────┐
│ [-100,200.0,300] │
└──────────────────┘
引入于: v25.8
使用不区分大小写的键匹配以未解析的字符串形式返回 JSON 的一部分。此函数类似于 JSONExtractRaw。
语法
JSONExtractRawCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取元素的原始 JSON 字符串。 String
示例
object
SELECT JSONExtractRawCaseInsensitive('{"Object": {"key": "value"}}', 'OBJECT')
引入于: v20.1
解析 JSON 并提取字符串类型的值。
语法
JSONExtractString(json[, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
如果存在该值，则返回一个字符串，否则返回一个空字符串。 String
示例
使用示例
SELECT JSONExtractString('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') AS res;
┌─res───┐
│ hello │
└───────┘
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取字符串。此函数类似于 JSONExtractString。
语法
JSONExtractStringCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的字符串值，如果未找到则返回空字符串。 String
示例
基本
SELECT JSONExtractStringCaseInsensitive('{"ABC": "def"}', 'abc')
嵌套
SELECT JSONExtractStringCaseInsensitive('{"User": {"Name": "John"}}', 'user', 'name')
引入于: v20.1
解析 JSON 并提取 UInt 类型的值。
语法
JSONExtractUInt(json [, indices_or_keys, ...])
参数
json — 要解析的 JSON 字符串。 Stringindices_or_keys — 一个列表，其中包含零个或多个参数，每个参数可以是字符串或整数。 String 或 (U)Int*
返回值
如果存在该值，则返回一个 UInt 值，否则返回 0。 UInt64
示例
使用示例
SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;
引入于: v25.8
解析 JSON 并使用不区分大小写的键匹配提取 UInt 类型的值。此函数类似于 JSONExtractUInt。
语法
JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的 UInt 值，如果未找到或无法转换则返回 0。 UInt64
示例
基本
SELECT JSONExtractUIntCaseInsensitive('{"COUNT": 789}', 'count')
JSONHas
引入于: v20.1
检查提供的值是否存在于 JSON 文档中。
语法
JSONHas(json[ ,indices_or_keys, ...])
参数
返回值
如果该值存在于 json 中，则返回 1，否则返回 0 UInt8
示例
使用示例
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 1;
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 4) = 0;
JSONLength
引入于: v20.1
返回 JSON 数组或 JSON 对象的长度。如果该值不存在或类型错误，将返回 0。
语法
JSONLength(json [, indices_or_keys, ...])
参数
返回值
返回 JSON 数组或 JSON 对象的长度，否则如果该值不存在或类型错误，则返回 0。 UInt64
示例
使用示例
SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 3;
SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}') = 2;
JSONMergePatch
引入于：v23.10
返回通过合并多个 JSON 对象形成的合并后的 JSON 对象字符串。
语法
jsonMergePatch(json1[, json2, ...])
别名: jsonMergePatch
参数
json1[, json2, ...] — 一个或多个包含有效 JSON 的字符串。 String
返回值
如果 JSON 对象字符串有效，则返回合并后的 JSON 对象字符串。 String
示例
使用示例
SELECT jsonMergePatch('{"a":1}', '{"name": "joey"}', '{"name": "tom"}', '{"name": "zoey"}') AS res;
┌─res───────────────────┐
│ {"a":1,"name":"zoey"} │
└───────────────────────┘
JSONSharedDataPaths
引入于：v24.8
返回存储在 JSON 列中的共享数据结构中的路径列表。
语法
JSONSharedDataPaths(json)
参数
返回值
返回存储在 JSON 列中的共享数据结构中的路径数组。 Array(String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONSharedDataPaths(json) FROM test;
┌─json─────────────────────────────────┬─JSONSharedDataPaths(json)─┐
│ {"a":"42"} │ [] │
│ {"b":"Hello"} │ ['b'] │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['c'] │
└──────────────────────────────────────┴───────────────────────────┘
JSONSharedDataPathsWithTypes
引入于：v24.8
返回存储在共享数据结构中及其在 JSON 列的每一行中的类型的路径列表。
语法
JSONSharedDataPathsWithTypes(json)
参数
返回值
返回存储在共享数据结构中的路径及其数据类型的映射。 Map(String, String)
示例
使用示例
CREATE TABLE test (json JSON(max_dynamic_paths=1)) ENGINE = Memory;
INSERT INTO test FORMAT JSONEachRow {"json" : {"a" : 42}}, {"json" : {"b" : "Hello"}}, {"json" : {"a" : [1, 2, 3], "c" : "2020-01-01"}}
SELECT json, JSONSharedDataPathsWithTypes(json) FROM test;
┌─json─────────────────────────────────┬─JSONSharedDataPathsWithTypes(json)─┐
│ {"a":"42"} │ {} │
│ {"b":"Hello"} │ {'b':'String'} │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'c':'Date'} │
└──────────────────────────────────────┴─────────────────────────────────────┘
JSONType
引入于: v20.1
返回 JSON 值的类型。如果该值不存在，将返回 Null=0。
语法
JSONType(json[, indices_or_keys, ...])
参数
返回值
返回 JSON 值的类型作为字符串，否则如果该值不存在，则返回 Null=0 Enum
示例
使用示例
SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}') = 'Object';
SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') = 'String';
SELECT JSONType('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 'Array';
JSON_EXISTS
引入于: v21.8
如果 JSON 文档中存在该值，则返回 1。如果该值不存在，则返回 0。
语法
参数
返回值
如果 JSON 文档中存在该值，则返回 1，否则返回 0。 UInt8
示例
使用示例
SELECT JSON_EXISTS('{"hello":1}', '$.hello');
SELECT JSON_EXISTS('{"hello":{"world":1}}', '$.hello.world');
SELECT JSON_EXISTS('{"hello":["world"]}', '$.hello[*]');
SELECT JSON_EXISTS('{"hello":["world"]}', '$.hello[0]');
┌─JSON_EXISTS(⋯ '$.hello')─┐
│ 1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯llo.world')─┐
│ 1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[*]')─┐
│ 1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[0]')─┐
│ 1 │
└──────────────────────────┘
JSON_QUERY
引入于: v21.8
解析 JSON 并提取一个值作为 JSON 数组或 JSON 对象。如果该值不存在，将返回一个空字符串。
语法
参数
返回值
返回提取的 JSON 数组或 JSON 对象作为字符串，或者如果该值不存在则返回一个空字符串。 String
示例
使用示例
SELECT JSON_QUERY('{"hello":"world"}', '$.hello');
SELECT JSON_QUERY('{"array":[[0, 1, 2, 3, 4, 5], [0, -1, -2, -3, -4, -5]]}', '$.array[*][0 to 2, 4]');
SELECT JSON_QUERY('{"hello":2}', '$.hello');
SELECT toTypeName(JSON_QUERY('{"hello":2}', '$.hello'));
["world"]
[0, 1, 4, 0, -1, -4]
[2]
String
JSON_VALUE
引入于：v21.11
解析 JSON 并提取一个值作为 JSON 标量。默认情况下，如果该值不存在，将返回一个空字符串。
此函数受以下设置控制
- 通过设置
function_json_value_return_type_allow_nullable = true，将返回 NULL。如果该值是复杂类型（例如：结构体、数组、映射），则默认返回一个空字符串。
- 通过设置
function_json_value_return_type_allow_complex = true，将返回复杂值。
语法
参数
返回值
返回提取的 JSON 标量作为字符串，或者如果该值不存在则返回一个空字符串。 String
示例
使用示例
SELECT JSON_VALUE('{"hello":"world"}', '$.hello');
SELECT JSON_VALUE('{"array":[[0, 1, 2, 3, 4, 5], [0, -1, -2, -3, -4, -5]]}', '$.array[*][0 to 2, 4]');
SELECT JSON_VALUE('{"hello":2}', '$.hello');
SELECT JSON_VALUE('{"hello":"world"}', '$.b') settings function_json_value_return_type_allow_nullable=true;
dynamicElement
引入版本: v24.1
从 Dynamic 列中提取指定类型的列。
此函数允许您从 Dynamic 列中提取特定类型的值。如果某行包含请求类型的值，则返回该值。如果该行包含不同的类型或 NULL，则返回标量类型的 NULL 或数组类型的空数组。
语法
dynamicElement(dynamic, type_name)
参数
dynamic — 要提取的 Dynamic 列。 Dynamictype_name — 要提取的变体类型的名称（例如，'String'、'Int64'、'Array(Int64)'）。
返回值
返回从 Dynamic 列中提取的指定类型的值。对于不匹配的类型（或数组类型的空数组），返回 NULL。 Any
示例
从 Dynamic 列中提取不同类型
CREATE TABLE test (d Dynamic) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, dynamicType(d), dynamicElement(d, 'String'), dynamicElement(d, 'Int64'), dynamicElement(d, 'Array(Int64)'), dynamicElement(d, 'Date'), dynamicElement(d, 'Array(String)') FROM test
┌─d─────────────┬─dynamicType(d)─┬─dynamicElement(d, 'String')─┬─dynamicElement(d, 'Int64')─┬─dynamicElement(d, 'Array(Int64)')─┬─dynamicElement(d, 'Date')─┬─dynamicElement(d, 'Array(String)')─┐
│ ᴺᵁᴸᴸ │ None │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [] │ ᴺᵁᴸᴸ │ [] │
│ 42 │ Int64 │ ᴺᵁᴸᴸ │ 42 │ [] │ ᴺᵁᴸᴸ │ [] │
│ Hello, World! │ String │ Hello, World! │ ᴺᵁᴸᴸ │ [] │ ᴺᵁᴸᴸ │ [] │
│ [1,2,3] │ Array(Int64) │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [1,2,3] │ ᴺᵁᴸᴸ │ [] │
└───────────────┴────────────────┴─────────────────────────────┴────────────────────────────┴───────────────────────────────────┴───────────────────────────┴────────────────────────────────────┘
dynamicType
引入版本: v24.1
返回 Dynamic 列的每一行的变体类型名称。
对于包含 NULL 的行，该函数返回 'None'。对于所有其他行，它返回存储在该 Dynamic 列的行中的实际数据类型（例如，'Int64'、'String'、'Array(Int64)'）。
语法
参数
返回值
返回存储在每一行中的值的类型名称，或者对于 NULL 值返回 'None'。 String
示例
检查 Dynamic 列中的类型
CREATE TABLE test (d Dynamic) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, dynamicType(d) FROM test;
┌─d─────────────┬─dynamicType(d)─┐
│ ᴺᵁᴸᴸ │ None │
│ 42 │ Int64 │
│ Hello, World! │ String │
│ [1,2,3] │ Array(Int64) │
└───────────────┴────────────────┘
isDynamicElementInSharedData
引入版本: v24.1
返回 Dynamic 列中存储在共享变体格式而不是作为单独子列中的行的 true。
当 Dynamic 列具有 max_types 限制时，超过此限制的值存储在共享二进制格式中，而不是分成单独的类型化子列。此函数标识哪些行存储在此共享格式中。
语法
isDynamicElementInSharedData(dynamic)
参数
返回值
如果该值存储在共享变体格式中，则返回 true，如果存储为单独的子列或为 NULL，则返回 false。 Bool
示例
检查具有 max_types 限制的 Dynamic 列中的存储格式
CREATE TABLE test (d Dynamic(max_types=2)) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, isDynamicElementInSharedData(d) FROM test;
┌─d─────────────┬─isDynamicElementInSharedData(d)─┐
│ ᴺᵁᴸᴸ │ false │
│ 42 │ false │
│ Hello, World! │ true │
│ [1,2,3] │ true │
└───────────────┴─────────────────────────────────┘
isValidJSON
引入于: v20.1
检查传递的字符串是否为有效的 JSON。
语法
参数
返回值
如果字符串是有效的 JSON，则返回 1，否则返回 0。 UInt8
示例
使用示例
SELECT isValidJSON('{"a": "hello", "b": [-100, 200.0, 300]}') = 1;
SELECT isValidJSON('not JSON') = 0;
使用整数访问 JSON 数组和 JSON 对象
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 0);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 1);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 2);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', -1);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', -2);
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 3);
引入于：v21.4
解析字段 field_name 的值中的 true/false 值。结果是 UInt8。
语法
simpleJSONExtractBool(json, field_name)
别名: visitParamExtractBool
参数
返回值
如果字段的值为 true，则返回 1，否则返回 0。这意味着此函数将在以下情况下返回 0（包括但不限于）
- 如果字段不存在。
- 如果字段包含
true 作为字符串，例如：{"field":"true"}。
- 如果字段包含
1 作为数值。 UInt8
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":false,"bar":true}');
INSERT INTO jsons VALUES ('{"foo":"true","qux":1}');
SELECT simpleJSONExtractBool(json, 'bar') FROM jsons ORDER BY json;
SELECT simpleJSONExtractBool(json, 'foo') FROM jsons ORDER BY json;
引入于：v21.4
从字段 field_name 的值中解析 Float64。如果 field_name 是字符串字段，它会尝试从字符串的开头解析一个数字。如果该字段不存在，或者存在但包含的不是数字，则返回 0。
语法
simpleJSONExtractFloat(json, field_name)
别名: visitParamExtractFloat
参数
返回值
如果该字段存在且包含一个数字，则返回从该字段解析的数字，否则返回 0。 Float64
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');
SELECT simpleJSONExtractFloat(json, 'foo') FROM jsons ORDER BY json;
引入于：v21.4
解析名为 field_name 的字段的值中的 Int64。如果 field_name 是字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或者存在但包含的不是数字，则返回 0。
语法
simpleJSONExtractInt(json, field_name)
别名: visitParamExtractInt
参数
返回值
如果字段存在且包含数字，则返回从字段解析的数字，否则返回 0 Int64
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');
SELECT simpleJSONExtractInt(json, 'foo') FROM jsons ORDER BY json;
引入于：v21.4
将名为 field_name 的字段的值作为 String 返回，包括分隔符。
语法
simpleJSONExtractRaw(json, field_name)
别名: visitParamExtractRaw
参数
返回值
如果字段存在，则返回包含分隔符的字段值作为字符串，否则返回空字符串 String
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"-4e3"}');
INSERT INTO jsons VALUES ('{"foo":-3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":{"def":[1,2,3]}}');
INSERT INTO jsons VALUES ('{"baz":2}');
SELECT simpleJSONExtractRaw(json, 'foo') FROM jsons ORDER BY json;
"-4e3"
-3.4
5
{"def":[1,2,3]}
引入于：v21.4
从名为 field_name 的字段的值中解析 String，用双引号括起来。
实现细节
目前不支持格式为 \uXXXX\uYYYY 的代码点，这些代码点不属于基本多语言平面（它们会被转换为 CESU-8 而不是 UTF-8）。
语法
simpleJSONExtractString(json, field_name)
别名: visitParamExtractString
参数
返回值
返回字段的未转义值作为字符串，包括分隔符。如果字段不包含双引号字符串，或者反转义失败，或者字段不存在，则返回空字符串 String
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"\\n\\u0000"}');
INSERT INTO jsons VALUES ('{"foo":"\\u263"}');
INSERT INTO jsons VALUES ('{"foo":"\\u263a"}');
INSERT INTO jsons VALUES ('{"foo":"hello}');
SELECT simpleJSONExtractString(json, 'foo') FROM jsons ORDER BY json;
引入于：v21.4
从名为 field_name 的字段的值中解析 UInt64。如果 field_name 是字符串字段，它会尝试从字符串的开头解析一个数字。如果字段不存在，或者存在但包含的不是数字，则返回 0。
语法
simpleJSONExtractUInt(json, field_name)
别名: visitParamExtractUInt
参数
返回值
如果字段存在且包含数字，则返回从字段解析的数字，否则返回 0 UInt64
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"4e3"}');
INSERT INTO jsons VALUES ('{"foo":3.4}');
INSERT INTO jsons VALUES ('{"foo":5}');
INSERT INTO jsons VALUES ('{"foo":"not1number"}');
INSERT INTO jsons VALUES ('{"baz":2}');
SELECT simpleJSONExtractUInt(json, 'foo') FROM jsons ORDER BY json;
simpleJSONHas
引入于：v21.4
检查是否存在名为 field_name 的字段。
语法
simpleJSONHas(json, field_name)
别名: visitParamHas
参数
返回值
如果字段存在，则返回 1，否则返回 0 UInt8
示例
使用示例
CREATE TABLE jsons
(
`json` String
)
ENGINE = MergeTree
ORDER BY tuple();
INSERT INTO jsons VALUES ('{"foo":"true","qux":1}');
SELECT simpleJSONHas(json, 'foo') FROM jsons;
SELECT simpleJSONHas(json, 'bar') FROM jsons;
toJSONString
引入于: v21.7
将值序列化为其 JSON 表示形式。支持各种数据类型和嵌套结构。64 位 整数 或更大的整数（例如 UInt64 或 Int128）默认情况下用引号括起来。 output_format_json_quote_64bit_integers 控制此行为。特殊值 NaN 和 inf 被替换为 null。启用 output_format_json_quote_denormals 设置以显示它们。在序列化 Enum 值时，该函数输出其名称。
参见
语法
参数
value — 要序列化的值。值可以是任何数据类型。 Any
返回值
返回值的 JSON 表示形式。 String
示例
Map 序列化
SELECT toJSONString(map('key1', 1, 'key2', 2));
┌─toJSONString(map('key1', 1, 'key2', 2))─┐
│ {"key1":1,"key2":2} │
└─────────────────────────────────────────┘
特殊值
SELECT toJSONString(tuple(1.25, NULL, NaN, +inf, -inf, [])) SETTINGS output_format_json_quote_denormals = 1;
┌─toJSONString(tuple(1.25, NULL, NaN, plus(inf), minus(inf), []))─┐
│ [1.25,null,"nan","inf","-inf",[]] │
└─────────────────────────────────────────────────────────────────┘
