eldenmoon commented on code in PR #4170:
URL: https://github.com/apache/doris-website/pull/4170#discussion_r4079878941
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/VARIANT.md:
##########
@@ -19,269 +17,511 @@ VARIANT 类型用于存储半结构化 JSON 数据，可包含不同基础类型
- 关键路径可以建立路径级索引，支持全文检索，同时继续受益于 Doris 的稀疏索引裁剪能力。
-
面向宽列场景的存储优化，让万级子列规模的自动子列列式提取（Subcolumnization）保持可用。若参与子列列式提取（Subcolumnization）的路径接近
10000，对硬件要求会明显提高，通常应优先评估 DOC mode。
-如果你还在决定默认模式、Sparse、DOC mode 还是 Schema Template，建议先阅读 [VARIANT
使用与配置指南](./variant-workload-guide)。本页主要提供语法、类型规则、索引、限制和配置参考。
+如果你还在决定默认模式、Sparse、DOC mode 还是 Schema Template，建议先阅读 [VARIANT
使用与配置指南](./variant-workload-guide.md)。本页提供写入与解析、类型规则、CAST、NULL
与比较语义、ALTER、索引、限制和配置的参考。
:::
-## 使用 VARIANT 类型
+:::info 版本说明
+本页描述 Doris 5.0.0 及之后版本中的 VARIANT。与 Doris 4.x 相比，最容易影响已有 SQL 的差异有：
+
+- `INSERT` 会把字符串作为 VARIANT 字符串写入，不再按 JSON 解析，从 `s3()`、`hdfs()` 等表函数执行 `INSERT
INTO ... SELECT` 也是如此。用 `INSERT` 写入 JSON 文本时请使用 `PARSE_TO_VARIANT`；Stream Load
等导入作业仍会解析 JSON。
+- 整个 VARIANT 值支持 `GROUP BY`、`DISTINCT` 和集合运算；两个 VARIANT 值之间可以用 `=`、`!=`、`<=>`
比较，也可以作为 Join 键、`ORDER BY` 键和窗口键。
+- 即使路径在 Schema Template 中声明了类型，`v['path']` 仍是 `VARIANT` 类型，需要显式 CAST。会话变量
`enable_variant_schema_auto_cast` 已不再生效。
+- `VARIANT_TYPE` 返回单个类型名称（如 `object`），不再返回从路径到类型的映射。
+- VARIANT 数组可以用整数下标访问，下标从 1 开始。
-### 建表语法
+Doris 4.x 的行为请参阅本页的 4.x 版本。
+:::
-建表时将列类型声明为 VARIANT：
+## 快速上手 {#quick-start}
```sql
-CREATE TABLE IF NOT EXISTS ${table_name} (
- k BIGINT,
- v VARIANT
+CREATE TABLE events (
+ id BIGINT,
+ v VARIANT
)
-PROPERTIES("replication_num" = "1");
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+-- INSERT 会把字符串字面量保留为 VARIANT 字符串，因此 JSON 文本需要显式解析。
+INSERT INTO events VALUES
+ (1, PARSE_TO_VARIANT('{"user": {"id": 42, "name": "alice"}, "tags":
["doris", "sql"], "score": 9.5}')),
+ (2, PARSE_TO_VARIANT('{"user": {"id": 7, "name": "bob"}, "score": 3}'));
+
+SELECT id,
+ CAST(v['user']['name'] AS STRING) AS name,
+ v['tags'][1] AS first_tag
+FROM events
+WHERE CAST(v['score'] AS DOUBLE) > 5;
+```
+
+```text
++------+-------+-----------+
+| id | name | first_tag |
++------+-------+-----------+
+| 1 | alice | doris |
++------+-------+-----------+
+```
+
+- `v['user']['name']` 和 `v['tags'][1]` 返回 `VARIANT` 值。数组下标从 1 开始。
+- 对路径做比较或计算之前，先把它 CAST 为具体类型。`v['score'] > 5`
通过[隐式转换](#implicit-conversion)也能执行，但它按 `DECIMAL(38, 9)` 比较，而且无法利用索引。
+- Stream Load 等导入作业会自动解析 JSON 文本。参见[写入数据](#write-data)。
+
+## 定义 VARIANT 列 {#define-a-variant-column}
+
+```sql
+column_name VARIANT
+column_name VARIANT< field_definition [, field_definition ...] >
+column_name VARIANT< properties('key' = 'value' [, ...]) >
+column_name VARIANT< field_definition [, ...], properties('key' = 'value' [,
...]) >
+
+field_definition:
+ [MATCH_NAME | MATCH_NAME_GLOB] 'path_or_pattern' : data_type [COMMENT
'comment']
```
-通过 Schema Template 约束部分 Path 的类型（更多见“扩展类型”）：
+- `field_definition` 列表就是 [Schema Template](#schema-template)，用于固定部分路径的存储类型。
+- `properties(...)` 用于设置列级存储属性，参见[列属性](#column-properties)。
+- VARIANT 列可以是 `NULL` 或 `NOT NULL`，默认值只能是 `NULL`。
```sql
-CREATE TABLE IF NOT EXISTS ${table_name} (
+CREATE TABLE IF NOT EXISTS example_tbl (
k BIGINT,
- v VARIANT <
- 'id' : INT, -- path 为 id 的子列被限制为 INT 类型
- 'message*' : STRING, -- 前缀匹配 message* 的子列被限制为 STRING 类型
- 'tags*' : ARRAY<TEXT> -- 前缀匹配 tags* 的子列被限制为 ARRAY<TEXT> 类型
- >
+ v VARIANT<
+ 'id' : INT, -- 路径 id 以 INT 存储
+ 'message*' : STRING, -- 匹配 message* 的路径以 STRING 存储
+ 'tags*' : ARRAY<TEXT>, -- 匹配 tags* 的路径以 ARRAY<TEXT> 存储
+ properties('variant_max_subcolumns_count' = '2048')
+ > NULL
)
-PROPERTIES("replication_num" = "1");
+DUPLICATE KEY(k)
+DISTRIBUTED BY HASH(k) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
```
-### 查询语法
+VARIANT 列在表中的使用范围：
+
+| 用法 | 是否支持 | 说明 |
+| --- | --- | --- |
+| Duplicate Key、Unique Key、Aggregate Key 表的 Value 列 | 支持 | 在 Aggregate Key
表中，聚合类型必须是 `REPLACE` 或 `REPLACE_IF_NOT_NULL`。 |
+| Key 列、分区列、分桶列 | 不支持 | |
+| 在表结构中嵌套在其他类型内（`ARRAY<VARIANT>`、`MAP`、`STRUCT`） | 不支持 | 查询结果仍可以是
`ARRAY<VARIANT>`，例如 `COLLECT_LIST(v)` 的结果。 |
+| 默认值 | 只能是 `NULL` | `DEFAULT '{}'` 等非 NULL 默认值会被拒绝。 |
+
+## 写入数据 {#write-data}
+
+### 输入如何变成 VARIANT 值 {#how-input-becomes-a-variant-value}
Review Comment:
“输入如何变成 VARIANT 值 ”， 这段不保留删了
--
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]
