This is an automated email from the ASF dual-hosted git repository.
eldenmoon pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 32c52e96861 Add FAQ for null value description in VARIANT and JSON
type (#2396)
32c52e96861 is described below
commit 32c52e96861e8677dfd93ae471a5cff47d8d9d56
Author: lihangyu <[email protected]>
AuthorDate: Mon May 19 16:22:51 2025 +0800
Add FAQ for null value description in VARIANT and JSON type (#2396)
## Versions
- [x] dev
- [x] 3.0
- [x] 2.1
- [x] 2.0
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../sql-data-types/semi-structured/JSON.md | 33 ++++++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 8 +++++-
.../sql-data-types/semi-structured/JSON.md | 26 +++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 4 +++
.../sql-data-types/semi-structured/JSON.md | 26 ++++++++++++++++-
.../sql-data-types/semi-structured/JSON.md | 26 +++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 4 +++
.../sql-data-types/semi-structured/JSON.md | 26 +++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 5 ++++
.../sql-data-types/semi-structured/JSON.md | 32 +++++++++++++++++++++
.../sql-data-types/semi-structured/JSON.md | 32 +++++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 8 +++++-
.../sql-data-types/semi-structured/JSON.md | 32 +++++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 9 ++++--
14 files changed, 266 insertions(+), 5 deletions(-)
diff --git
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index 3248266702d..27262685c06 100644
--- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -851,6 +851,39 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+
+1. Is there a difference between null in JSON and NULL in SQL (i.e., IS NULL)?
+
+Yes, there is a difference. In JSON, null (e.g., {"key1": null}) means that
the key key1 exists and its value is explicitly null. This is a special type
that gets encoded into JSON binary.
+
+In contrast, SQL NULL (when using IS NULL) can indicate that the key doesn’t
exist at all in the JSON object.
+
+For example:
+
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. What’s the difference between `GET_JSON_XXX` and `JSON_EXTRACT_XXX`
functions, and how should I choose between them?
+
+The `GET_JSON_XXX` functions are designed for use on string types — they
extract values directly from raw JSON strings. On the other hand,
`JSON_EXTRACT_XXX` functions are implemented specifically for the JSON data
type and are optimized for it.
+
+
### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_string,
json_exists_path, json_type
diff --git
a/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 8dc006e7d7b..70a8cd985a9 100644
--- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -468,9 +468,15 @@ SELECT * FROM example_table WHERE data_string LIKE
'%doris%'
```
### FAQ
-1.Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
+1. Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
Due to compaction and metadata storage limitations, the VARIANT type imposes a
limit on the number of columns, with the default being 2048 columns. You can
adjust the BE configuration `variant_max_merged_tablet_schema_size`
accordingly, but it is not recommended to exceed 4096 columns.
+2. Is there a difference between null in the VARIANT type (e.g., `{"key":
null}`) and SQL NULL (i.e., IS NULL)?
+
+No, there is no difference — in the VARIANT type, they are considered
equivalent.
+
### Keywords
VARIANT
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index bb17a68c0ac..cea40dff7c5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -850,5 +850,31 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+1. JSON类型中的null和SQL中的NULL(IS NULL)有区别吗
+
+是的,JSON中的null例如`{"key1" : nulll}`表示`key1`这个JSON键存在,并且值为null(作为一个特殊类型会被编码到JSON
binary中),而SQL中的NULL是指没有这个JSON键。例如
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. `GET_JSON_XXX` 函数和 `JSON_EXTRACT_XXX` 函数的区别,以及怎么选择
+
+`GET_JSON_XXX` 是针对字符串类型设计的函数,是直接在原生字符串上做提取操作,而 `JSON_EXTRACT_XXX` 是针对 JSON
类型实现的函数,针对 JSON 类型有特殊优化。一般建议使用 `JSON_EXTRACT_XXX` 性能会更好。
+
### keywords
JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_String,
json_exists_path, json_type
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 2217944e760..291017ee45e 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -461,8 +461,12 @@ SELECT * FROM example_table WHERE data_string LIKE
'%doris%';
### FAQ
1. Stream Load 报错: [CANCELLED][INTERNAL_ERROR]tablet error:
[DATA_QUALITY_ERROR]Reached max column size limit 2048。
+
由于 Compaction 和元信息存储限制,VARIANT 类型会限制列数,默认 2048 列,可以适当调整 BE 配置
`variant_max_merged_tablet_schema_size` ,但是不建议超过 4096
+2. VARIANT 类型中的 null(例如 `{"key": null}` )和 SQL 中的 NULL(即 IS NULL)有区别吗?
+
+没有区别,在 VARIANT 类型中,它们被视为等价的。
### Keywords
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
index 1026c8dd661..6f4232c0122 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
@@ -848,4 +848,28 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
-
+### FAQ
+1. JSON类型中的null和SQL中的NULL(IS NULL)有区别吗
+
+是的,JSON中的null例如`{"key1" : nulll}`表示`key1`这个JSON键存在,并且值为null(作为一个特殊类型会被编码到JSON
binary中),而SQL中的NULL是指没有这个JSON键。例如
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. `GET_JSON_XXX` 函数和 `JSON_EXTRACT_XXX` 函数的区别,以及怎么选择
+
+`GET_JSON_XXX` 是针对字符串类型设计的函数,是直接在原生字符串上做提取操作,而 `JSON_EXTRACT_XXX` 是针对 JSON
类型实现的函数,针对 JSON 类型有特殊优化。一般建议使用 `JSON_EXTRACT_XXX` 性能会更好。
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index bb17a68c0ac..cea40dff7c5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -850,5 +850,31 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+1. JSON类型中的null和SQL中的NULL(IS NULL)有区别吗
+
+是的,JSON中的null例如`{"key1" : nulll}`表示`key1`这个JSON键存在,并且值为null(作为一个特殊类型会被编码到JSON
binary中),而SQL中的NULL是指没有这个JSON键。例如
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. `GET_JSON_XXX` 函数和 `JSON_EXTRACT_XXX` 函数的区别,以及怎么选择
+
+`GET_JSON_XXX` 是针对字符串类型设计的函数,是直接在原生字符串上做提取操作,而 `JSON_EXTRACT_XXX` 是针对 JSON
类型实现的函数,针对 JSON 类型有特殊优化。一般建议使用 `JSON_EXTRACT_XXX` 性能会更好。
+
### keywords
JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_String,
json_exists_path, json_type
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 6765986a99f..ac86cae549a 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -461,8 +461,12 @@ SELECT * FROM example_table WHERE data_string LIKE
'%doris%';
### FAQ
1. Stream Load 报错: [CANCELLED][INTERNAL_ERROR]tablet error:
[DATA_QUALITY_ERROR]Reached max column size limit 2048。
+
由于 Compaction 和元信息存储限制,VARIANT 类型会限制列数,默认 2048 列,可以适当调整 BE 配置
`variant_max_merged_tablet_schema_size` ,但是不建议超过 4096
+2. VARIANT 类型中的 null(例如 `{"key": null}` )和 SQL 中的 NULL(即 IS NULL)有区别吗?
+
+没有区别,在 VARIANT 类型中,它们被视为等价的。
### Keywords
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index bb17a68c0ac..cea40dff7c5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -850,5 +850,31 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+1. JSON类型中的null和SQL中的NULL(IS NULL)有区别吗
+
+是的,JSON中的null例如`{"key1" : nulll}`表示`key1`这个JSON键存在,并且值为null(作为一个特殊类型会被编码到JSON
binary中),而SQL中的NULL是指没有这个JSON键。例如
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. `GET_JSON_XXX` 函数和 `JSON_EXTRACT_XXX` 函数的区别,以及怎么选择
+
+`GET_JSON_XXX` 是针对字符串类型设计的函数,是直接在原生字符串上做提取操作,而 `JSON_EXTRACT_XXX` 是针对 JSON
类型实现的函数,针对 JSON 类型有特殊优化。一般建议使用 `JSON_EXTRACT_XXX` 性能会更好。
+
### keywords
JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_String,
json_exists_path, json_type
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 0aaf377b565..162fe96f540 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -473,8 +473,13 @@ SELECT * FROM example_table WHERE data_string LIKE
'%doris%';
### FAQ
1. Stream Load 报错: [CANCELLED][INTERNAL_ERROR]tablet error:
[DATA_QUALITY_ERROR]Reached max column size limit 2048。
+
由于 Compaction 和元信息存储限制,VARIANT 类型会限制列数,默认 2048 列,可以适当调整 BE 配置
`variant_max_merged_tablet_schema_size` ,但是不建议超过 4096
+2. VARIANT 类型中的 null(例如 `{"key": null}` )和 SQL 中的 NULL(即 IS NULL)有区别吗?
+
+没有区别,在 VARIANT 类型中,它们被视为等价的。
+
### Keywords
diff --git
a/versioned_docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
b/versioned_docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
index 4ce84debda6..6aa8097185a 100644
---
a/versioned_docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
+++
b/versioned_docs/version-2.0/sql-manual/sql-data-types/semi-structured/JSON.md
@@ -848,6 +848,38 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+
+1. Is there a difference between null in JSON and NULL in SQL (i.e., IS NULL)?
+
+Yes, there is a difference. In JSON, null (e.g., {"key1": null}) means that
the key key1 exists and its value is explicitly null. This is a special type
that gets encoded into JSON binary.
+
+In contrast, SQL NULL (when using IS NULL) can indicate that the key doesn’t
exist at all in the JSON object.
+
+For example:
+
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. What’s the difference between `GET_JSON_XXX` and `JSON_EXTRACT_XXX`
functions, and how should I choose between them?
+
+The `GET_JSON_XXX` functions are designed for use on string types — they
extract values directly from raw JSON strings. On the other hand,
`JSON_EXTRACT_XXX` functions are implemented specifically for the JSON data
type and are optimized for it.
+
### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_string,
json_exists_path, json_type
diff --git
a/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index 3248266702d..673da032a0a 100644
---
a/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++
b/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -851,6 +851,38 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+
+1. Is there a difference between null in JSON and NULL in SQL (i.e., IS NULL)?
+
+Yes, there is a difference. In JSON, null (e.g., {"key1": null}) means that
the key key1 exists and its value is explicitly null. This is a special type
that gets encoded into JSON binary.
+
+In contrast, SQL NULL (when using IS NULL) can indicate that the key doesn’t
exist at all in the JSON object.
+
+For example:
+
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. What’s the difference between `GET_JSON_XXX` and `JSON_EXTRACT_XXX`
functions, and how should I choose between them?
+
+The `GET_JSON_XXX` functions are designed for use on string types — they
extract values directly from raw JSON strings. On the other hand,
`JSON_EXTRACT_XXX` functions are implemented specifically for the JSON data
type and are optimized for it.
+
### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_string,
json_exists_path, json_type
diff --git
a/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 17f60a219db..d27be79209a 100644
---
a/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/versioned_docs/version-2.1/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -456,9 +456,15 @@ SELECT * FROM example_table WHERE data_string LIKE
'%doris%'
```
### FAQ
-1.Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
+1. Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
Due to compaction and metadata storage limitations, the VARIANT type imposes a
limit on the number of columns, with the default being 2048 columns. You can
adjust the BE configuration `variant_max_merged_tablet_schema_size`
accordingly, but it is not recommended to exceed 4096 columns.
+2. Is there a difference between null in the VARIANT type (e.g., `{"key":
null}`) and SQL NULL (i.e., IS NULL)?
+
+No, there is no difference — in the VARIANT type, they are considered
equivalent.
+
### Keywords
VARIANT
diff --git
a/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
b/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
index 3248266702d..673da032a0a 100644
---
a/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
+++
b/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/JSON.md
@@ -851,6 +851,38 @@ mysql> select id, j, json_type(j, '$.k1') from test_json
order by id;
```
+### FAQ
+
+1. Is there a difference between null in JSON and NULL in SQL (i.e., IS NULL)?
+
+Yes, there is a difference. In JSON, null (e.g., {"key1": null}) means that
the key key1 exists and its value is explicitly null. This is a special type
that gets encoded into JSON binary.
+
+In contrast, SQL NULL (when using IS NULL) can indicate that the key doesn’t
exist at all in the JSON object.
+
+For example:
+
+``` sql
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL;
++----------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key1") IS NULL |
++----------------------------------------------------------+
+| 0 |
++----------------------------------------------------------+
+1 row in set (0.00 sec)
+
+mysql> SELECT JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS
NULL;
++-------------------------------------------------------------------+
+| JSON_EXTRACT_STRING('{"key1" : null}', "$.key_not_exist") IS NULL |
++-------------------------------------------------------------------+
+| 1 |
++-------------------------------------------------------------------+
+1 row in set (0.01 sec)
+```
+
+2. What’s the difference between `GET_JSON_XXX` and `JSON_EXTRACT_XXX`
functions, and how should I choose between them?
+
+The `GET_JSON_XXX` functions are designed for use on string types — they
extract values directly from raw JSON strings. On the other hand,
`JSON_EXTRACT_XXX` functions are implemented specifically for the JSON data
type and are optimized for it.
+
### keywords
JSONB, JSON, json_parse, json_parse_error_to_null, json_parse_error_to_value,
json_extract, json_extract_isnull, json_extract_bool, json_extract_int,
json_extract_bigint, json_extract_double, json_extract_string,
json_exists_path, json_type
diff --git
a/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 9bda2180363..d27be79209a 100644
---
a/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/versioned_docs/version-3.0/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -455,11 +455,16 @@ CREATE TABLE example_table (
SELECT * FROM example_table WHERE data_string LIKE '%doris%'
```
-
### FAQ
-1.Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
+1. Streamload Error: [CANCELLED][INTERNAL_ERROR] tablet error:
[DATA_QUALITY_ERROR] Reached max column size limit 2048.
+
Due to compaction and metadata storage limitations, the VARIANT type imposes a
limit on the number of columns, with the default being 2048 columns. You can
adjust the BE configuration `variant_max_merged_tablet_schema_size`
accordingly, but it is not recommended to exceed 4096 columns.
+2. Is there a difference between null in the VARIANT type (e.g., `{"key":
null}`) and SQL NULL (i.e., IS NULL)?
+
+No, there is no difference — in the VARIANT type, they are considered
equivalent.
+
### Keywords
VARIANT
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]