yiguolei commented on code in PR #4001:
URL: https://github.com/apache/doris-website/pull/4001#discussion_r3619341023
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md:
##########
@@ -67,6 +67,109 @@ FROM ${table_name}
WHERE ARRAY_CONTAINS(CAST(v['tags'] AS ARRAY<TEXT>), 'Doris');
```
+## 创建和访问值
+
+VARIANT 值可以从 JSON 文本或带确定类型的 SQL 表达式创建：
+
+- 如果字符串中包含需要解析的 JSON 文本，请使用
[PARSE_TO_VARIANT](../../../sql-functions/scalar-functions/variant-functions/parse-to-variant)。
+- 如果要将 SQL 值转换为带类型的 Variant 值，请使用 `CAST(expression AS VARIANT)`。字符串 CAST
不会把字符串按 JSON 解析。
+
+### 解析 JSON 文本
+
+```sql
+SELECT PARSE_TO_VARIANT('{\"user\": {\"id\": 42}, \"active\": true}');
+SELECT PARSE_TO_VARIANT('[10, 20, 30]');
+```
+
+如果非法 JSON 应该返回 SQL `NULL` 而不是使查询失败，请使用
[PARSE_TO_VARIANT_ERROR_TO_NULL](../../../sql-functions/scalar-functions/variant-functions/parse-to-variant-error-to-null)。
+
+### 访问对象和数组
+
+对象字段可以使用字符串 key 访问。开启 VARIANT V2 后，VARIANT 数组的非负索引从 0
开始，并支持从数组末尾倒数的负数索引。提取出的值仍是 `VARIANT`，如需按确定类型比较或聚合，请先 CAST。
+
+```sql
+SET enable_variant_v2 = true;
+
+SELECT CAST(PARSE_TO_VARIANT('{\"user\": {\"id\": 42}}')['user']['id'] AS
BIGINT);
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), 0); -- 10
+SELECT ELEMENT_AT(PARSE_TO_VARIANT('[10, 20, 30]'), -1); -- 30
+```
+
+对象和数组访问的详细说明请参见
[ELEMENT_AT](../../../sql-functions/scalar-functions/variant-functions/element-at)。
+## CAST 语义
+
+`CAST` 会保留 SQL 字符串和 JSON 文本之间的区别：
+
+- `CAST(string AS VARIANT)` 创建根值为“带类型的 Variant 字符串”的 Variant，**不会**解析
JSON。因此，`'{"id": 1}'` 会保持为一个字符串值，非法 JSON 文本对这个 CAST 仍然是合法输入。
+- `PARSE_TO_VARIANT(string)` 才会把字符串按 JSON 解析；解析为对象或数组后，才能继续使用路径访问或
`ELEMENT_AT`。如果非法 JSON 需要返回 SQL `NULL`，请使用 `PARSE_TO_VARIANT_ERROR_TO_NULL`。
+- `CAST(PARSE_TO_VARIANT(...) AS scalar)` 会在值形状和范围兼容时，把已经解析的 Variant 转换为确定的
SQL 标量类型。这个 CAST 不是 JSON 解析器，形状或范围不兼容时可能失败。
+- `CAST(typed_expression AS VARIANT)` 会把受支持的带类型 SQL 值转换为 Variant。开启
`enable_variant_v2` 只会改变当前 session 的执行表示，不会改变磁盘上的 Variant 存储、reader、writer 或
compaction。
+
+```sql
+SET enable_variant_v2 = true;
+
+SELECT CAST('{"id": 1}' AS VARIANT) AS typed_string,
+ PARSE_TO_VARIANT('{"id": 1}') AS parsed_object;
+-- typed_string：字面量字符串 {"id": 1}
+-- parsed_object：{"id": 1}
+
+SELECT ELEMENT_AT(CAST('{"id": 1}' AS VARIANT), 'id') AS from_string,
+ ELEMENT_AT(PARSE_TO_VARIANT('{"id": 1}'), 'id') AS from_json;
+-- from_string：NULL；from_json：1
+
+SELECT CAST(PARSE_TO_VARIANT('42') AS BIGINT) AS id;
+-- id：42
+
+SELECT CAST('{invalid json' AS VARIANT) AS still_a_string;
+-- 成功，因为 CAST 不会把输入按 JSON 解析
+```
+
+不要使用 `CAST(string AS VARIANT)` 做 JSON 校验。需要严格解析时使用
`PARSE_TO_VARIANT`；需要把格式错误转换为 SQL `NULL` 时使用 `PARSE_TO_VARIANT_ERROR_TO_NULL`。
+
+## Equality 语义
+
+开启 VARIANT V2 后，支持的分组、去重和集合运算会按 logical value 判断相等性，而不是按来源 SQL 类型或表示形式：
Review Comment:
需要补充一下关于join，order by，group by的支持情况；
hash 值计算的情况
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
