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
是有效的 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, return_type[, indices_or_keys, ...])
参数
json
— 要解析的 JSON 字符串。 String
return_type
— 要返回的 ClickHouse 数据类型。 String
indices_or_keys
— 一组零个或多个参数,每个参数可以是字符串或整数。 String
或 (U)Int*
返回值
如果可能,返回指定 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 并提取布尔类型的值。
语法
JSONExtractBool(json[, indices_or_keys, ...])
参数
返回值
如果存在,返回布尔值;否则返回 0
。 Bool
示例
用法示例
SELECT JSONExtractBool('{"passed": true}', 'passed') AS res;
引入版本:v25.8
解析 JSON 并使用不区分大小写的键匹配提取布尔值。此函数与 JSONExtractBool
类似。
语法
JSONExtractBoolCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的布尔值(1 表示真,0 表示假),如果未找到则返回 0。 UInt8
示例
基本
SELECT JSONExtractBoolCaseInsensitive('{"IsActive": true}', 'isactive')
引入版本:v25.8
解析 JSON 并使用不区分大小写的键匹配提取给定 ClickHouse 数据类型的值。此函数与 JSONExtract
类似。
语法
JSONExtractCaseInsensitive(json [, indices_or_keys...], return_type)
参数
json
— 要解析的 JSON 字符串 String
indices_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 并提取浮点类型的值。
语法
JSONExtractFloat(json[, indices_or_keys, ...])
参数
返回值
如果存在,返回浮点值;否则返回 0
。 Float64
示例
用法示例
SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;
引入版本:v25.8
解析 JSON 并使用不区分大小写的键匹配提取浮点值。此函数与 JSONExtractFloat
类似。
语法
JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的浮点值,如果未找到或无法转换则返回 0。 Float64
示例
基本
SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')
引入版本:v20.1
解析 JSON 并提取整型类型的值。
语法
JSONExtractInt(json[, indices_or_keys, ...])
参数
返回值
如果存在,返回整型值;否则返回 0
。 Int64
示例
用法示例
SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;
引入版本:v25.8
解析 JSON 并使用不区分大小写的键匹配提取整型类型的值。此函数与 JSONExtractInt
类似。
语法
JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的整型值,如果未找到或无法转换则返回 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, value_type[, indices_or_keys, ...])
参数
json
— 要解析的 JSON 字符串。 String
value_type
— 值的 ClickHouse 数据类型。 String
indices_or_keys
— 一组零个或多个参数,每个参数可以是字符串或整数。 String
或 (U)Int*
返回值
返回解析的键值对的元组数组。 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 字符串 String
indices_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]...)
参数
返回值
返回包含原始字符串形式的键值对的元组数组。 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 的部分。如果部分不存在或类型错误,则返回空字符串。 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
示例
对象
SELECT JSONExtractRawCaseInsensitive('{"Object": {"key": "value"}}', 'OBJECT')
引入版本:v20.1
解析 JSON 并提取字符串类型的值。
语法
JSONExtractString(json[, indices_or_keys, ...])
参数
返回值
如果存在,返回字符串类型的值;否则返回空字符串。 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 并提取无符号整型类型的值。
语法
JSONExtractUInt(json [, indices_or_keys, ...])
参数
返回值
如果存在,返回无符号整型值;否则返回 0
。 UInt64
示例
用法示例
SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;
引入版本:v25.8
解析 JSON 并使用不区分大小写的键匹配提取无符号整型类型的值。此函数与 JSONExtractUInt
类似。
语法
JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)
参数
返回值
返回提取的无符号整型值,如果未找到或无法转换则返回 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, ...])
参数
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 标量。如果值不存在,则默认返回空字符串。
此函数受以下设置控制:
- 通过设置
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
引入版本:v
从 Dynamic
列中提取指定类型的列。
语法
dynamicElement(dynamic, type_name)
参数
dynamic
— 动态列 - type_name
— 要提取的变体类型的名称
返回值
示例
示例
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
引入版本:v
返回 Dynamic
列每行的变体类型名称。如果行包含 NULL,则返回 'None'。
语法
参数
返回值
示例
示例
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
引入版本:v
返回在动态列中不分解为子列并以内存共享变体的二进制形式存储的行的真假值。
语法
isDynamicElementInSharedData(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
的字段中解析真/假值。
结果为 UInt8
。
语法
simpleJSONExtractBool(json, field_name)
参数
返回值
如果字段的值为 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)
参数
返回值
如果字段存在且包含数字,则返回从字段解析的数字,否则返回 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)
参数
返回值
如果字段存在且包含数字,则返回从字段解析的数字,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)
参数
返回值
如果字段存在,则返回字段的值作为字符串,包括分隔符,否则返回空字符串。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)
参数
返回值
返回字段的未转义值作为字符串,包括分隔符。如果字段不包含双引号字符串,或者未转义失败,或者字段不存在,则返回空字符串。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)
参数
返回值
如果字段存在且包含数字,则返回从字段解析的数字,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)
参数
返回值
如果字段存在,则返回 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
示例
映射序列化
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",[]] │
└─────────────────────────────────────────────────────────────────┘
variantElement
引入于: v
从 Variant
列中提取指定类型的列。
语法
variantElement(variant, type_name, [, default_value])
参数
variant
— Variant 列
type_name
— 要提取的变体类型的名称
default_value
— 如果变体没有具有指定类型的变体,将使用的默认值。可以是任何类型。可选
返回值
示例
示例
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;
┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [] │
│ 42 │ ᴺᵁᴸᴸ │ 42 │ [] │
│ Hello, World! │ Hello, World! │ ᴺᵁᴸᴸ │ [] │
│ [1,2,3] │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [1,2,3] │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
variantType
引入于: v
返回每行 Variant
列的变体类型名称。如果行包含 NULL,则为其返回 'None'。
语法
参数
返回值
示例
示例
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;
┌─variantType(v)─┐
│ None │
│ UInt64 │
│ String │
│ Array(UInt64) │
└────────────────┘