JSON 函数

JSON 函数的类型

有两组函数用于解析 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 在字符串字面量之外不包含空格字符。

JSONExtract 函数

这些函数基于 simdjson，专为更复杂的 JSON 解析需求而设计。

不区分大小写的 JSONExtract 函数

这些函数在从 JSON 对象中提取值时执行 ASCII 不区分大小写的键匹配。它们的工作方式与区分大小写的对应函数相同，只是对象键的匹配不区分大小写。当多个键以不同大小写匹配时，返回第一个匹配项。

注意

这些函数的性能可能低于其区分大小写的对应函数，因此如果可能，请使用常规 JSONExtract 函数。

JSONAllPaths

引入版本：v24.8

返回 JSON 列中每行存储的所有路径列表。

语法

JSONAllPaths(json)

参数

json — JSON 列。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 — JSON 列。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。

语法

JSONArrayLength(json)

别名:JSON_ARRAY_LENGTH

参数

json — 有效的 JSON 字符串。String

返回值

如果 json 是有效的 JSON 数组字符串,则返回数组元素的数量,否则返回 NULL。Nullable(UInt64)

示例

使用示例

SELECT
    JSONArrayLength(''),
    JSONArrayLength('[1,2,3]');

┌─JSONArrayLength('')─┬─JSONArrayLength('[1,2,3]')─┐
│                ᴺᵁᴸᴸ │                          3 │
└─────────────────────┴────────────────────────────┘

JSONDynamicPaths

引入版本:v24.8

返回 JSON 列中作为独立子列存储的动态路径列表。

语法

JSONDynamicPaths(json)

参数

json — JSON 列。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 — JSON 列。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))'}  │
└──────────────────────────────────────┴─────────────────────────────────┘

JSONExtract

引入版本: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])         │
└──────────────────────────────────┘

JSONExtractArrayRaw

引入版本:v20.1

返回一个数组,其中包含 JSON 数组的元素,每个元素以未解析的字符串形式表示。

语法

