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 0a1b0e8f515 [doc](variant) Document top-level column name restrictions
(#4307)
0a1b0e8f515 is described below
commit 0a1b0e8f51533d31accde6e8ae4770dd5f225636
Author: lihangyu <[email protected]>
AuthorDate: Thu Oct 15 11:09:12 2026 +0800
[doc](variant) Document top-level column name restrictions (#4307)
Document that top-level VARIANT column names cannot contain dots,
including backtick-quoted names, and that the restriction applies to
CREATE and ALTER (single/batch ADD, MODIFY, and RENAME). Clarify that
JSON field names inside VARIANT values are unaffected and add an ALTER
error example.
Update the current and 4.x English references and their Chinese
counterparts together. Related fixes: apache/doris#69088 (master) and
apache/doris#69077 (4.1 backport).
Validation: all four edited documents compile with MDX; front matter and
heading anchors are unchanged; git diff --check passes. Checked behavior
against the fix and existing dotted JSON-key regression coverage. No
full website build was run.
---
.../basic-element/sql-data-types/semi-structured/VARIANT.md | 8 ++++++++
.../basic-element/sql-data-types/semi-structured/VARIANT.md | 8 ++++++++
.../basic-element/sql-data-types/semi-structured/VARIANT.md | 9 +++++++++
.../basic-element/sql-data-types/semi-structured/VARIANT.md | 9 +++++++++
4 files changed, 34 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 e7ba1fbf7c9..c2c531fbcf6 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
@@ -81,6 +81,7 @@ field_definition:
- The `field_definition` list is the [Schema Template](#schema-template). It
fixes the storage type of selected paths.
- `properties(...)` sets column-level storage properties. See [Column
properties](#column-properties).
- A VARIANT column can be `NULL` or `NOT NULL`. Its only allowed default value
is `NULL`.
+- A top-level VARIANT column name cannot contain a dot (`.`), even when quoted
with backticks: for example, `` `v.x` VARIANT `` is invalid. This restriction
applies to `CREATE TABLE` and `ALTER TABLE`; it does not restrict JSON field
names inside a VARIANT value.
```sql
CREATE TABLE IF NOT EXISTS example_tbl (
@@ -543,6 +544,13 @@ The Schema Template cannot be changed after the column is
created. See [ALTER TA
## ALTER TABLE
+`ADD COLUMN` (including batch additions), `MODIFY COLUMN`, and `RENAME COLUMN`
must also use a top-level VARIANT column name without dots. For example, the
following statement is rejected:
+
+```sql
+ALTER TABLE example_tbl ADD COLUMN `v.x` VARIANT;
+-- ERROR: Cannot use `VARIANT` type column named with a `.` character: v.x
+```
+
`ALTER TABLE` supports:
- `ADD COLUMN` of a nullable VARIANT column, with or without a Schema Template
and properties.
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 166b270385f..1838e4cf5f6 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
@@ -81,6 +81,7 @@ field_definition:
- `field_definition` 列表就是 [Schema Template](#schema-template)，用于固定部分路径的存储类型。
- `properties(...)` 用于设置列级存储属性，参见[列属性](#column-properties)。
- VARIANT 列可以是 `NULL` 或 `NOT NULL`，默认值只能是 `NULL`。
+- VARIANT 顶层列名不能包含点号（`.`），使用反引号引用也不允许，例如 `` `v.x` VARIANT `` 是非法列定义。该限制适用于
`CREATE TABLE` 和 `ALTER TABLE`，不限制 VARIANT 值中的 JSON 字段名。
```sql
CREATE TABLE IF NOT EXISTS example_tbl (
@@ -543,6 +544,13 @@ v1 VARIANT<
## ALTER TABLE {#alter-table}
+`ADD COLUMN`（含批量添加）、`MODIFY COLUMN` 和 `RENAME COLUMN` 同样要求 VARIANT
顶层列名不含点号。例如，以下语句会被拒绝：
+
+```sql
+ALTER TABLE example_tbl ADD COLUMN `v.x` VARIANT;
+-- ERROR: Cannot use `VARIANT` type column named with a `.` character: v.x
+```
+
`ALTER TABLE` 支持：
- `ADD COLUMN` 新增可为 NULL 的 VARIANT 列，可以带 Schema Template 和属性。
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 12a06f925b6..e842c7182d3 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
@@ -36,6 +36,15 @@ CREATE TABLE IF NOT EXISTS ${table_name} (
PROPERTIES("replication_num" = "1");
```
+VARIANT 顶层列名不能包含点号（`.`），使用反引号引用也不允许，例如 `` `v.x` VARIANT `` 是非法列定义。该限制适用于
`CREATE TABLE` 和 `ALTER TABLE`，不限制 VARIANT 值中的 JSON 字段名。
+
+`ADD COLUMN`（含批量添加）、`MODIFY COLUMN` 和 `RENAME COLUMN` 同样要求 VARIANT
顶层列名不含点号。例如，以下语句会被拒绝：
+
+```sql
+ALTER TABLE ${table_name} ADD COLUMN `v.x` VARIANT;
+-- ERROR: Cannot use `VARIANT` type column named with a `.` character: v.x
+```
+
通过 Schema Template 约束部分 Path 的类型（更多见“扩展类型”）：
```sql
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 dc1d3f053fd..9e4f4765293 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
@@ -36,6 +36,15 @@ CREATE TABLE IF NOT EXISTS ${table_name} (
PROPERTIES("replication_num" = "1");
```
+A top-level VARIANT column name cannot contain a dot (`.`), even when quoted
with backticks: for example, `` `v.x` VARIANT `` is invalid. This restriction
applies to `CREATE TABLE` and `ALTER TABLE`; it does not restrict JSON field
names inside a VARIANT value.
+
+`ADD COLUMN` (including batch additions), `MODIFY COLUMN`, and `RENAME COLUMN`
must also use a top-level VARIANT column name without dots. For example, the
following statement is rejected:
+
+```sql
+ALTER TABLE ${table_name} ADD COLUMN `v.x` VARIANT;
+-- ERROR: Cannot use `VARIANT` type column named with a `.` character: v.x
+```
+
Constrain certain paths with a Schema Template (see “Extended types”):
```sql
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
