[doc](struct) document subscript and element_at access for STRUCT type

docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md

@@ -124,6 +124,39 @@ The STRUCT type is used to combine multiple fields into a single structure, wher
   +-------------------------------------------------------------------+
   ```
 
+- You can also use `ELEMENT_AT(struct, k/field_name)` or the subscript operator `struct[k]` / `struct['field_name']` to access a specific subcolumn, all of which are equivalent to `STRUCT_ELEMENT`.
+
+  - `k` represents the position, starting from 1.
+
+  - `field_name` is the name of the subcolumn in the `STRUCT`, and must be a string constant.
+
+  ```SQL
+  SELECT NAMED_STRUCT("name", "Jack", "id", 1728923)[1];
+
+  +-----------------------------------------------+
+  | NAMED_STRUCT('name', 'Jack', 'id', 1728923)[1] |
+  +-----------------------------------------------+
+  | Jack                                          |
+  +-----------------------------------------------+
+
+  SELECT NAMED_STRUCT("name", "Jack", "id", 1728923)['id'];
+
+  +--------------------------------------------------+
+  | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
+  +--------------------------------------------------+
+  |                                          1728923 |
+  +--------------------------------------------------+
+  ```
+
+- For a `STRUCT` column, you can also use the dot operator `struct_col.field_name` to access a subcolumn by name, including nested access such as `struct_col.a.b`.
+
+  ```SQL
+  -- struct_col is a STRUCT<name: STRING, id: INT> column
+  SELECT struct_col.name, struct_col.id FROM struct_table;
+  ```
+
+- Field names are matched **case-insensitively**. Accessing a non-existent field name or an out-of-bound position reports an error, and the index/field name must be a constant.
+
 ## Examples
 
 - Nested Complex Types

docs/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md

@@ -33,9 +33,10 @@ Return value meaning:
 ## Usage
 
 - Supports accessing by field position (index), index starts from 1
-- Supports accessing by field name, field name must match exactly
+- Supports accessing by field name; the field name is matched **case-insensitively**
 - The second parameter must be a constant (cannot be a column)
 - The function is marked as AlwaysNullable, return value may be null
+- `ELEMENT_AT(<struct>, ...)`, the subscript operators `<struct>[<index>]` / `<struct>['<field_name>']`, and the dot operator `<struct_col>.<field_name>` are all equivalent ways to access a struct field. `STRUCT_ELEMENT` is now an alias of `ELEMENT_AT` and is kept for backward compatibility.
 
 ## Examples
 
@@ -61,6 +62,17 @@ select struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'
 +------------------------------------------------------------------------------------+
 ```
 
+Access using the subscript operator (equivalent to the calls above):
+```sql
+select named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing')[1] as by_index,
+       named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing')['age'] as by_name;
++----------+---------+
+| by_index | by_name |
++----------+---------+
+| Alice    |      25 |
++----------+---------+
+```
+
 Accessing struct containing complex types:
 ```sql
 select struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}), 'array');
@@ -98,7 +110,7 @@ ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field index out o
 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)
+ERROR 1105 (HY000): errCode = 2, detailMessage = element_at over a struct only allows a constant int or string second parameter: element_at(named_struct('name', 'Alice', 'age', 25), inv)
 ```
 
 Input struct is NULL, will report error:

docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md

@@ -8,10 +8,11 @@
 
 ## Function
 
-The `ELEMENT_AT` function is used to extract the element value from an array or map based on the specified index or key.
+The `ELEMENT_AT` function is used to extract the element value from an array, map, struct, or variant based on the specified index or key.
 
 - When applied to an **ARRAY**, it returns the element at the specified position.  
 - When applied to a **MAP**, it returns the value corresponding to the specified key.  
+- When applied to a **STRUCT**, it returns the subfield at the specified position (starting from 1) or with the specified field name, equivalent to `STRUCT_ELEMENT`.  
 - When applied to a **VARIANT**, it returns the value of the specified subfield.
 
 ## Syntax
@@ -22,18 +23,20 @@ ELEMENT_AT(container, key_or_index)
 
 ## Parameters
 
-- `container`: Can be `ARRAY`, `MAP`, or `VARIANT`.
+- `container`: Can be `ARRAY`, `MAP`, `STRUCT`, or `VARIANT`.
 - `key_or_index`:
   - For `ARRAY`: An integer, with indexing starting from **1**.  
   - For `MAP`: The key type (`K`) of the `MAP`, which can be any supported primitive type.  
