docs: add json_strip_nulls function (#3107)

* docs: add json_strip_nulls function

* fix

* fix

* fix

* fix

* fix

---------

Co-authored-by: Q <787025321@qq.com>

Author: b41sh

docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md

@@ -44,14 +44,15 @@ title: JSON 函数
 | [JSON_EXTRACT_PATH_TEXT](json/json-extract-path-text) | 使用路径从 JSON 提取文本值 | `JSON_EXTRACT_PATH_TEXT('{"name":"John"}', 'name')` → `'John'` |
 | [JSON_EACH](json/json-each) | 将 JSON 对象展开为键值对 | `JSON_EACH('{"a":1,"b":2}')` → `[("a",1),("b",2)]` |
 | [JSON_ARRAY_ELEMENTS](json/json-array-elements) | 将 JSON 数组展开为单个元素 | `JSON_ARRAY_ELEMENTS('[1,2,3]')` → `1, 2, 3` |
+| [JQ](json/jq) | 使用 jq 风格查询处理 JSON | `JQ('{"name":"John"}', '.name')` → `"John"` |
 
 ## JSON 格式化与处理
 
 | 函数 | 描述 | 示例 |
 |----------|-------------|---------|
 | [JSON_PRETTY](json/json-pretty) | 以适当缩进格式化 JSON | `JSON_PRETTY('{"a":1}')` → 格式化后的 JSON 字符串 |
-| [STRIP_NULL_VALUE](json/strip-null-value) | 从 JSON 中移除 null 值 | `STRIP_NULL_VALUE('{"a":1,"b":null}')` → `{"a":1}` |
-| [JQ](json/jq) | 使用 jq 风格查询处理 JSON | `JQ('{"name":"John"}', '.name')` → `"John"` |
+| [STRIP_NULL_VALUE](json/strip-null-value) | 将 JSON 的 null 值转换为 SQL 的 NULL 值 | `STRIP_NULL_VALUE(parse_json('null'))` → `NULL` |
+| [JSON_STRIP_NULLS](json/json-strip-nulls) | 从 JSON 对象中移除 null 值 | `JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}'))` → `{"a":1}` |
 
 ## JSON 包含与键检测
 

docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-strip-nulls.md

@@ -0,0 +1,34 @@
+---
+title: JSON_STRIP_NULLS
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="引入或更新于：v1.2.762"/>
+
+从 JSON 对象中移除所有值为 null 的属性。
+
+## 语法
+
+```sql
+JSON_STRIP_NULLS(<variant_expr>)
+```
+
+## 参数
+
+VARIANT 类型的表达式。
+
+## 返回类型
+
+VARIANT 类型。
+
+## 示例
+
+```sql
+SELECT JSON_STRIP_NULLS(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}')) AS value;
+
+╭───────────────────────────╮
+│           value           │
+├───────────────────────────┤
+│ {"age":30,"name":"Alice"} │
+╰───────────────────────────╯
+```

docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md

@@ -1,29 +1,43 @@
 ---
 title: STRIP_NULL_VALUE
-title_includes: JSON_STRIP_NULLS
 ---
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
 <FunctionDescription description="引入或更新于：v1.2.762"/>
 
-从 JSON 对象中移除所有值为 null 的属性。
+将 JSON 的 null 值转换为 SQL 的 NULL 值。所有其它 Variant 值均保持不变。
 
 ## 语法
 
 ```sql
-STRIP_NULL_VALUE(<json_string>)
+STRIP_NULL_VALUE(<variant_expr>)
 ```
 
+## 参数
+
+VARIANT 类型的表达式。
+
 ## 返回类型
 
-返回与输入 JSON 值相同类型的值。
+- 如果表达式为 JSON 的 null 值，则该函数返回 SQL NULL。
+- 如果表达式不是 JSON 的 null 值，则该函数返回输入值。
 
 ## 示例
 
 ```sql
-SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}'));
+SELECT STRIP_NULL_VALUE(PARSE_JSON('null')) AS value;
+
+╭───────╮
+│ value │
+├───────┤
+│ NULL  │
+╰───────╯
+
+SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}')) AS value;
 
-strip_null_value(parse_json('{"name": "alice", "age": 30, "city": null}'))|
---------------------------------------------------------------------------+
-{"age":30,"name":"Alice"}                                                 |
+╭───────────────────────────────────────╮
+│                 value                 │
+├───────────────────────────────────────┤
+│ {"age":30,"city":null,"name":"Alice"} │
+╰───────────────────────────────────────╯
 ```

docs/cn/sql-reference/20-sql-functions/10-semi-structured-functions/index.md

@@ -36,7 +36,8 @@ Databend 中的结构化与半结构化函数能够高效处理数组（Array）
 |----------|-------------|--------|
 | [JSON_TO_STRING](semi-structured-functions/json/json-to-string) | 将 JSON 值转换为字符串 | `JSON_TO_STRING(PARSE_JSON('{"a":1}'))` |
 | [JSON_PRETTY](semi-structured-functions/json/json-pretty) | 使用适当缩进格式化 JSON | `JSON_PRETTY(PARSE_JSON('{"a":1}'))` |
-| [STRIP_NULL_VALUE](semi-structured-functions/json/strip-null-value) | 从 JSON 中移除 null 值 | `STRIP_NULL_VALUE(PARSE_JSON('{"a":1,"b":null}'))` |
+| [STRIP_NULL_VALUE](semi-structured-functions/json/strip-null-value) | 将 JSON 的 null 值转换为 SQL 的 NULL 值 | `STRIP_NULL_VALUE(parse_json('null'))` → `NULL` |
+| [JSON_STRIP_NULLS](semi-structured-functions/json/json-strip-nulls) | 从 JSON 对象中移除 null 值 | `JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}'))` → `{"a":1}` |
 
 ### 数组/对象展开
 | 函数 | 描述 | 示例 |
@@ -130,4 +131,4 @@ Databend 中的结构化与半结构化函数能够高效处理数组（Array）
 | [IS_INTEGER](semi-structured-functions/type-predicate/is-integer) | 检查 JSON 值是否为整数 | `IS_INTEGER(PARSE_JSON('42'))` |
 | [IS_FLOAT](semi-structured-functions/type-predicate/is-float) | 检查 JSON 值是否为浮点数 | `IS_FLOAT(PARSE_JSON('3.14'))` |
 | [IS_BOOLEAN](semi-structured-functions/type-predicate/is-boolean) | 检查 JSON 值是否为 BOOLEAN | `IS_BOOLEAN(PARSE_JSON('true'))` |
-| [IS_NULL_VALUE](semi-structured-functions/type-predicate/is-null-value) | 检查 JSON 值是否为 null | `IS_NULL_VALUE(PARSE_JSON('null'))` |
+| [IS_NULL_VALUE](semi-structured-functions/type-predicate/is-null-value) | 检查 JSON 值是否为 null | `IS_NULL_VALUE(PARSE_JSON('null'))` |

docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/index.md

@@ -44,14 +44,15 @@ This section provides reference information for JSON functions in Databend. JSON
 | [JSON_EXTRACT_PATH_TEXT](json/json-extract-path-text) | Extracts text value from JSON using path | `JSON_EXTRACT_PATH_TEXT('{"name":"John"}', 'name')` → `'John'` |
 | [JSON_EACH](json/json-each) | Expands JSON object into key-value pairs | `JSON_EACH('{"a":1,"b":2}')` → `[("a",1),("b",2)]` |
 | [JSON_ARRAY_ELEMENTS](json/json-array-elements) | Expands JSON array into individual elements | `JSON_ARRAY_ELEMENTS('[1,2,3]')` → `1, 2, 3` |
+| [JQ](json/jq) | Processes JSON using jq-style queries | `JQ('{"name":"John"}', '.name')` → `"John"` |
 
 ## JSON Formatting & Processing
 
 | Function | Description | Example |
 |----------|-------------|---------|
 | [JSON_PRETTY](json/json-pretty) | Formats JSON with proper indentation | `JSON_PRETTY('{"a":1}')` → Formatted JSON string |
-| [STRIP_NULL_VALUE](json/strip-null-value) | Removes null values from JSON | `STRIP_NULL_VALUE('{"a":1,"b":null}')` → `{"a":1}` |
-| [JQ](json/jq) | Processes JSON using jq-style queries | `JQ('{"name":"John"}', '.name')` → `"John"` |
+| [STRIP_NULL_VALUE](json/strip-null-value) | Converts a JSON null value to a SQL NULL value | `STRIP_NULL_VALUE(parse_json('null'))` → `NULL` |
+| [JSON_STRIP_NULLS](json/json-strip-nulls) | Removes null values from JSON Object | `JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}'))` → `{"a":1}` |
 
 ## JSON Containment & Existence
 

docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/json-strip-nulls.md

@@ -0,0 +1,34 @@
+---
+title: JSON_STRIP_NULLS
+---
+import FunctionDescription from '@site/src/components/FunctionDescription';
+
+<FunctionDescription description="Introduced or updated: v1.2.762"/>
+
+Removes all properties with null values from a JSON object. 
+
+## Syntax
+
+```sql
+JSON_STRIP_NULLS(<variant_expr>)
+```
+
+## Arguments
+
+An expression of type VARIANT.
+
+## Return Type
+
+VARIANT.
+
+## Examples
+
+```sql
+SELECT JSON_STRIP_NULLS(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}')) AS value;
+
+╭───────────────────────────╮
+│           value           │
+├───────────────────────────┤
+│ {"age":30,"name":"Alice"} │
+╰───────────────────────────╯
+```

docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/0-json/strip-null-value.md

@@ -1,29 +1,43 @@
 ---
 title: STRIP_NULL_VALUE
-title_includes: JSON_STRIP_NULLS
 ---
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
 <FunctionDescription description="Introduced or updated: v1.2.762"/>
 
-Removes all properties with null values from a JSON object. 
+Converts a JSON null value to a SQL NULL value. All other variant values are passed unchanged.
 
 ## Syntax
 
 ```sql
-STRIP_NULL_VALUE(<json_string>)
+STRIP_NULL_VALUE(<variant_expr>)
 ```
 
+## Arguments
+
+An expression of type VARIANT.
+
 ## Return Type
 
-Returns a value of the same type as the input JSON value.
+- If the expression is a JSON null value, the function returns a SQL NULL.
+- If the expression is not a JSON null value, the function returns the input value.
 
 ## Examples
 
 ```sql
-SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}'));
+SELECT STRIP_NULL_VALUE(PARSE_JSON('null')) AS value;
+
+╭───────╮
+│ value │
+├───────┤
+│ NULL  │
+╰───────╯
+
+SELECT STRIP_NULL_VALUE(PARSE_JSON('{"name": "Alice", "age": 30, "city": null}')) AS value;
 
-strip_null_value(parse_json('{"name": "alice", "age": 30, "city": null}'))|
---------------------------------------------------------------------------+
-{"age":30,"name":"Alice"}                                                 |
+╭───────────────────────────────────────╮
+│                 value                 │
+├───────────────────────────────────────┤
+│ {"age":30,"city":null,"name":"Alice"} │
+╰───────────────────────────────────────╯
 ```

docs/en/sql-reference/20-sql-functions/10-semi-structured-functions/index.md

@@ -36,7 +36,8 @@ Structured and semi-structured functions in Databend enable efficient processing
 |----------|-------------|--------|
 | [JSON_TO_STRING](semi-structured-functions/json/json-to-string) | Converts a JSON value to a string | `JSON_TO_STRING(PARSE_JSON('{"a":1}'))` |
 | [JSON_PRETTY](semi-structured-functions/json/json-pretty) | Formats JSON with proper indentation | `JSON_PRETTY(PARSE_JSON('{"a":1}'))` |
-| [STRIP_NULL_VALUE](semi-structured-functions/json/strip-null-value) | Removes null values from JSON | `STRIP_NULL_VALUE(PARSE_JSON('{"a":1,"b":null}'))` |
+| [STRIP_NULL_VALUE](semi-structured-functions/json/strip-null-value) | Converts a JSON null value to a SQL NULL value | `STRIP_NULL_VALUE(parse_json('null'))` → `NULL` |
+| [JSON_STRIP_NULLS](semi-structured-functions/json/json-strip-nulls) | Removes null values from JSON Object | `JSON_STRIP_NULLS(PARSE_JSON('{"a":1,"b":null}'))` → `{"a":1}` |
 
 ### Array/Object Expansion
 | Function | Description | Example |