JSONExtractArrayRaw(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_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"']   │
└──────────────────────────────┘

JSONExtractArrayRawCaseInsensitive

引入版本：v25.8

返回一个数组，包含 JSON 数组的各个元素，每个元素以未解析的字符串形式表示，使用不区分大小写的键匹配方式。此函数类似于 JSONExtractArrayRaw。

语法

JSONExtractArrayRawCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标数组的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回原始 JSON 字符串数组。Array(String)

示例

基础示例

SELECT JSONExtractArrayRawCaseInsensitive('{"Items": [1, 2, 3]}', 'ITEMS')

['1','2','3']

JSONExtractBool

引入版本:v20.1

解析 JSON 并提取布尔类型的值。

语法

JSONExtractBool(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数列表,每个参数可以是字符串或整数。String 或 (U)Int*

返回值

如果值存在则返回布尔值,否则返回 0。Bool

示例

使用示例

SELECT JSONExtractBool('{"passed": true}', 'passed') AS res;

┌─res─┐
│   1 │
└─────┘

JSONExtractBoolCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配方式提取布尔值。此函数与 JSONExtractBool 类似。

语法

JSONExtractBoolCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取的布尔值(true 为 1,false 为 0),未找到时返回 0。UInt8

示例

基础示例

SELECT JSONExtractBoolCaseInsensitive('{"IsActive": true}', 'isactive')

JSONExtractCaseInsensitive

引入版本: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

示例

整数类型

SELECT JSONExtractCaseInsensitive('{"Number": 123}', 'number', 'Int32')

数组类型

SELECT JSONExtractCaseInsensitive('{"List": [1, 2, 3]}', 'list', 'Array(Int32)')

[1,2,3]

JSONExtractFloat

引入版本:v20.1

解析 JSON 并提取浮点类型的值。

语法

JSONExtractFloat(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数的列表,每个参数可以是字符串或整数。String 或 (U)Int*

返回值

如果值存在则返回浮点值,否则返回 0。Float64

示例

使用示例

SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;

┌─res─┐
│ 200 │
└─────┘

JSONExtractFloatCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配方式提取 Float 类型的值。该函数类似于 JSONExtractFloat。

语法

JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取的 Float 值,若未找到或无法转换则返回 0。Float64

示例

基础示例

SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')

12.34

JSONExtractInt

引入版本:v20.1

解析 JSON 并提取 Int 类型的值。

语法

JSONExtractInt(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数的列表,每个参数可以是字符串或整数。String 或 (U)Int*

返回值

如果值存在则返回 Int 值,否则返回 0。Int64

示例

使用示例

SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;

┌─res─┐
│ 200 │
└─────┘

JSONExtractIntCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配方式提取 Int 类型的值。此函数与 JSONExtractInt 类似。

语法

JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取的 Int 值,若未找到或无法转换则返回 0。Int64

示例

基础用法

SELECT JSONExtractIntCaseInsensitive('{"Value": 123}', 'value')

嵌套结构

SELECT JSONExtractIntCaseInsensitive('{"DATA": {"COUNT": 42}}', 'data', 'Count')

JSONExtractKeys

引入版本:v21.11

解析 JSON 字符串并提取键。

语法

JSONExtractKeys(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_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, 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, ...])

参数

json — 要解析的 JSON 字符串。String
indices_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]...)

参数

json — 要解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到对象的索引或键。键使用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回包含键值对的元组数组，键值对以原始字符串形式表示。Array(Tuple(String, String))

示例

基础示例

SELECT JSONExtractKeysAndValuesRawCaseInsensitive('{"Name": "Alice", "AGE": 30}')

[('Name','"Alice"'),('AGE','30')]

JSONExtractKeysCaseInsensitive

引入版本：v25.8

解析 JSON 字符串并使用不区分大小写的键匹配提取键，以导航到嵌套对象。此函数类似于 JSONExtractKeys。

语法

JSONExtractKeysCaseInsensitive(json [, indices_or_keys]...)

参数

json — 要解析的 JSON 字符串 String
indices_or_keys — 可选。用于导航到对象的索引或键。键使用不区分大小写匹配 String 或 (U)Int*

返回值

返回 JSON 对象的键数组。Array(String)

示例

基础示例

SELECT JSONExtractKeysCaseInsensitive('{"Name": "Alice", "AGE": 30}')

['Name','AGE']

嵌套示例

SELECT JSONExtractKeysCaseInsensitive('{"User": {"name": "John", "AGE": 25}}', 'user')

['name','AGE']

JSONExtractRaw

引入版本：v20.1

以未解析的字符串形式返回 JSON 的一部分。

语法

JSONExtractRaw(json[, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数的列表，每个参数可以是字符串或整数。String 或 (U)Int*

返回值

以未解析的字符串形式返回 JSON 的部分内容。如果该部分不存在或类型错误，将返回空字符串。String

示例

使用示例

SELECT JSONExtractRaw('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') AS res;

┌─res──────────────┐
│ [-100,200.0,300] │
└──────────────────┘

JSONExtractRawCaseInsensitive

引入版本：v25.8

使用不区分大小写的键匹配方式返回 JSON 的一部分作为未解析的字符串。此函数类似于 JSONExtractRaw。

语法

JSONExtractRawCaseInsensitive(json [, indices_or_keys]...)

参数

json — 要解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取元素的原始 JSON 字符串。String

示例

对象

SELECT JSONExtractRawCaseInsensitive('{"Object": {"key": "value"}}', 'OBJECT')

{"key":"value"}

JSONExtractString

引入版本:v20.1

解析 JSON 并提取字符串类型的值。

语法

JSONExtractString(json[, indices_or_keys, ...])

参数

json — 待解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数组成的列表,每个参数可以是字符串或整数。String 或 (U)Int*

返回值

如果值存在,则返回字符串值;否则返回空字符串。String

示例

使用示例

SELECT JSONExtractString('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') AS res;

┌─res───┐
│ hello │
└───────┘

JSONExtractStringCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配方式提取字符串。此函数与 JSONExtractString 类似。

语法

JSONExtractStringCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取的字符串值,若未找到则返回空字符串。String

示例

基础用法

SELECT JSONExtractStringCaseInsensitive('{"ABC": "def"}', 'abc')

def

嵌套结构

SELECT JSONExtractStringCaseInsensitive('{"User": {"Name": "John"}}', 'user', 'name')

John

JSONExtractUInt

引入版本：v20.1

解析 JSON 并提取 UInt 类型的值。

语法

JSONExtractUInt(json [, indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串。String
indices_or_keys — 零个或多个参数的列表，每个参数可以是字符串或整数。String 或 (U)Int*

返回值

如果值存在则返回 UInt 值，否则返回 0。UInt64

示例

使用示例

SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;

┌─res─┐
│ 300 │
└─────┘

JSONExtractUIntCaseInsensitive

引入版本：v25.8

解析 JSON 并使用不区分大小写的键匹配方式提取 UInt 类型的值。此函数类似于 JSONExtractUInt。

语法

JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)

参数

json — 待解析的 JSON 字符串 String
indices_or_keys — 可选参数。用于导航到目标字段的索引或键。键采用不区分大小写的匹配方式 String 或 (U)Int*

返回值

返回提取的 UInt 值，如果未找到或无法转换则返回 0。UInt64

示例

基础用法

SELECT JSONExtractUIntCaseInsensitive('{"COUNT": 789}', 'count')

JSONHas

引入版本：v20.1

检查 JSON 文档中是否存在指定的值。

语法

JSONHas(json[ ,indices_or_keys, ...])

参数

json — 要解析的 JSON 字符串 String
[ ,indices_or_keys, ...] — 零个或多个参数列表。String 或 (U)Int*

返回值

如果值存在于 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;

1
0

JSONLength

引入版本:v20.1

返回 JSON 数组或 JSON 对象的长度。如果值不存在或类型错误,将返回 0。

语法

JSONLength(json [, indices_or_keys, ...])

参数

json — 待解析的 JSON 字符串 String
[, indices_or_keys, ...] — 可选参数。零个或多个参数列表。String 或 (U)Int8/16/32/64

返回值

返回 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;

1
1

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 — JSON 列。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 — JSON 列。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 — 要解析的 JSON 字符串 String
json[, indices_or_keys, ...] — 零个或多个参数列表,每个参数可以是字符串或整数。String 或 (U)Int8/16/32/64

返回值

以字符串形式返回 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';

1
1
1

JSON_EXISTS

引入版本：v21.8

如果 JSON 文档中存在该值，则返回 1。如果该值不存在，则返回 0。

语法

JSON_EXISTS(json, path)

参数

json — 有效的 JSON 字符串。String
path — 表示路径的字符串。String

返回值

如果 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_QUERY(json, path)

参数

json — 包含有效 JSON 的字符串。String
path — 表示路径的字符串。String

返回值

以字符串形式返回提取的 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。如果值为复杂类型(如:struct、array、map),默认返回空字符串。
设置 function_json_value_return_type_allow_complex = true 时,将返回复杂值。

语法

JSON_VALUE(json, path)

参数

json — 包含有效 JSON 的字符串。String
path — 表示路径的字符串。String

返回值

以字符串形式返回提取的 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;

world
0
2
ᴺᵁᴸᴸ

dynamicElement

引入版本：v24.1

从 Dynamic 列中提取指定类型的列。

此函数用于从 Dynamic 列中提取特定类型的值。如果某行包含所请求类型的值，则返回该值。如果该行包含不同类型或 NULL，则对标量类型返回 NULL，对数组类型返回空数组。

语法

dynamicElement(dynamic, type_name)

参数

dynamic — 要提取的 Dynamic 列。Dynamic
type_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)')。

语法

dynamicType(dynamic)

参数

dynamic — 要检查的 Dynamic 列。Dynamic

返回值

返回每一行中存储值的类型名称,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)

参数

dynamic — 要检查的 Dynamic 列。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。

语法

isValidJSON(json)

参数

json — 待验证的 JSON 字符串 String

返回值

如果字符串为有效 JSON 则返回 1,否则返回 0。UInt8

示例

使用示例

SELECT isValidJSON('{"a": "hello", "b": [-100, 200.0, 300]}') = 1;
SELECT isValidJSON('not JSON') = 0;

1
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);

simpleJSONExtractBool

引入版本:v21.4

从名为 field_name 的字段值中解析 true/false 值。返回结果为 UInt8 类型。

语法

simpleJSONExtractBool(json, field_name)

别名:visitParamExtractBool

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段的值为 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;

simpleJSONExtractFloat

引入版本:v21.4

从名为 field_name 的字段值中解析 Float64。如果 field_name 是字符串字段,则尝试从字符串开头解析数字。如果该字段不存在,或虽然存在但不包含数字,则返回 0。

语法

simpleJSONExtractFloat(json, field_name)

别名:visitParamExtractFloat

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段存在且包含数字,则返回从该字段解析出的数字,否则返回 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;

simpleJSONExtractInt

引入版本：v21.4

从名为 field_name 的字段值中解析 Int64。如果 field_name 是字符串字段，则尝试从字符串开头解析数字。如果该字段不存在，或者存在但不包含数字，则返回 0。

语法

simpleJSONExtractInt(json, field_name)

别名：visitParamExtractInt

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段存在且包含数字，则返回从该字段解析出的数字，否则返回 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;

simpleJSONExtractRaw

引入版本:v21.4

返回名为 field_name 的字段值,以 String 类型返回,包括分隔符。

语法

simpleJSONExtractRaw(json, field_name)

别名:visitParamExtractRaw

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段存在,返回该字段的字符串值(包括分隔符),否则返回空字符串 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]}

