跳到主要内容
跳到主要内容

JSON 函数

JSON 函数类型

有两组函数用于解析 JSON:

simpleJSON(visitParam)函数

ClickHouse 提供了用于处理简化 JSON 的特殊函数。所有这些 JSON 函数都基于强假设,假设 JSON 的内容是特定的。它们尽量以最小的操作完成任务,以最快的速度完成工作。

以下假设成立:

  1. 字段名(函数参数)必须是常量。
  2. 字段名在 JSON 中以某种方式标准化编码。例如:simpleJSONHas('{"abc":"def"}', 'abc') = 1,但是 simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0
  3. 在任何嵌套级别上搜索字段,不加区分。如果有多个匹配字段,则使用第一个出现的字段。
  4. 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 — 有效 JSON 的字符串。 String

返回值

如果 json 是有效的 JSON 数组字符串,则返回数组元素的数量;否则返回 NULLNullable(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*

返回值

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

示例

用法示例

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*

返回值

返回提取的布尔值(1 表示真,0 表示假),如果未找到则返回 0。 UInt8

示例

基本

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

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

示例

int_type

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

array_type

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*

返回值

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

示例

用法示例

SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;
┌─res─┐
│ 200 │
└─────┘

JSONExtractFloatCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配提取浮点值。此函数与 JSONExtractFloat 类似。

语法

JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)

参数

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

返回值

返回提取的浮点值,如果未找到或无法转换则返回 0。 Float64

示例

基本

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

JSONExtractInt

引入版本:v20.1

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

语法

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

参数

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

返回值

如果存在,返回整型值;否则返回 0Int64

示例

用法示例

SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;
┌─res─┐
│ 200 │
└─────┘

JSONExtractIntCaseInsensitive

引入版本:v25.8

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

语法

JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)

参数

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

返回值

返回提取的整型值,如果未找到或无法转换则返回 0。 Int64

示例

基本

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

嵌套

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

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 并提取无符号整型类型的值。

语法

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

参数

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

返回值

如果存在,返回无符号整型值;否则返回 0UInt64

示例

用法示例

SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;
┌─res─┐
│ 300 │
└─────┘

JSONExtractUIntCaseInsensitive

引入版本:v25.8

解析 JSON 并使用不区分大小写的键匹配提取无符号整型类型的值。此函数与 JSONExtractUInt 类似。

语法

JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)

参数

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

返回值

返回提取的无符号整型值,如果未找到或无法转换则返回 0。 UInt64

示例

基本

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

JSONHas

引入版本:v20.1

检查 JSON 文档中是否存在提供的值。

语法

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

参数

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

返回值

如果在 json 中存在该值,则返回 1;否则返回 0UInt8

示例

用法示例

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 对象的长度;否则,如果值不存在或类型错误,则返回 0UInt64

示例

用法示例

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, ...])

参数

  • 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=0Enum

示例

用法示例

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;否则返回 0UInt8

示例

用法示例

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。如果值为复杂类型(如:结构、数组、映射),则默认返回空字符串。
  • 通过设置 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

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

语法

dynamicType(dynamic)

参数

  • 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

引入版本:v

返回在动态列中不分解为子列并以内存共享变体的二进制形式存储的行的真假值。

语法

isDynamicElementInSharedData(dynamic)

参数

  • 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;否则返回 0UInt8

示例

用法示例

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

simpleJSONExtractBool

引入版本:v21.4

从名为 field_name 的字段中解析真/假值。 结果为 UInt8

语法

simpleJSONExtractBool(json, field_name)

参数

  • 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;
0
1
0
0

simpleJSONExtractFloat

引入于: v21.4

从名为 field_name 的字段值中解析 Float64。 如果 field_name 是字符串字段,它会尝试从字符串的开头解析一个数字。 如果字段不存在,或者存在但不包含数字,它将返回 0

语法

simpleJSONExtractFloat(json, field_name)

参数

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

返回值

如果字段存在且包含数字,则返回从字段解析的数字,否则返回 0Float64

示例

使用示例

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;
0
-4000
0
-3.4
5

simpleJSONExtractInt

引入于: v21.4

从名为 field_name 的字段值中解析 Int64。 如果 field_name 是字符串字段,它会尝试从字符串的开头解析一个数字。 如果字段不存在,或者存在但不包含数字,它将返回 0

语法

simpleJSONExtractInt(json, field_name)

参数

  • 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;
0
-4
0
-3
5

simpleJSONExtractRaw

引入于: v21.4

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

语法

simpleJSONExtractRaw(json, field_name)

参数

  • 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)

参数

  • 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)

参数

  • 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;
0
4
0
3
5

simpleJSONHas

引入于: v21.4

检查是否存在名为 field_name 的字段。

语法

simpleJSONHas(json, field_name)

参数

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

返回值

如果字段存在,则返回 1,否则返回 0UInt8

示例

使用示例

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 位 整数 或更大(如 UInt64Int128)默认用引号括起来。output_format_json_quote_64bit_integers 控制此行为。 特殊值 NaNinf 被替换为 null。启用 output_format_json_quote_denormals 设置以显示它们。 序列化 Enum 值时,函数输出其名称。

另请参见:

语法

toJSONString(value)

参数

  • 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'。

语法

variantType(variant)

参数

  • variant — Variant 列

返回值

示例

示例

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)  │
└────────────────┘