This is an automated email from the ASF dual-hosted git repository.
yiguolei 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 50f785a1e1d [doc](struct) match STRUCT sub-fields by name in cast from
string (#3907)
50f785a1e1d is described below
commit 50f785a1e1db311be32ef91ac53890c827916483
Author: Chenyang Sun <[email protected]>
AuthorDate: Mon Jun 8 09:55:24 2026 +0800
[doc](struct) match STRUCT sub-fields by name in cast from string (#3907)
Document the behavior change from apache/doris#64011: when casting a
string to STRUCT with field names fields are now matched by name
(case-insensitive) instead of by position.
The input field order may differ from the schema, missing fields are
filled with NULL, and unknown fields are rejected in strict mode /
ignored in non-strict mode.
## Versions
- [x] dev
- [x] 4.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.8 (1M context) <[email protected]>
---
.../sql-data-types/conversion/struct-conversion.md | 35 ++++++++++++++--------
.../sql-data-types/conversion/struct-conversion.md | 35 ++++++++++++++--------
.../sql-data-types/conversion/struct-conversion.md | 35 ++++++++++++++--------
.../sql-data-types/conversion/struct-conversion.md | 35 ++++++++++++++--------
4 files changed, 88 insertions(+), 52 deletions(-)
diff --git
a/docs/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
b/docs/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
index 69d4f380610..e667e662e42 100644
---
a/docs/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
+++
b/docs/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
@@ -46,12 +46,14 @@ STRUCT type is used to store and process structured data,
which can contain fiel
5. Field-value pairs must either all use the "fieldname:value" format or all
use the "value" format.
6. Field names and values can optionally be enclosed in matching single quotes
(`'`) or double quotes (`"`). The content inside the quotes is treated as a
single entity.
7. Whitespace is allowed before and after elements within the STRUCT.
-8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. If there are `<field-token>` parts, they must
match the number and order of names defined in the STRUCT.
+8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. How `<field-token>` parts are handled depends
on whether field names are provided:
+ - **When field names are provided:** fields are matched **by name**,
case-insensitively. The order of the input fields does **not** need to match
the order defined in the STRUCT. Fields defined in the STRUCT but missing from
the input are filled with NULL. In strict mode, an input field name that does
not exist in the STRUCT causes an error.
+ - **When no field names are provided:** fields are matched by position, and
the number of values **must** be exactly equal to the number of fields defined
in the STRUCT.
9. Elements can use "null" to represent a null value.
If the STRUCT format does not meet the requirements, an error is reported, for
example:
-1. The number of field-value pairs does not match the number defined in the
STRUCT.
-2. The order of field-values does not match the order defined in the STRUCT.
+1. When no field names are provided, the number of values is not equal to the
number of fields defined in the STRUCT.
+2. When field names are provided, the input contains a field name that does
not exist in the STRUCT.
3. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
If a value in the STRUCT does not meet the requirements of the corresponding
type, an error is reported.
@@ -64,10 +66,13 @@ If a value in the STRUCT does not meet the requirements of
the corresponding typ
| " {}" | Error | Does not start with a brace, parsing fails |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | Valid
STRUCT with field names |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names can be quoted or unquoted |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, parsing succeeds |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, matched by position |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | When
field names are provided, fields are matched by name; the input order may
differ from the schema |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names are matched case-insensitively |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | Field b is
missing from the input and is filled with NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: Error | Field name c does
not exist in the STRUCT; strict mode reports an error |
| '{a:1,3.1,c:100}' | Error | Mixed format with some having field names and
others not |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: Error | Number of field-value
pairs does not match defined count |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: Error | Incorrect order of
fields |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: Error | When no field
names are provided, the value count does not match the number of fields defined
|
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: Error | "abc" cannot
be converted to int type |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | Valid
STRUCT with null value |
| '{"name":"John","age":25}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"John", "age":25} | STRUCT with string values |
@@ -107,13 +112,14 @@ If a value in the STRUCT does not meet the requirements
of the corresponding typ
5. Field-value pairs must either all use the "fieldname:value" format or all
use the "value" format.
6. Field names and values can optionally be enclosed in matching single quotes
(`'`) or double quotes (`"`). The content inside the quotes is treated as a
single entity.
7. Whitespace is allowed before and after elements within the STRUCT.
-8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. If there are `<field-token>` parts, they must
match the number and order of names defined in the STRUCT.
+8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. How `<field-token>` parts are handled depends
on whether field names are provided:
+ - **When field names are provided:** fields are matched **by name**,
case-insensitively. The order of the input fields does **not** need to match
the order defined in the STRUCT. Fields defined in the STRUCT but missing from
the input are filled with NULL. An input field name that does not exist in the
STRUCT is ignored.
+ - **When no field names are provided:** fields are matched by position, and
the number of values **must** be exactly equal to the number of fields defined
in the STRUCT.
9. Elements can use "null" to represent a null value.
If the STRUCT format does not meet the requirements, NULL is returned, for
example:
-1. The number of field-value pairs does not match the number defined in the
STRUCT.
-2. The order of field-values does not match the order defined in the STRUCT.
-3. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
+1. When no field names are provided, the number of values is not equal to the
number of fields defined in the STRUCT.
+2. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
If a value in the STRUCT does not meet the requirements of the corresponding
type, the corresponding position is set to null.
@@ -125,10 +131,13 @@ If a value in the STRUCT does not meet the requirements
of the corresponding typ
| " {}" | NULL | Does not start with a brace, parsing fails |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | Valid
STRUCT with field names |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names can be quoted or unquoted |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, parsing succeeds |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, matched by position |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | When
field names are provided, fields are matched by name; the input order may
differ from the schema |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names are matched case-insensitively |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | Field b is
missing from the input and is filled with NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} |
Unknown field c is ignored; missing field b is filled with NULL |
| '{a:1,3.1,c:100}' | NULL | Mixed format with some having field names and
others not |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | Number of field-value
pairs does not match defined count |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | Incorrect order of
fields |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: NULL | When no field
names are provided, the value count does not match the number of fields defined
|
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} |
"abc" cannot be converted to int type, position set to null |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | Valid
STRUCT with null value |
| '{"name":"John","age":"twenty-five"}' | Cast to STRUCT\<name:string,
age:int\>: {"name":"John", "age":null} | "twenty-five" cannot be converted to
int type, position set to null |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
index 064f3e470ff..9024d7680d0 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
@@ -46,12 +46,14 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
5. 字段 - 值对要么全部为"字段名：值"的格式，要么全部都为"值"的格式。
6. 字段名与值两边都可以选择性地用匹配的单引号 (`'`) 或双引号 (`"`) 包围，引号内的内容被视为一个整体。
7. 内部的元素的前后允许有空白字符。
-8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。如果有
`<field-token>`，需要和定义的 STRUCT 的 name 的个数、顺序相同。
+8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。`<field-token>`
的处理方式取决于是否提供了字段名：
+ - **提供字段名时：** 字段按**名称**匹配，且大小写不敏感。输入字段的顺序**不需要**与 STRUCT 定义的顺序一致。STRUCT
中定义但输入未提供的字段会被填充为 NULL。在严格模式下，如果输入的字段名在 STRUCT 中不存在，则报错。
+ - **不提供字段名时：** 字段按位置匹配，且值的个数**必须**与 STRUCT 定义的字段个数完全相等。
9. 可以用 "null" 来表示一个 null 值的元素。
如果 STRUCT 的整体不满足要求，报错，例如：
-1. 字段 - 值对个数不等于 STRUCT 定义的个数。
-2. 字段 - 值的顺序不等于 STRUCT 定义的顺序。
+1. 不提供字段名时，值的个数不等于 STRUCT 定义的字段个数。
+2. 提供字段名时，输入包含 STRUCT 中不存在的字段名。
3. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
如果 STRUCT 中的某个值不满足对应类型，报错。
@@ -64,10 +66,13 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
| " {}" | 报错 | 开头不是花括号，整体解析失败 |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | 使用字段名的合法
STRUCT |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名可以用引号包括，也可以没有引号 |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，也可以解析 |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，按位置匹配解析 |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
提供字段名时按名称匹配，输入顺序可以与定义顺序不同 |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名匹配大小写不敏感 |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 输入缺少字段
b，填充为 NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 字段名 c 在 STRUCT
中不存在，严格模式下报错 |
| '{a:1,3.1,c:100}' | 报错 | 有的有字段名，有的没有，报错 |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 字段 - 值对不等于定义的个数，报错 |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 顺序不对，报错 |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: 报错 |
不提供字段名时，输入个数与定义的字段个数不匹配 |
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: 报错 | "abc" 无法转换成 int
类型 |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | 包含 null
值的合法 STRUCT |
| '{"name":"张三","age":25}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"张三", "age":25} | 包含字符串的 STRUCT |
@@ -107,13 +112,14 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
5. 字段 - 值对要么全部为"字段名：值"的格式，要么全部都为"值"的格式。
6. 字段名与值两边都可以选择性地用匹配的单引号 (`'`) 或双引号 (`"`) 包围，引号内的内容被视为一个整体。
7. 内部的元素的前后允许有空白字符。
-8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。如果有
`<field-token>`，需要和定义的 STRUCT 的 name 的个数、顺序相同。
+8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。`<field-token>`
的处理方式取决于是否提供了字段名：
+ - **提供字段名时：** 字段按**名称**匹配，且大小写不敏感。输入字段的顺序**不需要**与 STRUCT 定义的顺序一致。STRUCT
中定义但输入未提供的字段会被填充为 NULL。如果输入的字段名在 STRUCT 中不存在，则忽略该字段。
+ - **不提供字段名时：** 字段按位置匹配，且值的个数**必须**与 STRUCT 定义的字段个数完全相等。
9. 可以用 "null" 来表示一个 null 值的元素。
如果 STRUCT 的整体不满足要求，返回 NULL，例如：
-1. 字段 - 值对个数不等于 STRUCT 定义的个数。
-2. 字段 - 值的顺序不等于 STRUCT 定义的顺序。
-3. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
+1. 不提供字段名时，值的个数不等于 STRUCT 定义的字段个数。
+2. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
如果 STRUCT 中的某个值不满足对应类型，对应位置为 null。
@@ -125,10 +131,13 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
| " {}" | NULL | 开头不是花括号，整体解析失败 |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | 使用字段名的合法
STRUCT |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名可以用引号包括，也可以没有引号 |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，也可以解析 |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，按位置匹配解析 |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
提供字段名时按名称匹配，输入顺序可以与定义顺序不同 |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名匹配大小写不敏感 |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 输入缺少字段
b，填充为 NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 未知字段
c 被忽略，缺少的字段 b 填充为 NULL |
| '{a:1,3.1,c:100}' | NULL | 有的有字段名，有的没有，返回 NULL |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | 字段 - 值对不等于定义的个数，返回 NULL |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | 顺序不对，返回 NULL |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: NULL |
不提供字段名时，输入个数与定义的字段个数不匹配 |
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} |
"abc" 无法转换成 int 类型，对应位置为 null |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | 包含 null
值的合法 STRUCT |
| '{"name":"张三","age":"二十五"}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"张三", "age":null} | "二十五" 无法转换为 int 类型，对应位置为 null |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
index 064f3e470ff..9024d7680d0 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
@@ -46,12 +46,14 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
5. 字段 - 值对要么全部为"字段名：值"的格式，要么全部都为"值"的格式。
6. 字段名与值两边都可以选择性地用匹配的单引号 (`'`) 或双引号 (`"`) 包围，引号内的内容被视为一个整体。
7. 内部的元素的前后允许有空白字符。
-8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。如果有
`<field-token>`，需要和定义的 STRUCT 的 name 的个数、顺序相同。
+8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。`<field-token>`
的处理方式取决于是否提供了字段名：
+ - **提供字段名时：** 字段按**名称**匹配，且大小写不敏感。输入字段的顺序**不需要**与 STRUCT 定义的顺序一致。STRUCT
中定义但输入未提供的字段会被填充为 NULL。在严格模式下，如果输入的字段名在 STRUCT 中不存在，则报错。
+ - **不提供字段名时：** 字段按位置匹配，且值的个数**必须**与 STRUCT 定义的字段个数完全相等。
9. 可以用 "null" 来表示一个 null 值的元素。
如果 STRUCT 的整体不满足要求，报错，例如：
-1. 字段 - 值对个数不等于 STRUCT 定义的个数。
-2. 字段 - 值的顺序不等于 STRUCT 定义的顺序。
+1. 不提供字段名时，值的个数不等于 STRUCT 定义的字段个数。
+2. 提供字段名时，输入包含 STRUCT 中不存在的字段名。
3. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
如果 STRUCT 中的某个值不满足对应类型，报错。
@@ -64,10 +66,13 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
| " {}" | 报错 | 开头不是花括号，整体解析失败 |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | 使用字段名的合法
STRUCT |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名可以用引号包括，也可以没有引号 |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，也可以解析 |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，按位置匹配解析 |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
提供字段名时按名称匹配，输入顺序可以与定义顺序不同 |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名匹配大小写不敏感 |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 输入缺少字段
b，填充为 NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 字段名 c 在 STRUCT
中不存在，严格模式下报错 |
| '{a:1,3.1,c:100}' | 报错 | 有的有字段名，有的没有，报错 |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 字段 - 值对不等于定义的个数，报错 |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: 报错 | 顺序不对，报错 |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: 报错 |
不提供字段名时，输入个数与定义的字段个数不匹配 |
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: 报错 | "abc" 无法转换成 int
类型 |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | 包含 null
值的合法 STRUCT |
| '{"name":"张三","age":25}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"张三", "age":25} | 包含字符串的 STRUCT |
@@ -107,13 +112,14 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
5. 字段 - 值对要么全部为"字段名：值"的格式，要么全部都为"值"的格式。
6. 字段名与值两边都可以选择性地用匹配的单引号 (`'`) 或双引号 (`"`) 包围，引号内的内容被视为一个整体。
7. 内部的元素的前后允许有空白字符。
-8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。如果有
`<field-token>`，需要和定义的 STRUCT 的 name 的个数、顺序相同。
+8. 解析中匹配到 `<value-token>` 的部分，继续应用 value 类型的解析规则进行解析。`<field-token>`
的处理方式取决于是否提供了字段名：
+ - **提供字段名时：** 字段按**名称**匹配，且大小写不敏感。输入字段的顺序**不需要**与 STRUCT 定义的顺序一致。STRUCT
中定义但输入未提供的字段会被填充为 NULL。如果输入的字段名在 STRUCT 中不存在，则忽略该字段。
+ - **不提供字段名时：** 字段按位置匹配，且值的个数**必须**与 STRUCT 定义的字段个数完全相等。
9. 可以用 "null" 来表示一个 null 值的元素。
如果 STRUCT 的整体不满足要求，返回 NULL，例如：
-1. 字段 - 值对个数不等于 STRUCT 定义的个数。
-2. 字段 - 值的顺序不等于 STRUCT 定义的顺序。
-3. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
+1. 不提供字段名时，值的个数不等于 STRUCT 定义的字段个数。
+2. 字段 - 值出现一些有字段名，一些没有的情况（要么全部都有，要么全部都没有）。
如果 STRUCT 中的某个值不满足对应类型，对应位置为 null。
@@ -125,10 +131,13 @@ STRUCT 类型用于存储和处理结构化数据，可以包含不同类型的
| " {}" | NULL | 开头不是花括号，整体解析失败 |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | 使用字段名的合法
STRUCT |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名可以用引号包括，也可以没有引号 |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，也可以解析 |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
没有提供字段名，按位置匹配解析 |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
提供字段名时按名称匹配，输入顺序可以与定义顺序不同 |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
字段名匹配大小写不敏感 |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 输入缺少字段
b，填充为 NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | 未知字段
c 被忽略，缺少的字段 b 填充为 NULL |
| '{a:1,3.1,c:100}' | NULL | 有的有字段名，有的没有，返回 NULL |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | 字段 - 值对不等于定义的个数，返回 NULL |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | 顺序不对，返回 NULL |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: NULL |
不提供字段名时，输入个数与定义的字段个数不匹配 |
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} |
"abc" 无法转换成 int 类型，对应位置为 null |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | 包含 null
值的合法 STRUCT |
| '{"name":"张三","age":"二十五"}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"张三", "age":null} | "二十五" 无法转换为 int 类型，对应位置为 null |
diff --git
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
index 69d4f380610..e667e662e42 100644
---
a/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
+++
b/versioned_docs/version-4.x/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
@@ -46,12 +46,14 @@ STRUCT type is used to store and process structured data,
which can contain fiel
5. Field-value pairs must either all use the "fieldname:value" format or all
use the "value" format.
6. Field names and values can optionally be enclosed in matching single quotes
(`'`) or double quotes (`"`). The content inside the quotes is treated as a
single entity.
7. Whitespace is allowed before and after elements within the STRUCT.
-8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. If there are `<field-token>` parts, they must
match the number and order of names defined in the STRUCT.
+8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. How `<field-token>` parts are handled depends
on whether field names are provided:
+ - **When field names are provided:** fields are matched **by name**,
case-insensitively. The order of the input fields does **not** need to match
the order defined in the STRUCT. Fields defined in the STRUCT but missing from
the input are filled with NULL. In strict mode, an input field name that does
not exist in the STRUCT causes an error.
+ - **When no field names are provided:** fields are matched by position, and
the number of values **must** be exactly equal to the number of fields defined
in the STRUCT.
9. Elements can use "null" to represent a null value.
If the STRUCT format does not meet the requirements, an error is reported, for
example:
-1. The number of field-value pairs does not match the number defined in the
STRUCT.
-2. The order of field-values does not match the order defined in the STRUCT.
+1. When no field names are provided, the number of values is not equal to the
number of fields defined in the STRUCT.
+2. When field names are provided, the input contains a field name that does
not exist in the STRUCT.
3. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
If a value in the STRUCT does not meet the requirements of the corresponding
type, an error is reported.
@@ -64,10 +66,13 @@ If a value in the STRUCT does not meet the requirements of
the corresponding typ
| " {}" | Error | Does not start with a brace, parsing fails |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | Valid
STRUCT with field names |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names can be quoted or unquoted |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, parsing succeeds |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, matched by position |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | When
field names are provided, fields are matched by name; the input order may
differ from the schema |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names are matched case-insensitively |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | Field b is
missing from the input and is filled with NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: Error | Field name c does
not exist in the STRUCT; strict mode reports an error |
| '{a:1,3.1,c:100}' | Error | Mixed format with some having field names and
others not |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: Error | Number of field-value
pairs does not match defined count |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: Error | Incorrect order of
fields |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: Error | When no field
names are provided, the value count does not match the number of fields defined
|
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: Error | "abc" cannot
be converted to int type |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | Valid
STRUCT with null value |
| '{"name":"John","age":25}' | Cast to STRUCT\<name:string, age:int\>:
{"name":"John", "age":25} | STRUCT with string values |
@@ -107,13 +112,14 @@ If a value in the STRUCT does not meet the requirements
of the corresponding typ
5. Field-value pairs must either all use the "fieldname:value" format or all
use the "value" format.
6. Field names and values can optionally be enclosed in matching single quotes
(`'`) or double quotes (`"`). The content inside the quotes is treated as a
single entity.
7. Whitespace is allowed before and after elements within the STRUCT.
-8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. If there are `<field-token>` parts, they must
match the number and order of names defined in the STRUCT.
+8. During parsing, parts that match `<value-token>` continue to apply the
parsing rules of the value type. How `<field-token>` parts are handled depends
on whether field names are provided:
+ - **When field names are provided:** fields are matched **by name**,
case-insensitively. The order of the input fields does **not** need to match
the order defined in the STRUCT. Fields defined in the STRUCT but missing from
the input are filled with NULL. An input field name that does not exist in the
STRUCT is ignored.
+ - **When no field names are provided:** fields are matched by position, and
the number of values **must** be exactly equal to the number of fields defined
in the STRUCT.
9. Elements can use "null" to represent a null value.
If the STRUCT format does not meet the requirements, NULL is returned, for
example:
-1. The number of field-value pairs does not match the number defined in the
STRUCT.
-2. The order of field-values does not match the order defined in the STRUCT.
-3. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
+1. When no field names are provided, the number of values is not equal to the
number of fields defined in the STRUCT.
+2. Some field-value pairs have field names while others do not (they must
either all have field names or none have field names).
If a value in the STRUCT does not meet the requirements of the corresponding
type, the corresponding position is set to null.
@@ -125,10 +131,13 @@ If a value in the STRUCT does not meet the requirements
of the corresponding typ
| " {}" | NULL | Does not start with a brace, parsing fails |
| '{"a":1,"b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":1, "b":1} | Valid
STRUCT with field names |
| '{a:1,"b":3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names can be quoted or unquoted |
-| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, parsing succeeds |
+| '{1,3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | No field
names provided, matched by position |
+| '{b:3.14,a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} | When
field names are provided, fields are matched by name; the input order may
differ from the schema |
+| '{A:1,B:3.14}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":3.14} |
Field names are matched case-insensitively |
+| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} | Field b is
missing from the input and is filled with NULL |
+| '{a:1,c:100}' | Cast to STRUCT\<a:int, b:double\>: {"a":1, "b":null} |
Unknown field c is ignored; missing field b is filled with NULL |
| '{a:1,3.1,c:100}' | NULL | Mixed format with some having field names and
others not |
-| '{a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | Number of field-value
pairs does not match defined count |
-| '{b:1,a:1}' | Cast to STRUCT\<a:int, b:double\>: NULL | Incorrect order of
fields |
+| '{1,3.14,100}' | Cast to STRUCT\<a:int, b:double\>: NULL | When no field
names are provided, the value count does not match the number of fields defined
|
| '{"a":"abc","b":1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} |
"abc" cannot be converted to int type, position set to null |
| '{null,1}' | Cast to STRUCT\<a:int, b:int\>: {"a":null, "b":1} | Valid
STRUCT with null value |
| '{"name":"John","age":"twenty-five"}' | Cast to STRUCT\<name:string,
age:int\>: {"name":"John", "age":null} | "twenty-five" cannot be converted to
int type, position set to null |
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