simpleJSONExtractString

引入版本：v21.4

从名为 field_name 的字段值中解析双引号内的 String。

实现细节

目前不支持非基本多文种平面的 \uXXXX\uYYYY 格式码点(它们会被转换为 CESU-8 而非 UTF-8)。

语法

simpleJSONExtractString(json, field_name)

别名：visitParamExtractString

参数

json — 要在其中搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

返回字段的未转义值(字符串类型),包括分隔符。如果字段不包含双引号字符串、反转义失败或字段不存在,则返回空字符串。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;

\n\0

☺

simpleJSONExtractUInt

引入版本:v21.4

从名为 field_name 的字段值中解析 UInt64。如果 field_name 是字符串字段,则尝试从字符串开头解析数字。如果该字段不存在,或虽然存在但不包含数字,则返回 0。

语法

simpleJSONExtractUInt(json, field_name)

别名: visitParamExtractUInt

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段存在且包含数字,则返回从该字段解析出的数字,否则返回 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

参数

json — 要搜索字段的 JSON。String
field_name — 要搜索的字段名称。const String

返回值

如果字段存在则返回 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;

1
0

toJSONString

引入版本:v21.7

将值序列化为 JSON 表示形式。支持各种数据类型和嵌套结构。默认情况下,64 位整数或更大的整数(如 UInt64 或 Int128)会用引号括起来。output_format_json_quote_64bit_integers 控制此行为。特殊值 NaN 和 inf 会被替换为 null。启用 output_format_json_quote_denormals 设置可显示它们。在序列化 Enum 值时,该函数输出其名称。

