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 73b50dc5efc [doc] note VARIANT output sorts JSON object keys (#3841)
73b50dc5efc is described below
commit 73b50dc5efcc10833b087c3a571fa2b9348545de
Author: Chenyang Sun <[email protected]>
AuthorDate: Fri May 29 11:20:05 2026 +0800
[doc] note VARIANT output sorts JSON object keys (#3841)
Add an Output section after INSERT and load in the VARIANT type
reference to flag that the JSON returned on read is not byte-identical
to the input and that object keys are emitted in sorted order at every
nesting level. Applied to current/3.x/4.x EN and zh-CN.
## Versions
- [x] dev
- [x] 4.x
- [x] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
- [ ] Japanese candidate translation needed
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
.../sql-data-types/semi-structured/VARIANT.md | 18 ++++++++++++++++++
6 files changed, 108 insertions(+)
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 46856616e28..227fa747696 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
@@ -369,6 +369,24 @@ See also:
`https://doris.apache.org/docs/dev/data-operate/import/complex-types/v
After loading, verify with `SELECT count(*)` or sample with `SELECT * ...
LIMIT 1`. For high-throughput ingestion, prefer RANDOM bucketing and enable
Group Commit.
+## Output
+
+The JSON text returned when reading a VARIANT column is not byte-for-byte
identical to the JSON text that was written in: inside a JSON object, keys are
emitted in sorted (lexicographic) order regardless of the order they appeared
in the input JSON.
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+Sorting applies at every level — top-level keys become `a`, `b`, `c`, and the
nested object's keys become `x`, `y`.
+
## Supported operations and CAST rules
- VARIANT cannot be compared/operated directly with other types; comparisons
between two VARIANTs are not supported either.
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 a13a39bcaa8..344db4f2d6b 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
@@ -369,6 +369,24 @@ curl --location-trusted -u root: -T gh_2022-11-07-3.json \
导入完成后可用 `SELECT count(*)` 或 `SELECT * ... LIMIT 1` 验证。为提升高并发导入性能，推荐建表选择 RANDOM
分桶并开启 Group Commit（参见官方“Group Commit”文档）。
+## 输出
+
+从 VARIANT 列读出的 JSON 文本与写入时的 JSON 文本并非按字节完全一致：JSON object 内的 key 会按字典序输出，与输入
JSON 中的顺序无关。
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+排序在每一层都会生效——顶层 key 输出为 `a`、`b`、`c`，嵌套 object 内 key 输出为 `x`、`y`。
+
## 支持的运算与 CAST 规则
- VARIANT 本身不支持与其他类型直接比较/运算，两个 VARIANT 之间也不支持直接比较。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 4432a9ef001..76f24106ce9 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -422,6 +422,24 @@ curl --location-trusted -u root: -T gh_2022-11-07-3.json \
导入完成后可用 `SELECT count(*)` 或 `SELECT * ... LIMIT 1` 验证。为提升高并发导入性能，推荐建表选择 RANDOM
分桶并开启 Group Commit（参见官方“Group Commit”文档）。
+## 输出
+
+从 VARIANT 列读出的 JSON 文本与写入时的 JSON 文本并非按字节完全一致：JSON object 内的 key 会按字典序输出，与输入
JSON 中的顺序无关。
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+排序在每一层都会生效——顶层 key 输出为 `a`、`b`、`c`，嵌套 object 内 key 输出为 `x`、`y`。
+
## 支持的运算与 CAST 规则
- VARIANT 本身不支持与其他类型直接比较/运算，两个 VARIANT 之间也不支持直接比较。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index a13a39bcaa8..344db4f2d6b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -369,6 +369,24 @@ curl --location-trusted -u root: -T gh_2022-11-07-3.json \
导入完成后可用 `SELECT count(*)` 或 `SELECT * ... LIMIT 1` 验证。为提升高并发导入性能，推荐建表选择 RANDOM
分桶并开启 Group Commit（参见官方“Group Commit”文档）。
+## 输出
+
+从 VARIANT 列读出的 JSON 文本与写入时的 JSON 文本并非按字节完全一致：JSON object 内的 key 会按字典序输出，与输入
JSON 中的顺序无关。
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+排序在每一层都会生效——顶层 key 输出为 `a`、`b`、`c`，嵌套 object 内 key 输出为 `x`、`y`。
+
## 支持的运算与 CAST 规则
- VARIANT 本身不支持与其他类型直接比较/运算，两个 VARIANT 之间也不支持直接比较。
diff --git
a/versioned_docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/versioned_docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index b8677ece933..7d3addbf52f 100644
---
a/versioned_docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/versioned_docs/version-3.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -422,6 +422,24 @@ See also:
`https://doris.apache.org/docs/dev/data-operate/import/complex-types/v
After loading, verify with `SELECT count(*)` or sample with `SELECT * ...
LIMIT 1`. For high-throughput ingestion, prefer RANDOM bucketing and enable
Group Commit.
+## Output
+
+The JSON text returned when reading a VARIANT column is not byte-for-byte
identical to the JSON text that was written in: inside a JSON object, keys are
emitted in sorted (lexicographic) order regardless of the order they appeared
in the input JSON.
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+Sorting applies at every level — top-level keys become `a`, `b`, `c`, and the
nested object's keys become `x`, `y`.
+
## Supported operations and CAST rules
- VARIANT cannot be compared/operated directly with other types; comparisons
between two VARIANTs are not supported either.
diff --git
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
index 46856616e28..227fa747696 100644
---
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
+++
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md
@@ -369,6 +369,24 @@ See also:
`https://doris.apache.org/docs/dev/data-operate/import/complex-types/v
After loading, verify with `SELECT count(*)` or sample with `SELECT * ...
LIMIT 1`. For high-throughput ingestion, prefer RANDOM bucketing and enable
Group Commit.
+## Output
+
+The JSON text returned when reading a VARIANT column is not byte-for-byte
identical to the JSON text that was written in: inside a JSON object, keys are
emitted in sorted (lexicographic) order regardless of the order they appeared
in the input JSON.
+
+```sql
+INSERT INTO variant_tbl VALUES
+ (2, '{ "b": 2, "a": 1, "c": { "y": 20, "x": 10 } }');
+
+SELECT v FROM variant_tbl WHERE k = 2;
++-----------------------------------+
+| v |
++-----------------------------------+
+| {"a":1,"b":2,"c":{"x":10,"y":20}} |
++-----------------------------------+
+```
+
+Sorting applies at every level — top-level keys become `a`, `b`, `c`, and the
nested object's keys become `x`, `y`.
+
## Supported operations and CAST rules
- VARIANT cannot be compared/operated directly with other types; comparisons
between two VARIANTs are not supported either.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
