Skip to content

[doc](struct) match STRUCT sub-fields by name in cast from string #3907

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
csun5285 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[doc](struct) match STRUCT sub-fields by name in cast from string #3907

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 22 additions & 13 deletions docs/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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 |
Expand Down Expand Up @@ -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.

Expand All @@ -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 |
Expand Down
35 changes: 22 additions & 13 deletions ...current/sql-manual/basic-element/sql-data-types/conversion/struct-conversion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 中的某个值不满足对应类型，报错。
Expand All @@ -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 |
Expand Down Expand Up @@ -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。

Expand All @@ -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 |
Expand Down
Loading
Loading