+  - For `STRUCT`: A constant integer field position (starting from **1**) or a constant string field name (matched **case-insensitively**).  
   - For `VARIANT`: A string type.
 
 ## Return Value
 
 - For `ARRAY`: Returns the element at the specified index (`T` type).  
 - For `MAP`: Returns the value corresponding to the specified key (`V` type).  
+- For `STRUCT`: Returns the specified subfield value.  
 - For `VARIANT`: Returns a `VARIANT` type value.  
-- If the index or key does not exist, returns `NULL`.  
+- If the index or key does not exist, returns `NULL` (for `STRUCT`, an out-of-bound position or a non-existent field name reports an error).  
 - If the parameter is `NULL`, returns `NULL`.
 
 ## Notes
@@ -91,7 +94,25 @@ ELEMENT_AT(container, key_or_index)
     +-----------------------------------+
     ```
 
-4. When accessing a subfield of a `VARIANT`, if the `VARIANT` value is not an OBJECT, an empty value is returned.
+4. Accessing a `STRUCT` subfield by position or by field name (equivalent to `STRUCT_ELEMENT`).
+
+    ```SQL
+    SELECT ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1);
+    +------------------------------------------------------------+
+    | ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1) |
+    +------------------------------------------------------------+
+    | Jack                                                       |
+    +------------------------------------------------------------+
+
+    SELECT NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'];
+    +--------------------------------------------------+
+    | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
+    +--------------------------------------------------+
+    |                                          1728923 |
+    +--------------------------------------------------+
+    ```
+
+5. When accessing a subfield of a `VARIANT`, if the `VARIANT` value is not an OBJECT, an empty value is returned.
 
     ```SQL
     SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md

@@ -107,6 +107,37 @@ STRUCT 类型用于将多个字段组合成一个结构体，每个字段可以
   |                                                           1728923 |
   +-------------------------------------------------------------------+
   ```
+
+- 也可以使用 `ELEMENT_AT(struct, k/field_name)` 或下标运算符 `struct[k]` / `struct['field_name']` 来访问某一个子列，效果均等价于 `STRUCT_ELEMENT`。
+  - k 表征位置，从1开始。
+  - `field_name` 是 `STRUCT` 的子列的名字，必须为字符串常量。
+  ```SQL
+  SELECT NAMED_STRUCT("name", "Jack", "id", 1728923)[1];
+
+  +-----------------------------------------------+
+  | NAMED_STRUCT('name', 'Jack', 'id', 1728923)[1] |
+  +-----------------------------------------------+
+  | Jack                                          |
+  +-----------------------------------------------+
+
+  SELECT NAMED_STRUCT("name", "Jack", "id", 1728923)['id'];
+
+  +--------------------------------------------------+
+  | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
+  +--------------------------------------------------+
+  |                                          1728923 |
+  +--------------------------------------------------+
+  ```
+
+- 对于 `STRUCT` 列，还可以使用点运算符 `struct_col.field_name` 按名字访问子列，并支持嵌套访问，如 `struct_col.a.b`。
+
+  ```SQL
+  -- struct_col 是一个 STRUCT<name: STRING, id: INT> 列
+  SELECT struct_col.name, struct_col.id FROM struct_table;
+  ```
+
+- 字段名按**大小写不敏感**匹配。访问不存在的字段名或越界的位置会报错，且索引/字段名必须为常量。
+
 ## 示例
 
 - 嵌套复杂类型

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/struct-functions/struct-element.md

@@ -33,9 +33,10 @@ STRUCT_ELEMENT( <struct>, <field_location_or_name> )
 ## 使用说明
 
 - 支持通过字段位置（索引）访问，索引从1开始
-- 支持通过字段名访问，字段名必须完全匹配
+- 支持通过字段名访问，字段名按**大小写不敏感**匹配
 - 第二个参数必须是常量（不能是列）
 - 函数标记为 AlwaysNullable，返回值可能为 null
+- `ELEMENT_AT(<struct>, ...)`、下标运算符 `<struct>[<index>]` / `<struct>['<field_name>']` 以及点运算符 `<struct_col>.<field_name>` 都是访问 struct 字段的等价写法。`STRUCT_ELEMENT` 现在是 `ELEMENT_AT` 的别名，为保持向后兼容而保留。
 
 ## 举例
 
@@ -61,6 +62,17 @@ select struct_element(named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing'
 +------------------------------------------------------------------------------------+
 ```
 
