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 数组元素组成的字符串数组。如果相应部分不是数组或不存在，则返回空数组。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, ...])
参数
返回值
如果存在则返回 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, ...])
参数
返回值
如果存在则返回 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]...)
参数
返回值
返回提取到的浮点数值，若未找到或无法转换则返回 0。Float64
示例
基本示例
SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')
首次引入于：v20.1
解析 JSON 并提取 Int 类型的值。
语法
JSONExtractInt(json[, indices_or_keys, ...])
参数
返回值
如果对应值存在则返回整型值，否则返回 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 对象键的数组。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, ...])
参数
返回值
返回一个包含已解析键值对的元组数组，其中各值为未进一步解析的字符串。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]...)
参数
json — 要解析的 JSON 字符串 Stringindices_or_keys — 可选。用于定位到目标对象的索引或键。键不区分大小写进行匹配，可为 String 或 (U)Int*
返回值
返回一个由元组组成的数组，每个元组包含一组键值对的原始字符串形式。Array(Tuple(String, String))
示例
基础用法
SELECT JSONExtractKeysAndValuesRawCaseInsensitive('{"Name": "Alice", "AGE": 30}')
[('Name','"Alice"'),('AGE','30')]
引入版本：v25.8
解析 JSON 字符串，并通过不区分大小写的键匹配导航到嵌套对象，从中提取键。此函数类似于 JSONExtractKeys。
语法
JSONExtractKeysCaseInsensitive(json [, indices_or_keys]...)
参数
json — 要解析的 JSON 字符串 Stringindices_or_keys — 可选。用于导航到目标对象的索引或键。键进行不区分大小写的匹配，可为 String 或 (U)Int*
返回值
返回 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 中对应部分的原始未解析字符串。如果该部分不存在或类型不匹配，则返回空字符串。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 并提取 String 类型的值。
语法
JSONExtractString(json[, indices_or_keys, ...])
参数
返回值
如果存在则返回一个 String 类型的值，否则返回空字符串。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, ...])
参数
返回值
如果对应值存在则返回一个 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)
参数
返回值
返回一个映射，内容为存储在共享的数据结构中的路径及其在 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 标量返回。如果该值不存在，默认返回空字符串。
此函数受以下设置控制：
- 通过 SET
function_json_value_return_type_allow_nullable = true 时，将返回 NULL。如果该值是复杂类型（例如：struct、array、map），则默认返回空字符串。
- 通过 SET
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)
参数
返回值
如果值以 shared variant 格式存储，则返回 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",[]] │
└─────────────────────────────────────────────────────────────────┘
