From 6ac04b9880d7e98a8bd9377669d2b8849f6ad735 Mon Sep 17 00:00:00 2001 From: linzhenqi Date: Sat, 28 Feb 2026 17:24:40 +0800 Subject: [PATCH 1/2] [Feature](func) Support table function json_each, json_each_text --- .../table-functions/json-each-text.md | 99 +++++++++++++++++ .../table-functions/json-each.md | 97 +++++++++++++++++ .../table-functions/json-each-text.md | 99 +++++++++++++++++ .../table-functions/json-each.md | 96 ++++++++++++++++ .../table-functions/json-each-text.md | 103 ++++++++++++++++++ .../table-functions/json-each.md | 101 +++++++++++++++++ sidebars.ts | 2 + .../table-functions/json-each-text.md | 103 ++++++++++++++++++ .../table-functions/json-each.md | 101 +++++++++++++++++ versioned_sidebars/version-4.x-sidebars.json | 2 + 10 files changed, 803 insertions(+) create mode 100644 docs/sql-manual/sql-functions/table-functions/json-each-text.md create mode 100644 docs/sql-manual/sql-functions/table-functions/json-each.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md diff --git a/docs/sql-manual/sql-functions/table-functions/json-each-text.md b/docs/sql-manual/sql-functions/table-functions/json-each-text.md new file mode 100644 index 0000000000000..6d9b6bcaf96c0 --- /dev/null +++ b/docs/sql-manual/sql-functions/table-functions/json-each-text.md @@ -0,0 +1,99 @@ +--- +{ + "title": "JSON_EACH_TEXT", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column is returned as plain text. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_text` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). Unlike [`json_each`](json-each.md), the `value` column is of type TEXT, so string values are returned **without** JSON quotes. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH_TEXT() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ---------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +|---------|------|--------------------------------------------------------------------------------------| +| `key` | TEXT | The key name from the JSON object | +| `value` | TEXT | The corresponding value as plain text (string values have no quotes, e.g. `foo`) | + +Special cases: +- If `` is NULL, returns 0 rows +- If `` is an empty object (`{}`), returns 0 rows +- A JSON `null` value is returned as SQL `NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> The `value` column is of TEXT type, so string values have **no** JSON quotes (unlike `json_each`). + +JSON object with multiple value types + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"str":"hello","num":42,"bool":true,"null_val":null}') t AS k, v; +``` + +```text ++----------+-------+ +| k | v | ++----------+-------+ +| str | hello | +| num | 42 | +| bool | true | +| null_val | NULL | ++----------+-------+ +``` + +> JSON `null` values map to SQL `NULL`. + +NULL parameter: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text(NULL) t AS k, v; +-- Empty set +``` + +Empty object: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{}') t AS k, v; +-- Empty set +``` diff --git a/docs/sql-manual/sql-functions/table-functions/json-each.md b/docs/sql-manual/sql-functions/table-functions/json-each.md new file mode 100644 index 0000000000000..ade4facfe3741 --- /dev/null +++ b/docs/sql-manual/sql-functions/table-functions/json-each.md @@ -0,0 +1,97 @@ +--- +{ + "title": "JSON_EACH", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column retains JSON type. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). The `value` column retains the JSON type, so string values are returned with JSON quotes preserved. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ---------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +|---------|--------|-----------------------------------------------------------------------------| +| `key` | String | The key name from the JSON object | +| `value` | JSON | The corresponding value, kept as JSON type (string values include quotes, e.g. `"foo"`) | + +Special cases: +- If `` is NULL, returns 0 rows +- If `` is an empty object (`{}`), returns 0 rows + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +> The `value` column is of JSON type, so string values retain their JSON quotes. + +JSON object with multiple value types + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"str":"hello","num":42,"bool":true,"null_val":null,"arr":[1,2]}') t AS k, v; +``` + +```text ++----------+---------+ +| k | v | ++----------+---------+ +| str | "hello" | +| num | 42 | +| bool | true | +| null_val | NULL | +| arr | [1,2] | ++----------+---------+ +``` + +NULL parameter: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each(NULL) t AS k, v; +-- Empty set +``` + +Empty object: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{}') t AS k, v; +-- Empty set +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text.md new file mode 100644 index 0000000000000..360bb9045d4b0 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text.md @@ -0,0 +1,99 @@ +--- +{ + "title": "JSON_EACH_TEXT", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 TEXT 类型值。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_text` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。与 [`json_each`](json-each.md) 不同，`value` 列的类型为 TEXT，字符串值在输出中**不保留** JSON 引号。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH_TEXT() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ---- | ------------------------------------------------------ | +| `key` | TEXT | JSON 对象的键名 | +| `value` | TEXT | 对应的值，以文本形式返回（字符串值不带引号，如 `foo`） | + +特殊情况： +- 如果 `` 为 NULL，返回 0 行 +- 如果 `` 为空对象（`{}`），返回 0 行 +- JSON 值为 `null` 时，对应的 TEXT 值为 SQL `NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> `value` 列类型为 TEXT，字符串值**不保留** JSON 引号（与 `json_each` 的区别）。 + +包含多种类型值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"str":"hello","num":42,"bool":true,"null_val":null}') t AS k, v; +``` + +```text ++----------+-------+ +| k | v | ++----------+-------+ +| str | hello | +| num | 42 | +| bool | true | +| null_val | NULL | ++----------+-------+ +``` + +> JSON 中的 `null` 值对应 SQL `NULL`。 + +NULL 参数：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text(NULL) t AS k, v; +-- Empty set +``` + +空对象：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{}') t AS k, v; +-- Empty set +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each.md new file mode 100644 index 0000000000000..8e01359d1bb47 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each.md @@ -0,0 +1,96 @@ +--- +{ + "title": "JSON_EACH", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 JSON 类型值。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。其中 `value` 列保持 JSON 类型，字符串值在输出中保留 JSON 引号。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ------ | ------------------------------------------------------ | +| `key` | String | JSON 对象的键名 | +| `value` | JSON | 对应的值，保持 JSON 类型（字符串值带引号，如 `"foo"`） | + +特殊情况： +- 如果 `` 为 NULL，返回 0 行 +- 如果 `` 为空对象（`{}`），返回 0 行 + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +> `value` 列类型为 JSON，字符串值保留 JSON 引号。 + +包含多种类型值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"str":"hello","num":42,"bool":true,"null_val":null,"arr":[1,2]}') t AS k, v; +``` + +```text ++----------+---------+ +| k | v | ++----------+---------+ +| str | "hello" | +| num | 42 | +| bool | true | +| null_val | NULL | +| arr | [1,2] | ++----------+---------+ +``` + +NULL 参数：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each(NULL) t AS k, v; +-- Empty set +``` +空对象：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{}') t AS k, v; +-- Empty set +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md new file mode 100644 index 0000000000000..a584a17d12260 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md @@ -0,0 +1,103 @@ +--- +{ + "title": "JSON_EACH_TEXT", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 TEXT 类型值。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_text` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。与 [`json_each`](json-each.md) 不同，`value` 列的类型为 TEXT，字符串值在输出中**不保留** JSON 引号。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +:::note +该函数自4.1.0开始支持 +::: + +## 语法 + +```sql +JSON_EACH_TEXT() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ---- | ------------------------------------------------------ | +| `key` | TEXT | JSON 对象的键名 | +| `value` | TEXT | 对应的值，以文本形式返回（字符串值不带引号，如 `foo`） | + +特殊情况： +- 如果 `` 为 NULL，返回 0 行 +- 如果 `` 为空对象（`{}`），返回 0 行 +- JSON 值为 `null` 时，对应的 TEXT 值为 SQL `NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> `value` 列类型为 TEXT，字符串值**不保留** JSON 引号（与 `json_each` 的区别）。 + +包含多种类型值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"str":"hello","num":42,"bool":true,"null_val":null}') t AS k, v; +``` + +```text ++----------+-------+ +| k | v | ++----------+-------+ +| str | hello | +| num | 42 | +| bool | true | +| null_val | NULL | ++----------+-------+ +``` + +> JSON 中的 `null` 值对应 SQL `NULL`。 + +NULL 参数：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text(NULL) t AS k, v; +-- Empty set +``` + +空对象：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{}') t AS k, v; +-- Empty set +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md new file mode 100644 index 0000000000000..be54303963d15 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md @@ -0,0 +1,101 @@ +--- +{ + "title": "JSON_EACH", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 JSON 类型值。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。其中 `value` 列保持 JSON 类型，字符串值在输出中保留 JSON 引号。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +:::note +该函数自4.1.0开始支持 +::: + +## 语法 + +```sql +JSON_EACH() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ------ | ------------------------------------------------------ | +| `key` | String | JSON 对象的键名 | +| `value` | JSON | 对应的值，保持 JSON 类型（字符串值带引号，如 `"foo"`） | + +特殊情况： +- 如果 `` 为 NULL，返回 0 行 +- 如果 `` 为空对象（`{}`），返回 0 行 + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +> `value` 列类型为 JSON，字符串值保留 JSON 引号。 + +包含多种类型值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"str":"hello","num":42,"bool":true,"null_val":null,"arr":[1,2]}') t AS k, v; +``` + +```text ++----------+---------+ +| k | v | ++----------+---------+ +| str | "hello" | +| num | 42 | +| bool | true | +| null_val | NULL | +| arr | [1,2] | ++----------+---------+ +``` + +NULL 参数：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each(NULL) t AS k, v; +-- Empty set +``` + +空对象：返回 0 行 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{}') t AS k, v; +-- Empty set +``` diff --git a/sidebars.ts b/sidebars.ts index 31f7044a02d8c..b3935d1f2518b 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2038,6 +2038,8 @@ const sidebars: SidebarsConfig = { 'sql-manual/sql-functions/table-functions/explode-numbers-outer', 'sql-manual/sql-functions/table-functions/explode-split', 'sql-manual/sql-functions/table-functions/explode-split-outer', + 'sql-manual/sql-functions/table-functions/json-each', + 'sql-manual/sql-functions/table-functions/json-each-text', 'sql-manual/sql-functions/table-functions/posexplode', 'sql-manual/sql-functions/table-functions/posexplode-outer', ], diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md new file mode 100644 index 0000000000000..d24cb9efb4c2c --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text.md @@ -0,0 +1,103 @@ +--- +{ + "title": "JSON_EACH_TEXT", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column is returned as plain text. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_text` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). Unlike [`json_each`](json-each.md), the `value` column is of type TEXT, so string values are returned **without** JSON quotes. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +:::note +This function has been supported since 4.1.0 +::: + +## Syntax + +```sql +JSON_EACH_TEXT() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ---------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +|---------|------|--------------------------------------------------------------------------------------| +| `key` | TEXT | The key name from the JSON object | +| `value` | TEXT | The corresponding value as plain text (string values have no quotes, e.g. `foo`) | + +Special cases: +- If `` is NULL, returns 0 rows +- If `` is an empty object (`{}`), returns 0 rows +- A JSON `null` value is returned as SQL `NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> The `value` column is of TEXT type, so string values have **no** JSON quotes (unlike `json_each`). + +JSON object with multiple value types + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{"str":"hello","num":42,"bool":true,"null_val":null}') t AS k, v; +``` + +```text ++----------+-------+ +| k | v | ++----------+-------+ +| str | hello | +| num | 42 | +| bool | true | +| null_val | NULL | ++----------+-------+ +``` + +> JSON `null` values map to SQL `NULL`. + +NULL parameter: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text(NULL) t AS k, v; +-- Empty set +``` + +Empty object: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text('{}') t AS k, v; +-- Empty set +``` \ No newline at end of file diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md new file mode 100644 index 0000000000000..28eb91281a905 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each.md @@ -0,0 +1,101 @@ +--- +{ + "title": "JSON_EACH", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column retains JSON type. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). The `value` column retains the JSON type, so string values are returned with JSON quotes preserved. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +:::note +This function has been supported since 4.1.0 +::: + +## Syntax + +```sql +JSON_EACH() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ---------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +|---------|--------|-----------------------------------------------------------------------------| +| `key` | String | The key name from the JSON object | +| `value` | JSON | The corresponding value, kept as JSON type (string values include quotes, e.g. `"foo"`) | + +Special cases: +- If `` is NULL, returns 0 rows +- If `` is an empty object (`{}`), returns 0 rows + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +> The `value` column is of JSON type, so string values retain their JSON quotes. + +JSON object with multiple value types + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{"str":"hello","num":42,"bool":true,"null_val":null,"arr":[1,2]}') t AS k, v; +``` + +```text ++----------+---------+ +| k | v | ++----------+---------+ +| str | "hello" | +| num | 42 | +| bool | true | +| null_val | NULL | +| arr | [1,2] | ++----------+---------+ +``` + +NULL parameter: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each(NULL) t AS k, v; +-- Empty set +``` + +Empty object: returns 0 rows + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each('{}') t AS k, v; +-- Empty set +``` diff --git a/versioned_sidebars/version-4.x-sidebars.json b/versioned_sidebars/version-4.x-sidebars.json index 59e7778d6ecea..f88168c4aa9e6 100644 --- a/versioned_sidebars/version-4.x-sidebars.json +++ b/versioned_sidebars/version-4.x-sidebars.json @@ -2050,6 +2050,8 @@ "sql-manual/sql-functions/table-functions/explode-numbers-outer", "sql-manual/sql-functions/table-functions/explode-split", "sql-manual/sql-functions/table-functions/explode-split-outer", + "sql-manual/sql-functions/table-functions/json-each", + "sql-manual/sql-functions/table-functions/json-each-text", "sql-manual/sql-functions/table-functions/posexplode", "sql-manual/sql-functions/table-functions/posexplode-outer" ] From aeb0472e48a92765682c31abfb4d56d522517a6a Mon Sep 17 00:00:00 2001 From: linzhenqi Date: Tue, 3 Mar 2026 14:41:37 +0800 Subject: [PATCH 2/2] add _outer expend --- .../table-functions/json-each-outer.md | 91 ++++++++++++++++++ .../table-functions/json-each-text-outer.md | 94 +++++++++++++++++++ .../table-functions/json-each-outer.md | 91 ++++++++++++++++++ .../table-functions/json-each-text-outer.md | 94 +++++++++++++++++++ .../table-functions/json-each-outer.md | 91 ++++++++++++++++++ .../table-functions/json-each-text-outer.md | 94 +++++++++++++++++++ sidebars.ts | 2 + .../table-functions/json-each-outer.md | 91 ++++++++++++++++++ .../table-functions/json-each-text-outer.md | 94 +++++++++++++++++++ versioned_sidebars/version-4.x-sidebars.json | 2 + 10 files changed, 744 insertions(+) create mode 100644 docs/sql-manual/sql-functions/table-functions/json-each-outer.md create mode 100644 docs/sql-manual/sql-functions/table-functions/json-each-text-outer.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-outer.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text-outer.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md diff --git a/docs/sql-manual/sql-functions/table-functions/json-each-outer.md b/docs/sql-manual/sql-functions/table-functions/json-each-outer.md new file mode 100644 index 0000000000000..8ff7abef02dd3 --- /dev/null +++ b/docs/sql-manual/sql-functions/table-functions/json-each-outer.md @@ -0,0 +1,91 @@ +--- +{ + "title": "JSON_EACH_OUTER", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column retains JSON type. Unlike json_each, returns one row of NULLs instead of 0 rows when input is NULL or an empty object. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_outer` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). The `value` column retains the JSON type, so string values are returned with JSON quotes preserved. + +Unlike [`json_each`](json-each.md), when the input is NULL or an empty object, `json_each_outer` returns one row of `NULL, NULL` instead of 0 rows. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH_OUTER() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ------------------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +| ------- | ------ | --------------------------------------------------------------------------------------- | +| `key` | String | The key name from the JSON object | +| `value` | JSON | The corresponding value, kept as JSON type (string values include quotes, e.g. `"foo"`) | + +Special cases: +- If `` is NULL, returns 1 row of `NULL, NULL` +- If `` is an empty object (`{}`), returns 1 row of `NULL, NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +NULL parameter: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +Empty object: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/docs/sql-manual/sql-functions/table-functions/json-each-text-outer.md b/docs/sql-manual/sql-functions/table-functions/json-each-text-outer.md new file mode 100644 index 0000000000000..1d39d64a8c581 --- /dev/null +++ b/docs/sql-manual/sql-functions/table-functions/json-each-text-outer.md @@ -0,0 +1,94 @@ +--- +{ + "title": "JSON_EACH_TEXT_OUTER", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column is returned as plain text. Unlike json_each_text, returns one row of NULLs instead of 0 rows when input is NULL or an empty object. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_text_outer` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). Unlike [`json_each_outer`](json-each-outer.md), the `value` column is of type TEXT, so string values are returned **without** JSON quotes. + +Unlike [`json_each_text`](json-each-text.md), when the input is NULL or an empty object, `json_each_text_outer` returns one row of `NULL, NULL` instead of 0 rows. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH_TEXT_OUTER() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ------------------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +| ------- | ---- | -------------------------------------------------------------------------------- | +| `key` | TEXT | The key name from the JSON object | +| `value` | TEXT | The corresponding value as plain text (string values have no quotes, e.g. `foo`) | + +Special cases: +- If `` is NULL, returns 1 row of `NULL, NULL` +- If `` is an empty object (`{}`), returns 1 row of `NULL, NULL` +- A JSON `null` value is returned as SQL `NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> The `value` column is of TEXT type, so string values have **no** JSON quotes (unlike `json_each_outer`). + +NULL parameter: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +Empty object: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-outer.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-outer.md new file mode 100644 index 0000000000000..5b10c0e831cc4 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-outer.md @@ -0,0 +1,91 @@ +--- +{ + "title": "JSON_EACH_OUTER", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 JSON 类型值。与 json_each 的区别在于：当输入为 NULL 或空对象时，返回一行 NULL 值而非 0 行。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_outer` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。其中 `value` 列保持 JSON 类型，字符串值在输出中保留 JSON 引号。 + +与 [`json_each`](json-each.md) 的区别在于：当输入为 NULL 或空对象时，`json_each_outer` 返回一行 `NULL, NULL`，而 `json_each` 返回 0 行。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH_OUTER() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ------ | ------------------------------------------------------ | +| `key` | String | JSON 对象的键名 | +| `value` | JSON | 对应的值，保持 JSON 类型（字符串值带引号，如 `"foo"`） | + +特殊情况： +- 如果 `` 为 NULL，返回 1 行 `NULL, NULL` +- 如果 `` 为空对象（`{}`），返回 1 行 `NULL, NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +NULL 参数：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +空对象：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text-outer.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text-outer.md new file mode 100644 index 0000000000000..2bc21a27fbbd9 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/table-functions/json-each-text-outer.md @@ -0,0 +1,94 @@ +--- +{ + "title": "JSON_EACH_TEXT_OUTER", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 TEXT 类型值。与 json_each_text 的区别在于：当输入为 NULL 或空对象时，返回一行 NULL 值而非 0 行。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_text_outer` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。与 [`json_each_outer`](json-each-outer.md) 不同，`value` 列的类型为 TEXT，字符串值在输出中**不保留** JSON 引号。 + +与 [`json_each_text`](json-each-text.md) 的区别在于：当输入为 NULL 或空对象时，`json_each_text_outer` 返回一行 `NULL, NULL`，而 `json_each_text` 返回 0 行。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH_TEXT_OUTER() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ---- | ------------------------------------------------------ | +| `key` | TEXT | JSON 对象的键名 | +| `value` | TEXT | 对应的值，以文本形式返回（字符串值不带引号，如 `foo`） | + +特殊情况： +- 如果 `` 为 NULL，返回 1 行 `NULL, NULL` +- 如果 `` 为空对象（`{}`），返回 1 行 `NULL, NULL` +- JSON 值为 `null` 时，对应的 TEXT 值为 SQL `NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> `value` 列类型为 TEXT，字符串值**不保留** JSON 引号（与 `json_each_outer` 的区别）。 + +NULL 参数：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +空对象：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md new file mode 100644 index 0000000000000..5b10c0e831cc4 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md @@ -0,0 +1,91 @@ +--- +{ + "title": "JSON_EACH_OUTER", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 JSON 类型值。与 json_each 的区别在于：当输入为 NULL 或空对象时，返回一行 NULL 值而非 0 行。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_outer` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。其中 `value` 列保持 JSON 类型，字符串值在输出中保留 JSON 引号。 + +与 [`json_each`](json-each.md) 的区别在于：当输入为 NULL 或空对象时，`json_each_outer` 返回一行 `NULL, NULL`，而 `json_each` 返回 0 行。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH_OUTER() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ------ | ------------------------------------------------------ | +| `key` | String | JSON 对象的键名 | +| `value` | JSON | 对应的值，保持 JSON 类型（字符串值带引号，如 `"foo"`） | + +特殊情况： +- 如果 `` 为 NULL，返回 1 行 `NULL, NULL` +- 如果 `` 为空对象（`{}`），返回 1 行 `NULL, NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +NULL 参数：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +空对象：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md new file mode 100644 index 0000000000000..2bc21a27fbbd9 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md @@ -0,0 +1,94 @@ +--- +{ + "title": "JSON_EACH_TEXT_OUTER", + "language": "zh-CN", + "description": "将顶层 JSON 对象展开为键值对集合，每行包含一个键和对应的 TEXT 类型值。与 json_each_text 的区别在于：当输入为 NULL 或空对象时，返回一行 NULL 值而非 0 行。需配合 LATERAL VIEW 使用。" +} +--- + +## 描述 + +`json_each_text_outer` 表函数将顶层 JSON 对象展开为一组键值对，每行包含一个键（`key`）和对应的值（`value`）。与 [`json_each_outer`](json-each-outer.md) 不同，`value` 列的类型为 TEXT，字符串值在输出中**不保留** JSON 引号。 + +与 [`json_each_text`](json-each-text.md) 的区别在于：当输入为 NULL 或空对象时，`json_each_text_outer` 返回一行 `NULL, NULL`，而 `json_each_text` 返回 0 行。 + +该函数需配合 [`LATERAL VIEW`](../../../query-data/lateral-view.md) 使用。 + +## 语法 + +```sql +JSON_EACH_TEXT_OUTER() +``` + +## 参数 + +| 参数 | 说明 | +| ------------ | -------------------------------------------- | +| `` | 需要展开的 JSON 字符串，内容应为 JSON 对象。 | + +## 返回值 + +返回多列多行数据，每行对应 JSON 对象中的一个键值对： + +| 列名 | 类型 | 说明 | +| ------- | ---- | ------------------------------------------------------ | +| `key` | TEXT | JSON 对象的键名 | +| `value` | TEXT | 对应的值，以文本形式返回（字符串值不带引号，如 `foo`） | + +特殊情况： +- 如果 `` 为 NULL，返回 1 行 `NULL, NULL` +- 如果 `` 为空对象（`{}`），返回 1 行 `NULL, NULL` +- JSON 值为 `null` 时，对应的 TEXT 值为 SQL `NULL` + +## 示例 + +基本用法：展开包含字符串值的 JSON 对象 + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> `value` 列类型为 TEXT，字符串值**不保留** JSON 引号（与 `json_each_outer` 的区别）。 + +NULL 参数：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +空对象：返回 1 行 NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/sidebars.ts b/sidebars.ts index b3935d1f2518b..d07df25475340 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -2039,7 +2039,9 @@ const sidebars: SidebarsConfig = { 'sql-manual/sql-functions/table-functions/explode-split', 'sql-manual/sql-functions/table-functions/explode-split-outer', 'sql-manual/sql-functions/table-functions/json-each', + 'sql-manual/sql-functions/table-functions/json-each-outer', 'sql-manual/sql-functions/table-functions/json-each-text', + 'sql-manual/sql-functions/table-functions/json-each-text-outer', 'sql-manual/sql-functions/table-functions/posexplode', 'sql-manual/sql-functions/table-functions/posexplode-outer', ], diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md new file mode 100644 index 0000000000000..8ff7abef02dd3 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-outer.md @@ -0,0 +1,91 @@ +--- +{ + "title": "JSON_EACH_OUTER", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column retains JSON type. Unlike json_each, returns one row of NULLs instead of 0 rows when input is NULL or an empty object. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_outer` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). The `value` column retains the JSON type, so string values are returned with JSON quotes preserved. + +Unlike [`json_each`](json-each.md), when the input is NULL or an empty object, `json_each_outer` returns one row of `NULL, NULL` instead of 0 rows. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH_OUTER() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ------------------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +| ------- | ------ | --------------------------------------------------------------------------------------- | +| `key` | String | The key name from the JSON object | +| `value` | JSON | The corresponding value, kept as JSON type (string values include quotes, e.g. `"foo"`) | + +Special cases: +- If `` is NULL, returns 1 row of `NULL, NULL` +- If `` is an empty object (`{}`), returns 1 row of `NULL, NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-------+ +| k | v | ++---+-------+ +| a | "foo" | +| b | "bar" | ++---+-------+ +``` + +NULL parameter: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +Empty object: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md new file mode 100644 index 0000000000000..1d39d64a8c581 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/table-functions/json-each-text-outer.md @@ -0,0 +1,94 @@ +--- +{ + "title": "JSON_EACH_TEXT_OUTER", + "language": "en", + "description": "Expands the top-level JSON object into a set of key/value pairs, where the value column is returned as plain text. Unlike json_each_text, returns one row of NULLs instead of 0 rows when input is NULL or an empty object. Must be used with LATERAL VIEW." +} +--- + +## Description + +The `json_each_text_outer` table function expands the top-level JSON object into a set of key/value pairs. Each row contains one key (`key`) and its corresponding value (`value`). Unlike [`json_each_outer`](json-each-outer.md), the `value` column is of type TEXT, so string values are returned **without** JSON quotes. + +Unlike [`json_each_text`](json-each-text.md), when the input is NULL or an empty object, `json_each_text_outer` returns one row of `NULL, NULL` instead of 0 rows. + +Must be used with [`LATERAL VIEW`](../../../query-data/lateral-view.md). + +## Syntax + +```sql +JSON_EACH_TEXT_OUTER() +``` + +## Parameters + +| Parameter | Description | +| ------------ | ------------------------------------------------------------- | +| `` | The JSON string to expand. The content must be a JSON object. | + +## Return Value + +Returns multi-column, multi-row data. Each row corresponds to one key-value pair in the JSON object: + +| Column | Type | Description | +| ------- | ---- | -------------------------------------------------------------------------------- | +| `key` | TEXT | The key name from the JSON object | +| `value` | TEXT | The corresponding value as plain text (string values have no quotes, e.g. `foo`) | + +Special cases: +- If `` is NULL, returns 1 row of `NULL, NULL` +- If `` is an empty object (`{}`), returns 1 row of `NULL, NULL` +- A JSON `null` value is returned as SQL `NULL` + +## Examples + +Basic usage: expand a JSON object with string values + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{"a":"foo","b":"bar"}') t AS k, v; +``` + +```text ++---+-----+ +| k | v | ++---+-----+ +| a | foo | +| b | bar | ++---+-----+ +``` + +> The `value` column is of TEXT type, so string values have **no** JSON quotes (unlike `json_each_outer`). + +NULL parameter: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer(NULL) t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` + +Empty object: returns 1 row of NULL + +```sql +SELECT k, v +FROM (SELECT 1) dummy +LATERAL VIEW json_each_text_outer('{}') t AS k, v; +``` + +```text ++------+------+ +| k | v | ++------+------+ +| NULL | NULL | ++------+------+ +``` diff --git a/versioned_sidebars/version-4.x-sidebars.json b/versioned_sidebars/version-4.x-sidebars.json index f88168c4aa9e6..4579e0ea87fdb 100644 --- a/versioned_sidebars/version-4.x-sidebars.json +++ b/versioned_sidebars/version-4.x-sidebars.json @@ -2051,7 +2051,9 @@ "sql-manual/sql-functions/table-functions/explode-split", "sql-manual/sql-functions/table-functions/explode-split-outer", "sql-manual/sql-functions/table-functions/json-each", + "sql-manual/sql-functions/table-functions/json-each-outer", "sql-manual/sql-functions/table-functions/json-each-text", + "sql-manual/sql-functions/table-functions/json-each-text-outer", "sql-manual/sql-functions/table-functions/posexplode", "sql-manual/sql-functions/table-functions/posexplode-outer" ]