> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-3a82795f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> JSON 函数文档

# JSON 函数

<div id="types-of-functions">
  ## JSON 函数的类型
</div>

有两类用于解析 JSON 的函数：

* [`simpleJSON*` (`visitParam*`)](#simplejson-visitparam-functions)，用于以极高速度解析受限的 JSON 子集。
* [`JSONExtract*`](#jsonextract-functions)，用于解析常规 JSON。

<div id="simplejson-visitparam-functions">
  ### simpleJSON (visitParam) 函数
</div>

ClickHouse 提供了一组用于处理简化 JSON 的特殊函数。所有这些 JSON 函数都建立在对 JSON 形式的严格假设之上。它们会尽量少做处理，以便尽可能快地完成任务。

具体假设如下：

1. 字段名 (函数参数) 必须是常量。
2. 字段名在 JSON 中必须采用某种规范编码形式。例如：`simpleJSONHas('{"abc":"def"}', 'abc') = 1`，但 `simpleJSONHas('{"\\u0061\\u0062\\u0063":"def"}', 'abc') = 0`
3. 会在任意嵌套层级中搜索字段，不区分层级。如果存在多个匹配字段，则使用第一次出现的字段。
4. JSON 在字符串字面量之外不能包含空格字符。

<div id="jsonextract-functions">
  ### JSONExtract 函数
</div>

这些函数基于 [simdjson](https://github.com/lemire/simdjson) 实现，适用于更复杂的 JSON 解析场景。

<div id="case-insensitive-jsonextract-functions">
  ### 不区分大小写的 JSONExtract 函数
</div>

这些函数在从 JSON 对象中提取值时执行 ASCII 不区分大小写的键名匹配。
它们的行为与对应的区分大小写版本完全一致，唯一的区别是匹配对象键名时不考虑大小写。
当多个仅大小写不同的键都能匹配时，将返回第一个匹配项。

<Note>
  这些函数的性能可能不如对应的区分大小写版本，因此如无必要，建议使用常规的 JSONExtract 函数。
</Note>

{/*AUTOGENERATED_START*/}

<div id="JSONAllPaths">
  ## JSONAllPaths
</div>

引入版本：v24.8.0

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

**语法**

```sql theme={null}
JSONAllPaths(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回由 JSON 列中所有路径组成的数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONAllPaths(json)─┐
│ {"a":"42"}                           │ ['a']              │
│ {"b":"Hello"}                        │ ['b']              │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a','c']          │
└──────────────────────────────────────┴────────────────────┘
```

<div id="JSONAllPathsWithTypes">
  ## JSONAllPathsWithTypes
</div>

引入版本：v24.8.0

返回 JSON 列中每一行存储的所有路径及其数据类型列表。

**语法**

```sql theme={null}
JSONAllPathsWithTypes(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回 JSON 列中所有路径及其数据类型的映射。[`Map(String, String)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─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'} │
└──────────────────────────────────────┴───────────────────────────────────────────┘
```

<div id="JSONAllValues">
  ## JSONAllValues
</div>

首次引入于：v26.4.0

以字符串数组的形式返回 JSON 列中每一行的所有值。
这些值会按其文本表示形式进行序列化，并按路径名称排序。

**语法**

```sql theme={null}
JSONAllValues(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回 JSON 列中所有值组成的 String 数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
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, JSONAllValues(json) FROM test;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONAllValues(json)──────┐
│ {"a":42}                             │ ['42']                   │
│ {"b":"Hello"}                        │ ['Hello']                │
│ {"a":[1,2,3],"c":"2020-01-01"}       │ ['[1,2,3]','2020-01-01'] │
└──────────────────────────────────────┴──────────────────────────┘
```

<div id="JSONArrayLength">
  ## JSONArrayLength
</div>

引入版本：v23.2.0

返回最外层 JSON 数组中的元素数量。
如果输入的 JSON 字符串无效，该函数将返回 `NULL`。

**语法**

```sql theme={null}
JSONArrayLength(json)
```

**别名**: `JSON_ARRAY_LENGTH`

**参数**

* `json` — 有效 JSON 的 String。[`String`](/zh/reference/data-types/string)

**返回值**

如果 `json` 是有效的 JSON 数组 字符串，则返回数组元素个数；否则返回 `NULL`。[`Nullable(UInt64)`](/zh/reference/data-types/nullable)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT
    JSONArrayLength(''),
    JSONArrayLength('[1,2,3]');
```

```response title=Response theme={null}
┌─JSONArrayLength('')─┬─JSONArrayLength('[1,2,3]')─┐
│                ᴺᵁᴸᴸ │                          3 │
└─────────────────────┴────────────────────────────┘
```

<div id="JSONDynamicPaths">
  ## JSONDynamicPaths
</div>

引入版本：v24.8.0

返回以单独子列形式存储在 JSON 列中的动态路径列表。

**语法**

```sql theme={null}
JSONDynamicPaths(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回由 JSON 列中的动态路径组成的数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONDynamicPaths(json)─┐
│ {"a":"42"}                           │ ['a']                  │
│ {"b":"Hello"}                        │ []                     │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['a']                  │
└──────────────────────────────────────┴────────────────────────┘
```

<div id="JSONDynamicPathsWithTypes">
  ## JSONDynamicPathsWithTypes
</div>

引入版本：v24.8.0

返回 JSON 列中以独立子列形式存储的动态路径列表，以及它们在每一行中的类型。

**语法**

```sql theme={null}
JSONDynamicPathsWithTypes(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回 JSON 列中动态路径及其数据类型的映射。[`Map(String, String)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONDynamicPathsWithTypes(json)─┐
│ {"a":"42"}                           │ {'a':'Int64'}                   │
│ {"b":"Hello"}                        │ {}                              │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'a':'Array(Nullable(Int64))'}  │
└──────────────────────────────────────┴─────────────────────────────────┘
```

<div id="JSONExtract">
  ## JSONExtract
</div>

引入版本：v19.14.0

解析 JSON，并提取指定 ClickHouse 数据类型的值。

**语法**

```sql theme={null}
JSONExtract(json[, indices_or_keys, ...], return_type)
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `return_type` — 要返回的 ClickHouse 数据类型。[`String`](/zh/reference/data-types/string)

**返回值**

如果可以，返回指定的 ClickHouse 数据类型的值；否则返回该类型的默认值。

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtract('{"a": "hello", "b": [-100, 200.0, 300]}', 'Tuple(String, Array(Float64))') AS res;
```

```response title=Response theme={null}
┌─res──────────────────────────────┐
│ ('hello',[-100,200,300])         │
└──────────────────────────────────┘
```

<div id="JSONExtractArrayRaw">
  ## JSONExtractArrayRaw
</div>

引入于：v20.1.0

返回一个数组，其中包含 JSON 数组 的各个元素，每个元素都表示为未解析字符串。

**语法**

```sql theme={null}
JSONExtractArrayRaw(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数构成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回由 JSON 数组元素组成的字符串数组。如果对应部分不是数组或不存在，则返回空数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractArrayRaw('{"a": "hello", "b": [-100, 200.0, "hello"]}', 'b') AS res;
```

```response title=Response theme={null}
┌─res──────────────────────────┐
│ ['-100','200.0','"hello"']   │
└──────────────────────────────┘
```

<div id="JSONExtractArrayRawCaseInsensitive">
  ## JSONExtractArrayRawCaseInsensitive
</div>

引入版本：v25.8.0

使用不区分大小写的键名匹配，返回一个 JSON 数组，其中每个元素都表示为未解析的字符串。此函数与 [`JSONExtractArrayRaw`](#JSONExtractArrayRaw) 类似。

**语法**

```sql theme={null}
JSONExtractArrayRawCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位数组中的索引或键。键匹配不区分大小写 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回由原始 JSON 字符串组成的数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**基本**

```sql title=Query theme={null}
SELECT JSONExtractArrayRawCaseInsensitive('{"Items": [1, 2, 3]}', 'ITEMS')
```

```response title=Response theme={null}
['1','2','3']
```

<div id="JSONExtractBool">
  ## JSONExtractBool
</div>

自 v20.1.0 起引入

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

**语法**

```sql theme={null}
JSONExtractBool(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果存在，则返回 Bool 值；否则返回 `0`。[`Bool`](/zh/reference/data-types/boolean)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractBool('{"passed": true}', 'passed') AS res;
```

```response title=Response theme={null}
┌─res─┐
│   1 │
└─────┘
```

<div id="JSONExtractBoolCaseInsensitive">
  ## JSONExtractBoolCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取布尔值。该函数与 [`JSONExtractBool`](#JSONExtractBool) 类似。

**语法**

```sql theme={null}
JSONExtractBoolCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位字段的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的布尔值 (`true` 为 1，`false` 为 0) ；如果未找到，则返回 0。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractBoolCaseInsensitive('{"IsActive": true}', 'isactive')
```

```response title=Response theme={null}
1
```

<div id="JSONExtractCaseInsensitive">
  ## JSONExtractCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取指定 ClickHouse 数据类型的值。该函数类似于 [`JSONExtract`](#JSONExtract)。

**语法**

```sql theme={null}
JSONExtractCaseInsensitive(json [, indices_or_keys...], return_type)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键采用不区分大小写的匹配方式 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `return_type` — 要提取的 ClickHouse 数据类型 [`String`](/zh/reference/data-types/string)

**返回值**

返回以指定数据类型表示的提取值。[`Any`](/zh/reference/data-types)

**示例**

**int\_type**

```sql title=Query theme={null}
SELECT JSONExtractCaseInsensitive('{"Number": 123}', 'number', 'Int32')
```

```response title=Response theme={null}
123
```

**array\_type**

```sql title=Query theme={null}
SELECT JSONExtractCaseInsensitive('{"List": [1, 2, 3]}', 'list', 'Array(Int32)')
```

```response title=Response theme={null}
[1,2,3]
```

<div id="JSONExtractFloat">
  ## JSONExtractFloat
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
JSONExtractFloat(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果存在，则返回 Float 值；否则返回 `0`。[`Float64`](/zh/reference/data-types/float)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONExtractFloat('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 2) AS res;
```

```response title=Response theme={null}
┌─res─┐
│ 200 │
└─────┘
```

<div id="JSONExtractFloatCaseInsensitive">
  ## JSONExtractFloatCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取 Float 类型的值。该函数与 [`JSONExtractFloat`](#JSONExtractFloat) 类似。

**语法**

```sql theme={null}
JSONExtractFloatCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键名匹配时不区分大小写 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的浮点值；如果未找到或无法转换，则返回 0。 [`Float64`](/zh/reference/data-types/float)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractFloatCaseInsensitive('{"Price": 12.34}', 'PRICE')
```

```response title=Response theme={null}
12.34
```

<div id="JSONExtractInt">
  ## JSONExtractInt
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
JSONExtractInt(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果该值存在，则返回 Int 值；否则返回 `0`。[`Int64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 1) AS res;
```

```response title=Response theme={null}
┌──res─┐
│ -100 │
└──────┘
```

<div id="JSONExtractIntCaseInsensitive">
  ## JSONExtractIntCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取 Int 类型的值。此函数与 [`JSONExtractInt`](#JSONExtractInt) 类似。

**语法**

```sql theme={null}
JSONExtractIntCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的 Int 值；如果未找到或无法转换，则返回 0。[`Int64`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractIntCaseInsensitive('{"Value": 123}', 'value')
```

```response title=Response theme={null}
123
```

**嵌套**

```sql title=Query theme={null}
SELECT JSONExtractIntCaseInsensitive('{"DATA": {"COUNT": 42}}', 'data', 'Count')
```

```response title=Response theme={null}
42
```

<div id="JSONExtractKeys">
  ## JSONExtractKeys
</div>

自 v21.11.0 引入

解析 JSON 字符串并提取键名。

**语法**

```sql theme={null}
JSONExtractKeys(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个包含 JSON 对象键的数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONExtractKeys('{"a": "hello", "b": [-100, 200.0, 300]}') AS res;
```

```response title=Response theme={null}
┌─res─────────┐
│ ['a','b']   │
└─────────────┘
```

<div id="JSONExtractKeysAndValues">
  ## JSONExtractKeysAndValues
</div>

引入版本：v20.1.0

从 JSON 中解析键值对，其中值的类型为指定的 ClickHouse 数据类型。

**语法**

```sql theme={null}
JSONExtractKeysAndValues(json[, indices_or_keys, ...], value_type)
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `value_type` — 值的 ClickHouse 数据类型。[`String`](/zh/reference/data-types/string)

**返回值**

返回由已解析键值对组成的Tuple数组。[`Array(Tuple(String, value_type))`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractKeysAndValues('{"x": {"a": 5, "b": 7, "c": 11}}', 'Int8', 'x') AS res;
```

```response title=Response theme={null}
┌─res────────────────────┐
│ [('a',5),('b',7),('c',11)] │
└────────────────────────┘
```

<div id="JSONExtractKeysAndValuesCaseInsensitive">
  ## JSONExtractKeysAndValuesCaseInsensitive
</div>

引入版本：v25.8.0

通过不区分大小写的键名匹配从 JSON 中解析键值对。此函数与 [`JSONExtractKeysAndValues`](#JSONExtractKeysAndValues) 类似。

**语法**

```sql theme={null}
JSONExtractKeysAndValuesCaseInsensitive(json [, indices_or_keys...], value_type)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到对象的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)
* `value_type` — 值的 ClickHouse 数据类型 [`String`](/zh/reference/data-types/string)

**返回值**

返回一个包含键值对的 Tuple 数组。[`Array(Tuple(String, T))`](/zh/reference/data-types/array)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractKeysAndValuesCaseInsensitive('{"Name": "Alice", "AGE": 30}', 'String')
```

```response title=Response theme={null}
[('Name','Alice'),('AGE','30')]
```

<div id="JSONExtractKeysAndValuesRaw">
  ## JSONExtractKeysAndValuesRaw
</div>

引入版本：v20.4.0

返回一个数组，其中包含 JSON 对象中的键和值组成的元组。所有值都以未解析的字符串形式表示。

**语法**

```sql theme={null}
JSONExtractKeysAndValuesRaw(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个包含已解析键值对的 Tuple 数组，其中值为未解析的字符串。[`Array(Tuple(String, String))`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractKeysAndValuesRaw('{"a": [-100, 200.0], "b": "hello"}') AS res;
```

```response title=Response theme={null}
┌─res──────────────────────────────────┐
│ [('a','[-100,200.0]'),('b','"hello"')] │
└──────────────────────────────────────┘
```

<div id="JSONExtractKeysAndValuesRawCaseInsensitive">
  ## JSONExtractKeysAndValuesRawCaseInsensitive
</div>

引入版本：v25.8.0

使用不区分大小写的键名匹配，从 JSON 中提取原始键值对。此函数与 [`JSONExtractKeysAndValuesRaw`](#JSONExtractKeysAndValuesRaw) 类似。

**语法**

```sql theme={null}
JSONExtractKeysAndValuesRawCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该对象的索引或键。键采用不区分大小写的匹配方式 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个 Tuple 数组，其中包含以原始字符串形式表示的键值对。[`Array(Tuple(String, String))`](/zh/reference/data-types/array)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractKeysAndValuesRawCaseInsensitive('{"Name": "Alice", "AGE": 30}')
```

```response title=Response theme={null}
[('Name','"Alice"'),('AGE','30')]
```

<div id="JSONExtractKeysCaseInsensitive">
  ## JSONExtractKeysCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON 字符串，并通过不区分大小写的键名匹配访问嵌套对象并提取键。此函数类似于 [`JSONExtractKeys`](#JSONExtractKeys)。

**语法**

```sql theme={null}
JSONExtractKeysCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该对象的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 JSON 对象 中键组成的数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractKeysCaseInsensitive('{"Name": "Alice", "AGE": 30}')
```

```response title=Response theme={null}
['Name','AGE']
```

**嵌套**

```sql title=Query theme={null}
SELECT JSONExtractKeysCaseInsensitive('{"User": {"name": "John", "AGE": 25}}', 'user')
```

```response title=Response theme={null}
['name','AGE']
```

<div id="JSONExtractRaw">
  ## JSONExtractRaw
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
JSONExtractRaw(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 JSON 中指定部分的未解析字符串。如果该部分不存在或类型不正确，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONExtractRaw('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') AS res;
```

```response title=Response theme={null}
┌─res──────────────┐
│ [-100,200.0,300] │
└──────────────────┘
```

<div id="JSONExtractRawCaseInsensitive">
  ## JSONExtractRawCaseInsensitive
</div>

发布于：v25.8.0

使用不区分大小写的键名匹配，将 JSON 的一部分以未解析字符串的形式返回。此函数与 [`JSONExtractRaw`](#JSONExtractRaw) 类似。

**语法**

```sql theme={null}
JSONExtractRawCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键采用不区分大小写的匹配方式 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的元素的原始 JSON 字符串。[`String`](/zh/reference/data-types/string)

**示例**

**object**

```sql title=Query theme={null}
SELECT JSONExtractRawCaseInsensitive('{"Object": {"key": "value"}}', 'OBJECT')
```

```response title=Response theme={null}
{"key":"value"}
```

<div id="JSONExtractString">
  ## JSONExtractString
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
JSONExtractString(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果该值存在，则返回 String 值；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONExtractString('{"a": "hello", "b": [-100, 200.0, 300]}', 'a') AS res;
```

```response title=Response theme={null}
┌─res───┐
│ hello │
└───────┘
```

<div id="JSONExtractStringCaseInsensitive">
  ## JSONExtractStringCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取字符串。此函数与 [`JSONExtractString`](#JSONExtractString) 类似。

**语法**

```sql theme={null}
JSONExtractStringCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的字符串值；如果未找到，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractStringCaseInsensitive('{"ABC": "def"}', 'abc')
```

```response title=Response theme={null}
def
```

**嵌套**

```sql title=Query theme={null}
SELECT JSONExtractStringCaseInsensitive('{"User": {"Name": "John"}}', 'user', 'name')
```

```response title=Response theme={null}
John
```

<div id="JSONExtractUInt">
  ## JSONExtractUInt
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
JSONExtractUInt(json [, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果存在，则返回一个 UInt 值；否则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONExtractUInt('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', -1) AS res;
```

```response title=Response theme={null}
┌─res─┐
│ 300 │
└─────┘
```

<div id="JSONExtractUIntCaseInsensitive">
  ## JSONExtractUIntCaseInsensitive
</div>

引入版本：v25.8.0

解析 JSON，并通过不区分大小写的键名匹配提取 UInt 类型的值。该函数与 [`JSONExtractUInt`](#JSONExtractUInt) 类似。

**语法**

```sql theme={null}
JSONExtractUIntCaseInsensitive(json [, indices_or_keys]...)
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选。用于定位到该字段的索引或键。键按不区分大小写的方式匹配 [`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回提取出的 UInt 值；如果未找到或无法转换，则返回 0。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**基本用法**

```sql title=Query theme={null}
SELECT JSONExtractUIntCaseInsensitive('{"COUNT": 789}', 'count')
```

```response title=Response theme={null}
789
```

<div id="JSONHas">
  ## JSONHas
</div>

引入于版本：v20.1.0

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

**语法**

```sql theme={null}
JSONHas(json[ ,indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `[ ,indices_or_keys, ...]` — 由零个或多个参数组成的列表。[`String`](/zh/reference/data-types/string) 或 [`(U)Int*`](/zh/reference/data-types/int-uint)

**返回值**

如果值存在于 `json` 中，则返回 `1`；否则返回 `0` [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 1;
SELECT JSONHas('{"a": "hello", "b": [-100, 200.0, 300]}', 'b', 4) = 0;
```

```response title=Response theme={null}
1
0
```

<div id="JSONKey">
  ## JSONKey
</div>

引入版本：v20.1.0

返回 JSON 对象中指定索引 (从 1 开始) 处字段的键。如果 JSON 以字符串形式传入，则会先进行解析。第二个参数是用于访问嵌套对象的 JSON path。该函数返回指定位置的键名。

**语法**

```sql theme={null}
JSONKey(json[, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串。[`String`](/zh/reference/data-types/string)
* `indices_or_keys` — 可选的索引或键列表，用于指定嵌套元素的路径。每个参数都可以是字符串 (通过键访问) 或整数 (通过从 1 开始的索引访问) 。[`String`](/zh/reference/data-types/string) 或 [`Int*`](/zh/reference/data-types/int-uint)

**返回值**

返回 JSON 对象中指定位置的键名。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONKey('{"a": "hello", "b": [-100, 200.0, 300]}', 1);
```

```response title=Response theme={null}
a
```

<div id="JSONLength">
  ## JSONLength
</div>

引入版本：v20.1.0

返回 JSON 数组或 JSON 对象的长度。
如果该值不存在或类型不正确，则返回 `0`。

**语法**

```sql theme={null}
JSONLength(json [, indices_or_keys, ...])
```

**参数**

* `json` — 要解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `[, indices_or_keys, ...]` — 可选。由零个或多个参数组成的列表。[`String`](/zh/reference/data-types/string) 或 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回 JSON 数组或 JSON 对象的长度；如果该值不存在或类型不正确，则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}', 'b') = 3;
SELECT JSONLength('{"a": "hello", "b": [-100, 200.0, 300]}') = 2;
```

```response title=Response theme={null}
1
1
```

<div id="JSONMergePatch">
  ## JSONMergePatch
</div>

引入版本：v23.10.0

返回通过合并多个 JSON 对象生成的合并后 JSON 对象字符串。

**语法**

```sql theme={null}
JSONMergePatch(json1[, json2, ...])
```

**别名**: `jsonMergePatch`

**参数**

* `json1[, json2, ...]` — 一个或多个有效的 JSON 字符串。[`String`](/zh/reference/data-types/string)

**返回值**

如果 JSON 对象字符串有效，则返回合并后的 JSON 对象字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT JSONMergePatch('{"a":1}', '{"name": "joey"}', '{"name": "tom"}', '{"name": "zoey"}') AS res;
```

```response title=Response theme={null}
┌─res───────────────────┐
│ {"a":1,"name":"zoey"} │
└───────────────────────┘
```

<div id="JSONSharedDataPaths">
  ## JSONSharedDataPaths
</div>

引入版本：v24.8.0

返回存储在 JSON 列共享数据结构中的路径列表。

**语法**

```sql theme={null}
JSONSharedDataPaths(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回 JSON 列中存储在共享数据结构中的路径数组。[`Array(String)`](/zh/reference/data-types/array)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONSharedDataPaths(json)─┐
│ {"a":"42"}                           │ []                        │
│ {"b":"Hello"}                        │ ['b']                     │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ ['c']                     │
└──────────────────────────────────────┴───────────────────────────┘
```

<div id="JSONSharedDataPathsWithTypes">
  ## JSONSharedDataPathsWithTypes
</div>

引入版本：v24.8.0

返回 JSON 列中每一行存储在共享数据结构中的路径及其类型列表。

**语法**

```sql theme={null}
JSONSharedDataPathsWithTypes(json)
```

**参数**

* `json` — JSON 列。[`JSON`](/zh/reference/data-types/newjson)

**返回值**

返回一个映射，包含存储在共享数据结构中的路径及其在 JSON 列中的数据类型。[`Map(String, String)`](/zh/reference/data-types/map)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─json─────────────────────────────────┬─JSONSharedDataPathsWithTypes(json)─┐
│ {"a":"42"}                           │ {}                                  │
│ {"b":"Hello"}                        │ {'b':'String'}                      │
│ {"a":["1","2","3"],"c":"2020-01-01"} │ {'c':'Date'}                        │
└──────────────────────────────────────┴─────────────────────────────────────┘
```

<div id="JSONType">
  ## JSONType
</div>

引入版本：v20.1.0

返回 JSON 值的类型。如果该值不存在，则返回 `Null=0`。

**语法**

```sql theme={null}
JSONType(json[, indices_or_keys, ...])
```

**参数**

* `json` — 待解析的 JSON 字符串 [`String`](/zh/reference/data-types/string)
* `json[, indices_or_keys, ...]` — 由零个或多个参数组成的列表，其中每个参数都可以是字符串或整数。[`String`](/zh/reference/data-types/string) 或 [`(U)Int8/16/32/64`](/zh/reference/data-types/int-uint)

**返回值**

返回 JSON 值的类型 (以字符串形式表示) ；如果该值不存在，则返回 `Null=0` [`枚举`](/zh/reference/data-types/enum)

**示例**

**使用示例**

```sql title=Query theme={null}
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';
```

```response title=Response theme={null}
1
1
1
```

<div id="JSON_EXISTS">
  ## JSON\_EXISTS
</div>

引入版本：v21.8.0

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

**语法**

```sql theme={null}
JSON_EXISTS(json, path)
```

**参数**

* `json` — 包含有效 JSON 的字符串。[`String`](/zh/reference/data-types/string)
* `path` — 表示路径的字符串。[`String`](/zh/reference/data-types/string)

**返回值**

如果该值在 JSON 文档中存在，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
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]');
```

```response title=Response theme={null}
┌─JSON_EXISTS(⋯ '$.hello')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯llo.world')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[*]')─┐
│                        1 │
└──────────────────────────┘
┌─JSON_EXISTS(⋯.hello[0]')─┐
│                        1 │
└──────────────────────────┘
```

<div id="JSON_QUERY">
  ## JSON\_QUERY
</div>

引入版本：v21.8.0

解析 JSON，并将某个值提取为 JSON 数组或 JSON 对象。
如果该值不存在，则返回空字符串。

**语法**

```sql theme={null}
JSON_QUERY(json, path)
```

**参数**

* `json` — 包含有效 JSON 的字符串。[`String`](/zh/reference/data-types/string)
* `path` — 表示路径的字符串。[`String`](/zh/reference/data-types/string)

**返回值**

返回提取出的 JSON 数组或 JSON 对象字符串；如果该值不存在，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
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'));
```

```response title=Response theme={null}
["world"]
[0, 1, 4, 0, -1, -4]
[2]
String
```

<div id="JSON_VALUE">
  ## JSON\_VALUE
</div>

引入版本：v21.11.0

解析 JSON，并提取其中的一个值作为 JSON 标量。如果该值不存在，默认返回空字符串。

此函数的行为由以下设置控制：

* 通过 SET `function_json_value_return_type_allow_nullable` = `true`，将返回 `NULL`。如果该值为复杂类型 (例如：struct、array、map) ，默认将返回空字符串。
* 通过 SET `function_json_value_return_type_allow_complex` = `true`，将返回该复杂值。

**语法**

```sql theme={null}
JSON_VALUE(json, path)
```

**参数**

* `json` — 包含有效 JSON 的字符串。[`String`](/zh/reference/data-types/string)
* `path` — 表示路径的字符串。[`String`](/zh/reference/data-types/string)

**返回值**

返回提取出的 JSON 标量字符串；如果该值不存在，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
world
0
2
ᴺᵁᴸᴸ
```

<div id="dynamicElement">
  ## dynamicElement
</div>

引入版本：v24.1.0

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

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

**语法**

```sql theme={null}
dynamicElement(dynamic, type_name)
```

**参数**

* `dynamic` — 要从中提取值的 Dynamic 列。[`Dynamic`](/zh/reference/data-types/dynamic)
* `type_name` — 要提取的 Variant 类型名称 (例如 'String'、'Int64'、'Array(Int64)') 。

**返回值**

返回 Dynamic 列中指定类型的值。对于类型不匹配的情况，返回 NULL (数组类型则返回空数组) 。[`Any`](/zh/reference/data-types)

**示例**

**从 Dynamic 列提取不同类型**

```sql title=Query theme={null}
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
```

```response title=Response theme={null}
┌─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]                           │                      ᴺᵁᴸᴸ │ []                                 │
└───────────────┴────────────────┴─────────────────────────────┴────────────────────────────┴───────────────────────────────────┴───────────────────────────┴────────────────────────────────────┘
```

<div id="dynamicType">
  ## dynamicType
</div>

Introduced in: v24.1.0

返回 `Dynamic` 列中每一行对应的 Variant 类型名称。

对于包含 NULL 的行，该函数返回 'None'。对于其他所有行，它返回存储在该行 Dynamic 列中的实际数据类型
(例如 'Int64'、'String'、'Array(Int64)') 。

**Syntax**

```sql theme={null}
dynamicType(dynamic)
```

**参数**

* `dynamic` — 要检查的 Dynamic 列。[`Dynamic`](/zh/reference/data-types/dynamic)

**返回值**

返回每一行中存储的值的类型名称；对于 NULL 值，返回 'None'。[`String`](/zh/reference/data-types/string)

**示例**

**检查 Dynamic 列中的类型**

```sql title=Query theme={null}
CREATE TABLE test (d Dynamic) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT d, dynamicType(d) FROM test;
```

```response title=Response theme={null}
┌─d─────────────┬─dynamicType(d)─┐
│ ᴺᵁᴸᴸ          │ None           │
│ 42            │ Int64          │
│ Hello, World! │ String         │
│ [1,2,3]       │ Array(Int64)   │
└───────────────┴────────────────┘
```

<div id="isDynamicElementInSharedData">
  ## isDynamicElementInSharedData
</div>

引入版本：v24.1.0

对于存储为共享 Variant 格式而非单独子列的 Dynamic 列中的行，返回 true。

当 Dynamic 列设置了 `max_types` 限制时，超出该限制的值会以共享二进制格式存储，
而不会拆分为各个独立的类型化子列。此函数可用于识别哪些行是以这种共享格式存储的。

**语法**

```sql theme={null}
isDynamicElementInSharedData(dynamic)
```

**参数**

* `dynamic` — 要检查的 Dynamic 列。[`Dynamic`](/zh/reference/data-types/dynamic)

**返回值**

如果值以共享 Variant 格式存储，则返回 true；如果值存储为独立子列或为 NULL，则返回 false。[`Bool`](/zh/reference/data-types/boolean)

**示例**

**检查带有 max\_types 限制的 Dynamic 列的存储格式**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
┌─d─────────────┬─isDynamicElementInSharedData(d)─┐
│ ᴺᵁᴸᴸ          │ false                           │
│ 42            │ false                           │
│ Hello, World! │ true                            │
│ [1,2,3]       │ true                            │
└───────────────┴─────────────────────────────────┘
```

<div id="isValidJSON">
  ## isValidJSON
</div>

自 v20.1.0 引入

检查传入的字符串是否为有效的 JSON。

**语法**

```sql theme={null}
isValidJSON(json)
```

**参数**

* `json` — 待验证的 JSON 字符串 [`String`](/zh/reference/data-types/string)

**返回值**

如果该字符串是有效的 JSON，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

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

```response title=Response theme={null}
1
0
```

**使用整数访问 JSON 数组和 JSON 对象**

```sql title=Query theme={null}
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);
```

```response title=Response theme={null}
0
1
1
1
1
1
0
```

<div id="simpleJSONExtractBool">
  ## simpleJSONExtractBool
</div>

引入版本：v21.4.0

从名为 `field_name` 的字段值中解析出一个 true/false 值。
结果为 `UInt8`。

**语法**

```sql theme={null}
simpleJSONExtractBool(json, field_name)
```

**别名**: `visitParamExtractBool`

**参数**

* `json` — 要在其中查找字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名称。[`const String`](/zh/reference/data-types/string)

**返回值**

如果字段的值为 `true`，则返回 `1`；否则返回 `0`。这意味着在以下情况 (包括但不限于) 下，此函数也会返回 `0`：

* 如果字段不存在。
* 如果字段包含字符串形式的 `true`，例如：`{"field":"true"}`。
* 如果字段包含数值 `1`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
0
1
0
0
```

<div id="simpleJSONExtractFloat">
  ## simpleJSONExtractFloat
</div>

引入版本：v21.4.0

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

**语法**

```sql theme={null}
simpleJSONExtractFloat(json, field_name)
```

**别名**: `visitParamExtractFloat`

**参数**

* `json` — 要在其中查找字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名称。[`const String`](/zh/reference/data-types/string)

**返回值**

如果字段存在且包含数字，则返回从该字段中解析出的数值；否则返回 `0`。[`Float64`](/zh/reference/data-types/float)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
0
-4000
0
-3.4
5
```

<div id="simpleJSONExtractInt">
  ## simpleJSONExtractInt
</div>

引入版本：v21.4.0

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

**语法**

```sql theme={null}
simpleJSONExtractInt(json, field_name)
```

**别名**: `visitParamExtractInt`

**参数**

* `json` — 用于查找字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名称。[`const String`](/zh/reference/data-types/string)

**返回值**

如果该字段存在且其值为数值，则返回从该字段中解析出的数值；否则返回 `0`。[`Int64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
0
-4
0
-3
5
```

<div id="simpleJSONExtractRaw">
  ## simpleJSONExtractRaw
</div>

引入版本：v21.4.0

返回名为 `field_name` 的字段值，类型为 `String`，并保留分隔符。

**语法**

```sql theme={null}
simpleJSONExtractRaw(json, field_name)
```

**别名**: `visitParamExtractRaw`

**参数**

* `json` — 要在其中查找字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名称。[`const String`](/zh/reference/data-types/string)

**返回值**

如果字段存在，则返回该字段的字符串值 (包括分隔符) ；否则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
"-4e3"
-3.4
5
{"def":[1,2,3]}
```

<div id="simpleJSONExtractString">
  ## simpleJSONExtractString
</div>

引入版本：v21.4.0

从名为 `field_name` 的字段的值中解析出双引号括起来的 `String`。

**实现细节**

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

**语法**

```sql theme={null}
simpleJSONExtractString(json, field_name)
```

**别名**: `visitParamExtractString`

**参数**

* `json` — 要在其中查找字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名。[`const String`](/zh/reference/data-types/string)

**返回值**

返回字段未经转义的字符串值，包括分隔符。如果该字段不包含双引号括起来的字符串、转义还原失败，或字段不存在，则返回空字符串。[`String`](/zh/reference/data-types/string)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
\n\0

☺
```

<div id="simpleJSONExtractUInt">
  ## simpleJSONExtractUInt
</div>

引入版本：v21.4.0

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

**语法**

```sql theme={null}
simpleJSONExtractUInt(json, field_name)
```

**别名**: `visitParamExtractUInt`

**参数**

* `json` — 要搜索字段的 JSON。[`String`](/zh/reference/data-types/string)
* `field_name` — 要搜索的字段名。[`const String`](/zh/reference/data-types/string)

**返回值**

如果字段存在且包含数值，则返回从该字段中解析出的数值；否则返回 `0`。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
0
4
0
3
5
```

<div id="simpleJSONHas">
  ## simpleJSONHas
</div>

引入版本：v21.4.0

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

**语法**

```sql theme={null}
simpleJSONHas(json, field_name)
```

**别名**: `visitParamHas`

**参数**

* `json` — 要在其中查找字段的 JSON。 [`String`](/zh/reference/data-types/string)
* `field_name` — 要查找的字段名称。 [`const String`](/zh/reference/data-types/string)

**返回值**

如果字段存在，则返回 `1`；否则返回 `0`。 [`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
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;
```

```response title=Response theme={null}
1
0
```

<div id="toJSONString">
  ## toJSONString
</div>

引入版本：v21.7.0

将一个值序列化为其 JSON 表示形式。支持多种数据类型和嵌套结构。
默认情况下，64 位[整数](/zh/reference/data-types/int-uint)或更大的整数 (例如 `UInt64` 或 `Int128`) 会以引号括起来。[output\_format\_json\_quote\_64bit\_integers](/zh/reference/settings/formats#output_format_json_quote_64bit_integers) 控制此行为。
特殊值 `NaN` 和 `inf` 会被替换为 `null`。启用 [output\_format\_json\_quote\_denormals](/zh/reference/settings/formats#output_format_json_quote_denormals) 设置可显示它们。
序列化 [枚举](/zh/reference/data-types/enum) 值时，该函数会输出其名称。

另请参见：

* [output\_format\_json\_quote\_64bit\_integers](/zh/reference/settings/formats#output_format_json_quote_64bit_integers)
* [output\_format\_json\_quote\_denormals](/zh/reference/settings/formats#output_format_json_quote_denormals)

**语法**

```sql theme={null}
toJSONString(value)
```

**参数**

* `value` — 要序列化的值。该值可以是任意数据类型。[`Any`](/zh/reference/data-types)

**返回值**

返回该值的 JSON 表示。[`String`](/zh/reference/data-types/string)

**示例**

**Map 的序列化**

```sql title=Query theme={null}
SELECT toJSONString(map('key1', 1, 'key2', 2));
```

```response title=Response theme={null}
┌─toJSONString(map('key1', 1, 'key2', 2))─┐
│ {"key1":1,"key2":2}                     │
└─────────────────────────────────────────┘
```

**特殊值**

```sql title=Query theme={null}
SELECT toJSONString(tuple(1.25, NULL, NaN, +inf, -inf, [])) SETTINGS output_format_json_quote_denormals = 1;
```

```response title=Response theme={null}
┌─toJSONString(tuple(1.25, NULL, NaN, plus(inf), minus(inf), []))─┐
│ [1.25,null,"nan","inf","-inf",[]]                               │
└─────────────────────────────────────────────────────────────────┘
```