另请参阅:

语法

toJSONString(value)

参数

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",[]]                               │
└─────────────────────────────────────────────────────────────────┘

JSON 函数的类型​

simpleJSON (visitParam) 函数​

JSONExtract 函数​

不区分大小写的 JSONExtract 函数​

JSONAllPaths​

JSONAllPathsWithTypes​

JSONArrayLength​

JSONDynamicPaths​

JSONDynamicPathsWithTypes​

JSONExtract​

JSONExtractArrayRaw​

JSONExtractArrayRawCaseInsensitive​

JSONExtractBool​

JSONExtractBoolCaseInsensitive​

JSONExtractCaseInsensitive​

JSONExtractFloat​

JSONExtractFloatCaseInsensitive​

JSONExtractInt​

JSONExtractIntCaseInsensitive​

JSONExtractKeys​

JSONExtractKeysAndValues​

JSONExtractKeysAndValuesCaseInsensitive​

JSONExtractKeysAndValuesRaw​

JSONExtractKeysAndValuesRawCaseInsensitive​

JSONExtractKeysCaseInsensitive​

JSONExtractRaw​

JSONExtractRawCaseInsensitive​

JSONExtractString​

JSONExtractStringCaseInsensitive​

JSONExtractUInt​

JSONExtractUIntCaseInsensitive​

JSONHas​

JSONLength​

JSONMergePatch​

JSONSharedDataPaths​

JSONSharedDataPathsWithTypes​

JSONType​

JSON_EXISTS​

JSON_QUERY​

JSON_VALUE​

dynamicElement​

dynamicType​

isDynamicElementInSharedData​

isValidJSON​

simpleJSONExtractBool​

simpleJSONExtractFloat​

simpleJSONExtractInt​

simpleJSONExtractRaw​

simpleJSONExtractString​

simpleJSONExtractUInt​

simpleJSONHas​

toJSONString​

JSON 函数的类型

simpleJSON (visitParam) 函数

JSONExtract 函数

不区分大小写的 JSONExtract 函数

JSONAllPaths

JSONAllPathsWithTypes

JSONArrayLength

JSONDynamicPaths

JSONDynamicPathsWithTypes

JSONExtract

JSONExtractArrayRaw

JSONExtractArrayRawCaseInsensitive

JSONExtractBool

JSONExtractBoolCaseInsensitive

JSONExtractCaseInsensitive

JSONExtractFloat

JSONExtractFloatCaseInsensitive

JSONExtractInt

JSONExtractIntCaseInsensitive

JSONExtractKeys

JSONExtractKeysAndValues

JSONExtractKeysAndValuesCaseInsensitive

JSONExtractKeysAndValuesRaw

JSONExtractKeysAndValuesRawCaseInsensitive

JSONExtractKeysCaseInsensitive

JSONExtractRaw

JSONExtractRawCaseInsensitive

JSONExtractString

JSONExtractStringCaseInsensitive

JSONExtractUInt

JSONExtractUIntCaseInsensitive

JSONHas

JSONLength

JSONMergePatch

JSONSharedDataPaths

JSONSharedDataPathsWithTypes

JSONType

JSON_EXISTS

JSON_QUERY

JSON_VALUE

dynamicElement

dynamicType

isDynamicElementInSharedData

isValidJSON

simpleJSONExtractBool

simpleJSONExtractFloat

simpleJSONExtractInt

simpleJSONExtractRaw

simpleJSONExtractString

simpleJSONExtractUInt

simpleJSONHas

toJSONString