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 ddce974bef8 [doc](struct) update struct functions (#2765)
ddce974bef8 is described below
commit ddce974bef86c168d11bd83e953ad79544db99d8
Author: amory <[email protected]>
AuthorDate: Tue Sep 9 13:07:01 2025 +0800
[doc](struct) update struct functions (#2765)
## Versions
- [ ] dev
- [ ] 3.0
- [ ] 2.1
- [ ] 2.0
## Languages
- [ ] Chinese
- [ ] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
---
.../struct-functions/named-struct.md | 104 ++++++++++++++++----
.../struct-functions/struct-element.md | 105 +++++++++++++++------
.../scalar-functions/struct-functions/struct.md | 80 +++++++++++++---
.../struct-functions/named-struct.md | 101 ++++++++++++++++----
.../struct-functions/struct-element.md | 100 +++++++++++++++-----
.../scalar-functions/struct-functions/struct.md | 79 +++++++++++++---
6 files changed, 456 insertions(+), 113 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
index aac69d572b4..36066336d2c 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
@@ -1,43 +1,111 @@
---
{
"title": "NAMED_STRUCT",
- "language": "en"
+ "language": "en-US"
}
---
## Description
-Construct and return a struct based on the given strings and values. Notes:
-
-- The number of parameters must be a non-zero even number.The odd-indexed
elements are the names of the fields, which must be constant strings.The
even-indexed elements are the values of the fields, which can be either
multiple columns or constants.
+Constructs and returns a struct based on given field names and values. The
function accepts an even number of parameters, where odd positions are field
names and even positions are field values.
## Syntax
```sql
-NAMED_STRUCT( <field_name> , <filed_value> [ , <field_name> , <filed_value>
... ] )
+NAMED_STRUCT( <field_name> , <field_value> [ , <field_name> , <field_value>
... ] )
```
## Parameters
-| Parameter | Description |
-| -- | -- |
-| `<field_name>` | The odd-indexed elements in constructing the struct are the
field names, which must be constant strings |
-| `<filed_value>` | The even-indexed elements in constructing the struct
represent the field values, which can be either multiple columns or constants |
+- `<field_name>`: Input content at odd positions for constructing the struct,
the name of the field, must be a constant string
+- `<field_value>`: Input content at even positions for constructing the
struct, the value of the field, can be multiple columns or constants
+
+**Supported element types:**
+- Numeric types: TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE,
DECIMAL
+- String types: CHAR, VARCHAR, STRING
+- Date and time types: DATE, DATETIME, DATEV2, DATETIMEV2
+- Boolean type: BOOLEAN
+- IP types: IPV4, IPV6
+- Complex types: ARRAY, MAP, STRUCT
## Return Value
-Construct and return a struct based on the given strings and values.
+Return type: STRUCT<T>
+
+Return value meaning:
+- Returns a struct containing all specified field name and value pairs
+- All fields support NULL values
+
+## Usage
+
+- The function combines all field name and value pairs into a struct, where
odd positions are field names (must be constant strings and cannot be repeated,
case-insensitive), and even positions are field values (can be multiple columns
or constants)
+- The number of parameters must be a non-zero even number greater than 1
+- All fields are marked as nullable
+
+**Query Examples:**
+
+Basic usage:
+```sql
+select named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing');
++-------------------------------------------------------------+
+| named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing') |
++-------------------------------------------------------------+
+| {"name":"Alice", "age":25, "city":"Beijing"} |
++-------------------------------------------------------------+
+```
+
+Including null values:
+```sql
+select named_struct('id', 1, 'name', null, 'score', 95.5);
++----------------------------------------------------+
+| named_struct('id', 1, 'name', null, 'score', 95.5) |
++----------------------------------------------------+
+| {"id":1, "name":null, "score":95.5} |
++----------------------------------------------------+
+```
+
+Including complex types:
+```sql
+select named_struct('array', [1,2,3], 'map', {'key':'value'}, 'struct',
named_struct('f1',1,'f2',2));
++-----------------------------------------------------------------------------------------------+
+| named_struct('array', [1,2,3], 'map', {'key':'value'}, 'struct',
named_struct('f1',1,'f2',2)) |
++-----------------------------------------------------------------------------------------------+
+| {"array":[1, 2, 3], "map":{"key":"value"}, "struct":{"f1":1, "f2":2}}
|
++-----------------------------------------------------------------------------------------------+
+```
+
+Creating a named struct containing IP addresses:
+```sql
+select named_struct('ipv4', cast('192.168.1.1' as ipv4), 'ipv6',
cast('2001:db8::1' as ipv6));
++----------------------------------------------------------------------------------------+
+| named_struct('ipv4', cast('192.168.1.1' as ipv4), 'ipv6', cast('2001:db8::1'
as ipv6)) |
++----------------------------------------------------------------------------------------+
+| {"ipv4":"192.168.1.1", "ipv6":"2001:db8::1"}
|
++----------------------------------------------------------------------------------------+
+```
+
+Error Examples
+
+Less than 2 parameters:
+```sql
+select named_Struct();
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct requires at
least two arguments, like: named_struct('a', 1)
-## Example
+select named_struct('name');
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct requires at
least two arguments, like: named_struct('a', 1)
+```
+Odd number of parameters:
```sql
-select named_struct('f1', 1, 'f2', 'a', 'f3', "abc"),named_struct('a', null,
'b', "v");
+select named_struct('name', 'Alice', 'age');
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct can't be odd
parameters, need even parameters named_struct('name', 'Alice', 'age')
```
-```text
-+-----------------------------------------------+-----------------------------------+
-| named_struct('f1', 1, 'f2', 'a', 'f3', 'abc') | named_struct('a', NULL, 'b',
'v') |
-+-----------------------------------------------+-----------------------------------+
-| {"f1":1, "f2":"a", "f3":"abc"} | {"a":null, "b":"v"}
|
-+-----------------------------------------------+-----------------------------------+
+Duplicate field names, field names are case-insensitive:
+```sql
+select named_struct('name', 'Alice', 'name', 'Bob');
+ERROR 1105 (HY000): errCode = 2, detailMessage = The name of the struct field
cannot be repeated. same name fields are name
+
+select named_struct('name', 'Alice', 'Name', 'Bob');
+ERROR 1105 (HY000): errCode = 2, detailMessage = The name of the struct field
cannot be repeated. same name fields are name
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
index 23d4bb1c9b1..b55f4e9ce27 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
@@ -1,58 +1,107 @@
---
{
"title": "STRUCT_ELEMENT",
- "language": "en"
+ "language": "en-US"
}
---
## Description
-Return a specific field within a data column of a struct.
+Returns a specific field within a struct data column. The function supports
accessing fields in a struct through field position (index) or field name.
## Syntax
```sql
-STRUCT_ELEMENT( <struct>, '<filed_location>/<filed_name>')
+STRUCT_ELEMENT( <struct>, <field_location_or_name> )
```
## Parameters
-| Parameter | Description |
-| -- | -- |
-| `<struct>` | If the input struct column is null, return null |
-| `<filed_location>` | The position of the field starts from 1, and only
constants are supported |
-| `<filed_name>` | The field name must be a constant, case sensitive |
+- `<struct>`: Input struct column
+- `<field_location_or_name>`: Field position (starting from 1) or field name,
only supports constants
## Return Value
-Return the specified field column, with the type being any type
+Return type: Field value type supported by struct
-## Example
+Return value meaning:
+- Returns the specified field value
+- If the input struct is null, returns null
+- If the specified field does not exist, an error will be reported
+## Usage
+
+- Supports accessing by field position (index), index starts from 1
+- Supports accessing by field name, field name must match exactly
+- The second parameter must be a constant (cannot be a column)
+- The function is marked as AlwaysNullable, return value may be null
+
+## Examples
+
+**Query Examples:**
+
+Access by position:
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25, 'city',
'Beijing'), 1);
++--------------------------------------------------------------------------------+
+| struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'),
1) |
++--------------------------------------------------------------------------------+
+| Alice
|
++--------------------------------------------------------------------------------+
+```
+
+Access by field name:
```sql
-select struct_element(named_struct('f1', 1, 'f2', 'a'),
'f2'),struct_element(named_struct('f1', 1, 'f2', 'a'), 1);
+select struct_element(named_struct('name', 'Alice', 'age', 25, 'city',
'Beijing'), 'age');
++------------------------------------------------------------------------------------+
+| struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'),
'age') |
++------------------------------------------------------------------------------------+
+|
25 |
++------------------------------------------------------------------------------------+
```
-```text
-+--------------------------------------------------------+-----------------------------------------------------+
-| struct_element(named_struct('f1', 1, 'f2', 'a'), 'f2') |
struct_element(named_struct('f1', 1, 'f2', 'a'), 1) |
-+--------------------------------------------------------+-----------------------------------------------------+
-| a |
1 |
-+--------------------------------------------------------+-----------------------------------------------------+
+Accessing struct containing complex types:
+```sql
+select struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}),
'array');
++---------------------------------------------------------------------------------+
+| struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}),
'array') |
++---------------------------------------------------------------------------------+
+| [1, 2, 3]
|
++---------------------------------------------------------------------------------+
```
+Accessing result with null field value:
```sql
-select struct_col, struct_element(struct_col, 'f1') from test_struct;
+select struct_element(named_struct('name', null, 'age', 25), 'name');
++---------------------------------------------------------------+
+| struct_element(named_struct('name', null, 'age', 25), 'name') |
++---------------------------------------------------------------+
+| NULL |
++---------------------------------------------------------------+
```
-```text
-+-------------------------------------------------+-------------------------------------+
-| struct_col | struct_element(`struct_col
`, 'f1') |
-+-------------------------------------------------+-------------------------------------+
-| {1, 2, 3, 4, 5} |
1 |
-| {1, 1000, 10000000, 100000000000, 100000000000} |
1 |
-| {5, 4, 3, 2, 1} |
5 |
-| NULL |
NULL |
-| {1, NULL, 3, NULL, 5} |
1 |
-+-------------------------------------------------+-------------------------------------+
+Error Examples
+
+Accessing non-existent field name:
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), 'nonexistent');
+ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field name
nonexistent was not found: struct_element(named_struct('name', 'Alice', 'age',
25), 'nonexistent')
+```
+
+Accessing out-of-bounds index:
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field index out
of bound: struct_element(named_struct('name', 'Alice', 'age', 25), 5)
+```
+
+Second parameter is not a constant:
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), inv) from
var_with_index where k = 4;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct_element only allows
constant int or string second parameter: struct_element(named_struct('name',
'Alice', 'age', 25), inv)
+```
+
+Input struct is NULL, will report error:
+```sql
+select struct_element(NULL, 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: struct_element(NULL, TINYINT)
```
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
index 74b6897ffe3..f7abde7d89e 100644
--- a/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
+++ b/docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
@@ -1,13 +1,13 @@
---
{
"title": "STRUCT",
- "language": "en"
+ "language": "en-US"
}
---
## Description
-construct an struct with variadic elements and return it, Tn could be column
or literal
+Constructs and returns a struct based on given values. The function accepts
one or more parameters and returns a struct containing all input elements.
## Syntax
@@ -17,24 +17,78 @@ STRUCT( <expr1> [ , <expr2> ... ] )
## Parameters
-| Parameter | Description |
-| -- | -- |
-| `<expr>` | Construct the input content for the struct |
+- `<expr1>, <expr2>, ...`: Input content for constructing the struct, supports
one or more parameters
+
+**Supported element types:**
+- Numeric types: TINYINT, SMALLINT, INT, BIGINT, LARGEINT, FLOAT, DOUBLE,
DECIMAL
+- String types: CHAR, VARCHAR, STRING
+- Date and time types: DATE, DATETIME, DATEV2, DATETIMEV2
+- Boolean type: BOOLEAN
+- IP types: IPV4, IPV6
+- Complex types: ARRAY, MAP, STRUCT
## Return Value
-construct an struct with variadic elements and return it, Tn could be column
or literal
+Return type: STRUCT<T>
+
+Return value meaning:
+- Returns a struct containing all input elements, field names default to col1,
col2, col3, ... format
+- All fields support NULL values
+
+## Usage
+
+- The function combines all input elements into a struct
+- At least one parameter is required
+- All fields are marked as nullable
-## Example
+## Examples
+**Query Examples:**
+
+Basic usage: Creating a struct containing mixed types with null fields
```sql
select struct(1, 'a', "abc"),struct(null, 1, null),struct(cast('2023-03-16' as
datetime));
++--------------------------------------+--------------------------------------+----------------------------------------+
+| struct(1, 'a', "abc") | struct(null, 1, null)
| struct(cast('2023-03-16' as datetime)) |
++--------------------------------------+--------------------------------------+----------------------------------------+
+| {"col1":1, "col2":"a", "col3":"abc"} | {"col1":null, "col2":1, "col3":null}
| {"col1":"2023-03-16 00:00:00"} |
++--------------------------------------+--------------------------------------+----------------------------------------+
+```
+
+Creating a struct containing complex types:
+```sql
+select struct([1,2,3], {'name':'Alice','age':20}, named_struct('f1',1,'f2',2));
++----------------------------------------------------------------------------------+
+| struct([1,2,3], {'name':'Alice','age':20}, named_struct('f1',1,'f2',2))
|
++----------------------------------------------------------------------------------+
+| {"col1":[1, 2, 3], "col2":{"name":"Alice", "age":"20"}, "col3":{"f1":1,
"f2":2}} |
++----------------------------------------------------------------------------------+
```
-```text
-+--------------------------------------+--------------------------------------+---------------------------------------------+
-| struct(1, 'a', 'abc') | struct(NULL, 1, NULL)
| struct(cast('2023-03-16' as DATETIMEV2(0))) |
-+--------------------------------------+--------------------------------------+---------------------------------------------+
-| {"col1":1, "col2":"a", "col3":"abc"} | {"col1":null, "col2":1, "col3":null}
| {"col1":"2023-03-16 00:00:00"} |
-+--------------------------------------+--------------------------------------+---------------------------------------------+
+Creating a struct containing IP addresses:
+```sql
+select struct(cast('192.168.1.1' as ipv4), cast('2001:db8::1' as ipv6));
++------------------------------------------------------------------+
+| struct(cast('192.168.1.1' as ipv4), cast('2001:db8::1' as ipv6)) |
++------------------------------------------------------------------+
+| {"col1":"192.168.1.1", "col2":"2001:db8::1"} |
++------------------------------------------------------------------+
+```
+
+Error Examples
+
+Unsupported types will report error:
+Creating struct containing Json/Variant types
+```sql
+select struct(v) from var_with_index;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct does not support
jsonb/variant type
+
+select struct(cast(1 as jsonb)) from var_with_index;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct does not support
jsonb/variant type
+```
+
+Creating empty struct will report error, at least one parameter is required,
consistent with hive behavior:
+```sql
+select struct();
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct requires at least one
argument, like: struct(1)
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
index 8275211a2cb..281d7b3689f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/named-struct.md
@@ -7,37 +7,104 @@
## 描述
-根据给定的字符串和值构造并返回 struct ,注意事项：
-
-- 参数个数必须为非 0 偶数，奇数位是 field 的名字，必须为常量字符串，偶数位是 field 的值，可以是多列或常量
+根据给定的字段名和值构造并返回 struct。函数接受偶数个参数，奇数位是字段名，偶数位是字段值。
## 语法
```sql
-NAMED_STRUCT( <field_name> , <filed_value> [ , <field_name> , <filed_value>
... ] )
+NAMED_STRUCT( <field_name> , <field_value> [ , <field_name> , <field_value>
... ] )
```
## 参数
-| 参数 | 说明 |
-| -- | -- |
-| `<field_name>` | 构造 struct 的奇数位输入内容，field 的名字 |
-| `<filed_value>` | 构造 struct 的偶数位输入内容，field 的值，可以是多列或常量 |
+- `<field_name>`：构造 struct 的奇数位输入内容，字段的名字，必须为常量字符串
+- `<field_value>`：构造 struct 的偶数位输入内容，字段的值，可以是多列或常量
+
+**支持的元素类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
+- 字符串类型：CHAR、VARCHAR、STRING
+- 日期时间类型：DATE、DATETIME、DATEV2、DATETIMEV2
+- 布尔类型：BOOLEAN
+- IP 类型：IPV4、IPV6
+- 复杂类型：ARRAY、MAP、STRUCT
## 返回值
-根据给定的字符串和值构造并返回 struct
+返回类型：STRUCT<T>
+
+返回值含义：
+- 返回一个包含所有指定字段名和值对的结构体
+- 所有字段都支持 NULL 值
+
+## 使用说明
+
+- 函数会将所有字段名和值对组合成一个结构体，奇数位是字段的名字，必须为常量字符串，且不能重复，大小写不敏感，偶数位是字段的值，可以是多列或常量
+- 参数个数必须大于1的为非 0 偶数
+- 所有字段都标记为可空（nullable）
+
+**查询示例：**
-## 举例
+基本用法：
+```sql
+select named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing');
++-------------------------------------------------------------+
+| named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing') |
++-------------------------------------------------------------+
+| {"name":"Alice", "age":25, "city":"Beijing"} |
++-------------------------------------------------------------+
+```
+
+包含 null 值：
+```sql
+select named_struct('id', 1, 'name', null, 'score', 95.5);
++----------------------------------------------------+
+| named_struct('id', 1, 'name', null, 'score', 95.5) |
++----------------------------------------------------+
+| {"id":1, "name":null, "score":95.5} |
++----------------------------------------------------+
+```
+包含复杂类型：
```sql
-select named_struct('f1', 1, 'f2', 'a', 'f3', "abc"),named_struct('a', null,
'b', "v");
+select named_struct('array', [1,2,3], 'map', {'key':'value'}, 'struct',
named_struct('f1',1,'f2',2));
++-----------------------------------------------------------------------------------------------+
+| named_struct('array', [1,2,3], 'map', {'key':'value'}, 'struct',
named_struct('f1',1,'f2',2)) |
++-----------------------------------------------------------------------------------------------+
+| {"array":[1, 2, 3], "map":{"key":"value"}, "struct":{"f1":1, "f2":2}}
|
++-----------------------------------------------------------------------------------------------+
```
-```text
-+-----------------------------------------------+-----------------------------------+
-| named_struct('f1', 1, 'f2', 'a', 'f3', 'abc') | named_struct('a', NULL, 'b',
'v') |
-+-----------------------------------------------+-----------------------------------+
-| {"f1":1, "f2":"a", "f3":"abc"} | {"a":null, "b":"v"}
|
-+-----------------------------------------------+-----------------------------------+
+创建包含 IP 地址的命名结构体：
+```sql
+select named_struct('ipv4', cast('192.168.1.1' as ipv4), 'ipv6',
cast('2001:db8::1' as ipv6));
++----------------------------------------------------------------------------------------+
+| named_struct('ipv4', cast('192.168.1.1' as ipv4), 'ipv6', cast('2001:db8::1'
as ipv6)) |
++----------------------------------------------------------------------------------------+
+| {"ipv4":"192.168.1.1", "ipv6":"2001:db8::1"}
|
++----------------------------------------------------------------------------------------+
+```
+
+错误示例
+参数少于2个：
+```sql
+select named_Struct();
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct requires at
least two arguments, like: named_struct('a', 1)
+
+select named_struct('name');
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct requires at
least two arguments, like: named_struct('a', 1)
+```
+
+参数个数为奇数：
+```sql
+select named_struct('name', 'Alice', 'age');
+ERROR 1105 (HY000): errCode = 2, detailMessage = named_struct can't be odd
parameters, need even parameters named_struct('name', 'Alice', 'age')
+```
+
+字段名重复，字段名大小写不敏感：
+```sql
+select named_struct('name', 'Alice', 'name', 'Bob');
+ERROR 1105 (HY000): errCode = 2, detailMessage = The name of the struct field
cannot be repeated. same name fields are name
+
+select named_struct('name', 'Alice', 'Name', 'Bob');
+ERROR 1105 (HY000): errCode = 2, detailMessage = The name of the struct field
cannot be repeated. same name fields are name
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
index 0d691c227f9..3ffa5d3be32 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md
@@ -7,52 +7,100 @@
## 描述
-返回 struct 数据列内的某一 field
+返回 struct 数据列内的某一字段。函数支持通过字段位置（索引）或字段名来访问结构体中的字段。
## 语法
```sql
-STRUCT_ELEMENT( <struct>, '<filed_location>/<filed_name>')
+STRUCT_ELEMENT( <struct>, <field_location_or_name> )
```
## 参数
-| 参数 | 说明 |
-| -- | -- |
-| `<struct>` | 输入的 struct 列，如果是 null，则返回 null |
-| `<filed_location>` | field 的位置，起始位置从 1 开始，仅支持常量 |
-| `<filed_name>` | field 的名字，仅支持常量，大小写敏感 |
+- `<struct>`：输入的 struct 列
+- `<field_location_or_name>`：字段的位置（从1开始）或字段的名字，仅支持常量
## 返回值
-返回指定的 field 列，类型为任意类型
+返回类型：struct 支持的字段值类型
+
+返回值含义：
+- 返回指定的字段值
+- 如果输入的 struct 为 null，返回 null
+- 如果指定的字段不存在，会报错
+
+## 使用说明
+
+- 支持通过字段位置（索引）访问，索引从1开始
+- 支持通过字段名访问，字段名必须完全匹配
+- 第二个参数必须是常量（不能是列）
+- 函数标记为 AlwaysNullable，返回值可能为 null
## 举例
+**查询示例：**
+
+按位置访问：
```sql
-select struct_element(named_struct('f1', 1, 'f2', 'a'),
'f2'),struct_element(named_struct('f1', 1, 'f2', 'a'), 1);
+select struct_element(named_struct('name', 'Alice', 'age', 25, 'city',
'Beijing'), 1);
++--------------------------------------------------------------------------------+
+| struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'),
1) |
++--------------------------------------------------------------------------------+
+| Alice
|
++--------------------------------------------------------------------------------+
```
-```text
-+--------------------------------------------------------+-----------------------------------------------------+
-| struct_element(named_struct('f1', 1, 'f2', 'a'), 'f2') |
struct_element(named_struct('f1', 1, 'f2', 'a'), 1) |
-+--------------------------------------------------------+-----------------------------------------------------+
-| a |
1 |
-+--------------------------------------------------------+-----------------------------------------------------+
+按字段名访问：
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25, 'city',
'Beijing'), 'age');
++------------------------------------------------------------------------------------+
+| struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'),
'age') |
++------------------------------------------------------------------------------------+
+|
25 |
++------------------------------------------------------------------------------------+
```
+访问包含有复杂类型的struct：
```sql
-select struct_col, struct_element(struct_col, 'f1') from test_struct;
+select struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}),
'array');
++---------------------------------------------------------------------------------+
+| struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}),
'array') |
++---------------------------------------------------------------------------------+
+| [1, 2, 3]
|
++---------------------------------------------------------------------------------+
```
-```text
-+-------------------------------------------------+-------------------------------------+
-| struct_col | struct_element(`struct_col
`, 'f1') |
-+-------------------------------------------------+-------------------------------------+
-| {1, 2, 3, 4, 5} |
1 |
-| {1, 1000, 10000000, 100000000000, 100000000000} |
1 |
-| {5, 4, 3, 2, 1} |
5 |
-| NULL |
NULL |
-| {1, NULL, 3, NULL, 5} |
1 |
-+-------------------------------------------------+-------------------------------------+
+访问字段值有 null 的结果：
+```sql
+select struct_element(named_struct('name', null, 'age', 25), 'name');
++---------------------------------------------------------------+
+| struct_element(named_struct('name', null, 'age', 25), 'name') |
++---------------------------------------------------------------+
+| NULL |
++---------------------------------------------------------------+
+```
+
+错误示例
+访问的字段名不存在：
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), 'nonexistent');
+ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field name
nonexistent was not found: struct_element(named_struct('name', 'Alice', 'age',
25), 'nonexistent')
```
+
+访问的索引越界：
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field index out
of bound: struct_element(named_struct('name', 'Alice', 'age', 25), 5)
+```
+
+访问的第二个参数不是常量：
+```sql
+select struct_element(named_struct('name', 'Alice', 'age', 25), inv) from
var_with_index where k = 4;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct_element only allows
constant int or string second parameter: struct_element(named_struct('name',
'Alice', 'age', 25), inv)
+```
+
+输入的struct 为NULL，会报错：
+```sql
+select struct_element(NULL, 5);
+ERROR 1105 (HY000): errCode = 2, detailMessage = Can not find the
compatibility function signature: struct_element(NULL, TINYINT)
+```
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
index f30f3fbe3b5..97d3de9c7d4 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct.md
@@ -7,7 +7,7 @@
## 描述
-根据给定的值构造并返回 struct，参数可以是多列或常量
+根据给定的值构造并返回 struct。函数接受一个或多个参数，返回一个包含所有输入元素的结构体。
## 语法
@@ -17,24 +17,81 @@ STRUCT( <expr1> [ , <expr2> ... ] )
## 参数
-| 参数 | 说明 |
-| -- | -- |
-| `<expr>` | 构造 struct 的输入内容 |
+- `<expr1>, <expr2>, ...`：构造 struct 的输入内容，支持一个或多个参数
+
+**支持的元素类型：**
+- 数值类型：TINYINT、SMALLINT、INT、BIGINT、LARGEINT、FLOAT、DOUBLE、DECIMAL
+- 字符串类型：CHAR、VARCHAR、STRING
+- 日期时间类型：DATE、DATETIME、DATEV2、DATETIMEV2
+- 布尔类型：BOOLEAN
+- IP 类型：IPV4、IPV6
+- 复杂类型：ARRAY、MAP、STRUCT
## 返回值
-根据给定的值构造并返回 struct，参数可以是多列或常量
+返回类型：STRUCT<T>
+
+返回值含义：
+- 返回一个包含所有输入元素的结构体，字段名默认为 col1, col2, col3, ... 格式
+- 所有字段都支持 NULL 值
+
+## 使用说明
+
+- 函数会将所有输入元素组合成一个结构体
+- 至少需要一个参数
+- 所有字段都标记为可空（nullable）
## 举例
+**查询示例：**
+
+基本用法：创建包含混合类型的结构体，并且字段有 null
```sql
select struct(1, 'a', "abc"),struct(null, 1, null),struct(cast('2023-03-16' as
datetime));
++--------------------------------------+--------------------------------------+----------------------------------------+
+| struct(1, 'a', "abc") | struct(null, 1, null)
| struct(cast('2023-03-16' as datetime)) |
++--------------------------------------+--------------------------------------+----------------------------------------+
+| {"col1":1, "col2":"a", "col3":"abc"} | {"col1":null, "col2":1, "col3":null}
| {"col1":"2023-03-16 00:00:00"} |
++--------------------------------------+--------------------------------------+----------------------------------------+
```
-```text
-+--------------------------------------+--------------------------------------+---------------------------------------------+
-| struct(1, 'a', 'abc') | struct(NULL, 1, NULL)
| struct(cast('2023-03-16' as DATETIMEV2(0))) |
-+--------------------------------------+--------------------------------------+---------------------------------------------+
-| {"col1":1, "col2":"a", "col3":"abc"} | {"col1":null, "col2":1, "col3":null}
| {"col1":"2023-03-16 00:00:00"} |
-+--------------------------------------+--------------------------------------+---------------------------------------------+
+创建包含复杂类型的结构体：
+```sql
+select struct([1,2,3], {'name':'Alice','age':20}, named_struct('f1',1,'f2',2));
++----------------------------------------------------------------------------------+
+| struct([1,2,3], {'name':'Alice','age':20}, named_struct('f1',1,'f2',2))
|
++----------------------------------------------------------------------------------+
+| {"col1":[1, 2, 3], "col2":{"name":"Alice", "age":"20"}, "col3":{"f1":1,
"f2":2}} |
++----------------------------------------------------------------------------------+
```
+
+创建包含 IP 地址的结构体：
+```sql
+select struct(cast('192.168.1.1' as ipv4), cast('2001:db8::1' as ipv6));
++------------------------------------------------------------------+
+| struct(cast('192.168.1.1' as ipv4), cast('2001:db8::1' as ipv6)) |
++------------------------------------------------------------------+
+| {"col1":"192.168.1.1", "col2":"2001:db8::1"} |
++------------------------------------------------------------------+
+```
+
+错误示例
+
+不支持的类型会报错：
+创建包含 Json/Variant 类型
+```sql
+select struct(v) from var_with_index;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct does not support
jsonb/variant type
+
+select struct(cast(1 as jsonb)) from var_with_index;
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct does not support
jsonb/variant type
+```
+
+创建空的struct 会报错，至少有一个参数，和 hive 行为保持一致：
+```sql
+select struct();
+ERROR 1105 (HY000): errCode = 2, detailMessage = struct requires at least one
argument, like: struct(1)
+```
+
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