+使用下标运算符访问（等价于上述调用）：
+```sql
+select named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing')[1] as by_index,
+       named_struct('name', 'Alice', 'age', 25, 'city', 'Beijing')['age'] as by_name;
++----------+---------+
+| by_index | by_name |
++----------+---------+
+| Alice    |      25 |
++----------+---------+
+```
+
 访问包含有复杂类型的struct：
 ```sql
 select struct_element(named_struct('array', [1,2,3], 'map', {'key':'value'}), 'array');
@@ -97,7 +109,7 @@ ERROR 1105 (HY000): errCode = 2, detailMessage = the specified field index out o
 访问的第二个参数不是常量：
 ```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)
+ERROR 1105 (HY000): errCode = 2, detailMessage = element_at over a struct only allows a constant int or string second parameter: element_at(named_struct('name', 'Alice', 'age', 25), inv)
 ```
 
 输入的struct 为NULL，会报错：

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md

@@ -8,10 +8,11 @@
 
 ## 功能
 
-`ELEMENT_AT` 函数用于从数组或 map 中按指定的索引或键提取对应的元素值。
+`ELEMENT_AT` 函数用于从数组、map、struct 或 variant 中按指定的索引或键提取对应的元素值。
 
 - 当作用于 **数组（ARRAY）** 时，返回指定位置的元素；
 - 当作用于 **MAP** 时，返回指定键对应的值。
+- 当作用于 **STRUCT** 时，返回指定位置（从 1 开始）或指定字段名对应的子列，等价于 `STRUCT_ELEMENT`。
 - 当作用于 **VARIANT** 时，返回指定子列对应的值。
 
 ## 语法
@@ -22,18 +23,20 @@ ELEMENT_AT(container, key_or_index)
 
 ## 参数
 
-- `container`：可以是`ARRAY`, `MAP`, `VARIANT`。
+- `container`：可以是`ARRAY`, `MAP`, `STRUCT`, `VARIANT`。
 - `key_or_index`：
   - 对于 `ARRAY`：为整数类型，索引从 **1** 开始；
   - 对于 `MAP`：为 `MAP` 中的键类型（`K`），可为任意支持的基础类型。
+  - 对于 `STRUCT`：为常量整数（字段位置，从 **1** 开始）或常量字符串（字段名，按**大小写不敏感**匹配）。
   - 对于 `VARIANT`： 为字符串类型
 
 ## 返回值
 
 - 若为 `ARRAY`，返回数组中对应索引的元素（`T` 类型）；
 - 若为 `MAP`，返回对应键的值（`V` 类型）；
+- 若为 `STRUCT`，返回指定的子列值；
 - 若为 `VARIANT`， 返回 `VARIANT` 类型；
-- 如果索引或键不存在，返回 `NULL`；
+- 如果索引或键不存在，返回 `NULL`（对于 `STRUCT`，位置越界或字段名不存在会报错）；
 - 如果参数为 `NULL`，返回 `NULL`。
 
 ## 使用说明
@@ -91,7 +94,25 @@ ELEMENT_AT(container, key_or_index)
     +-----------------------------------+
     ```
 
-4. 访问 `VARIANT` 的某个子列，如果 `VARIANT` 的值不是 OBJECT，返回空
+4. 按位置或字段名访问 `STRUCT` 的子列（等价于 `STRUCT_ELEMENT`）。
+
+    ```SQL
+    SELECT ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1);
+    +------------------------------------------------------------+
+    | ELEMENT_AT(NAMED_STRUCT('name', 'Jack', 'id', 1728923), 1) |
+    +------------------------------------------------------------+
+    | Jack                                                       |
+    +------------------------------------------------------------+
+
+    SELECT NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'];
+    +--------------------------------------------------+
+    | NAMED_STRUCT('name', 'Jack', 'id', 1728923)['id'] |
+    +--------------------------------------------------+
+    |                                          1728923 |
+    +--------------------------------------------------+
+    ```
+
+5. 访问 `VARIANT` 的某个子列，如果 `VARIANT` 的值不是 OBJECT，返回空
 
     ```SQL
      SELECT ELEMENT_AT(CAST('{"a": 1, "b": 2}' AS VARIANT), "a");