From 955268fad8bcbe6f5af94c6399762d723b292249 Mon Sep 17 00:00:00 2001 From: csun5285 Date: Tue, 2 Jun 2026 18:05:50 +0800 Subject: [PATCH 1/3] [doc](struct) add subscript access syntax for STRUCT type Document that STRUCT fields can be accessed via the subscript operator s[idx] / s['field_name'], equivalent to STRUCT_ELEMENT, aligning the docs with apache/doris#64027. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../sql-data-types/semi-structured/STRUCT.md | 24 +++++++++++++++++++ .../struct-functions/struct-element.md | 12 ++++++++++ .../sql-data-types/semi-structured/STRUCT.md | 21 ++++++++++++++++ .../struct-functions/struct-element.md | 12 ++++++++++ 4 files changed, 69 insertions(+) diff --git a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index 1be44bd51cdcd..723bc19607a9b 100644 --- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -124,6 +124,30 @@ The STRUCT type is used to combine multiple fields into a single structure, wher +-------------------------------------------------------------------+ ``` +- You can also use the subscript operator `struct[k]` or `struct['field_name']` to access a specific subcolumn, which is 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 | + +--------------------------------------------------+ + ``` + ## Examples - Nested Complex Types 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 ffaf65c9da2eb..684a501388a4e 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 @@ -36,6 +36,7 @@ Return value meaning: - 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 +- The subscript operators `[]` and `['']` are equivalent to `STRUCT_ELEMENT(, )` and `STRUCT_ELEMENT(, '')` respectively ## 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'); diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index e235d7956bfe3..803a885f9460e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -107,6 +107,27 @@ STRUCT 类型用于将多个字段组合成一个结构体，每个字段可以 | 1728923 | +-------------------------------------------------------------------+ ``` + +- 也可以使用下标运算符 `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 | + +--------------------------------------------------+ + ``` ## 示例 - 嵌套复杂类型 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 e37b10c0a1d92..5fe4176af2f77 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 @@ -36,6 +36,7 @@ STRUCT_ELEMENT( , ) - 支持通过字段名访问，字段名必须完全匹配 - 第二个参数必须是常量（不能是列） - 函数标记为 AlwaysNullable，返回值可能为 null +- 下标运算符 `[]` 和 `['']` 分别等价于 `STRUCT_ELEMENT(, )` 和 `STRUCT_ELEMENT(, '')` ## 举例 @@ -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'); From 3fa189943ebbdb0b65321e481a393f9091d13bd1 Mon Sep 17 00:00:00 2001 From: csun5285 Date: Wed, 3 Jun 2026 09:23:45 +0800 Subject: [PATCH 2/3] [doc](struct) document element_at and subscript access for STRUCT Extend ELEMENT_AT docs to cover STRUCT, and note in the STRUCT type / STRUCT_ELEMENT pages that element_at(s, ...) and s[...] are equivalent to STRUCT_ELEMENT. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../sql-data-types/semi-structured/STRUCT.md | 2 +- .../struct-functions/struct-element.md | 2 +- .../variant-functions/element-at.md | 29 ++++++++++++++++--- .../sql-data-types/semi-structured/STRUCT.md | 2 +- .../struct-functions/struct-element.md | 2 +- .../variant-functions/element-at.md | 29 ++++++++++++++++--- 6 files changed, 54 insertions(+), 12 deletions(-) diff --git a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index 723bc19607a9b..2e37daa028574 100644 --- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -124,7 +124,7 @@ The STRUCT type is used to combine multiple fields into a single structure, wher +-------------------------------------------------------------------+ ``` -- You can also use the subscript operator `struct[k]` or `struct['field_name']` to access a specific subcolumn, which is equivalent to `STRUCT_ELEMENT`. +- 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. 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 684a501388a4e..642731005abf2 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 @@ -36,7 +36,7 @@ Return value meaning: - 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 -- The subscript operators `[]` and `['']` are equivalent to `STRUCT_ELEMENT(, )` and `STRUCT_ELEMENT(, '')` respectively +- `ELEMENT_AT(, ...)` and the subscript operators `[]` / `['']` are equivalent to `STRUCT_ELEMENT(, )` and `STRUCT_ELEMENT(, '')` respectively ## Examples diff --git a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md index a64898c64c814..451bafeffa08e 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md +++ b/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. - 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"); diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index 803a885f9460e..10781392241fd 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -108,7 +108,7 @@ STRUCT 类型用于将多个字段组合成一个结构体，每个字段可以 +-------------------------------------------------------------------+ ``` -- 也可以使用下标运算符 `struct[k]` 或 `struct['field_name']` 来访问某一个子列，效果等价于 `STRUCT_ELEMENT`。 +- 也可以使用 `ELEMENT_AT(struct, k/field_name)` 或下标运算符 `struct[k]` / `struct['field_name']` 来访问某一个子列，效果均等价于 `STRUCT_ELEMENT`。 - k 表征位置，从1开始。 - `field_name` 是 `STRUCT` 的子列的名字，必须为字符串常量。 ```SQL 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 5fe4176af2f77..cd68b4285a992 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 @@ -36,7 +36,7 @@ STRUCT_ELEMENT( , ) - 支持通过字段名访问，字段名必须完全匹配 - 第二个参数必须是常量（不能是列） - 函数标记为 AlwaysNullable，返回值可能为 null -- 下标运算符 `[]` 和 `['']` 分别等价于 `STRUCT_ELEMENT(, )` 和 `STRUCT_ELEMENT(, '')` +- `ELEMENT_AT(, ...)` 以及下标运算符 `[]` / `['']` 分别等价于 `STRUCT_ELEMENT(, )` 和 `STRUCT_ELEMENT(, '')` ## 举例 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md index 64f2d2ef790fa..550f0a74a61d7 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md +++ b/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"); From 16e8ddf7f1888063801fe679afe1453ce35de2f4 Mon Sep 17 00:00:00 2001 From: csun5285 Date: Wed, 3 Jun 2026 22:30:56 +0800 Subject: [PATCH 3/3] [doc](struct) update STRUCT access for merged struct_element/element_at Reflect apache/doris#64027 latest changes: struct_element is now subsumed by element_at (kept as a backward-compatible alias), struct field names are matched case-insensitively, document the dot operator s.field access form, and update the non-constant index error message. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../sql-data-types/semi-structured/STRUCT.md | 9 +++++++++ .../struct-functions/struct-element.md | 6 +++--- .../scalar-functions/variant-functions/element-at.md | 2 +- .../sql-data-types/semi-structured/STRUCT.md | 10 ++++++++++ .../struct-functions/struct-element.md | 6 +++--- .../scalar-functions/variant-functions/element-at.md | 2 +- 6 files changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index 2e37daa028574..471441d7654d9 100644 --- a/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/docs/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -148,6 +148,15 @@ The STRUCT type is used to combine multiple fields into a single structure, wher +--------------------------------------------------+ ``` +- 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 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 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 642731005abf2..8be001abeb986 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 @@ -33,10 +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(, ...)` and the subscript operators `[]` / `['']` are equivalent to `STRUCT_ELEMENT(, )` and `STRUCT_ELEMENT(, '')` respectively +- `ELEMENT_AT(, ...)`, the subscript operators `[]` / `['']`, and the dot operator `.` 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 @@ -110,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: diff --git a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md index 451bafeffa08e..4a9b8594781f5 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md +++ b/docs/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md @@ -27,7 +27,7 @@ ELEMENT_AT(container, key_or_index) - `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. + - 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 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md index 10781392241fd..c3a267b232a3d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/basic-element/sql-data-types/semi-structured/STRUCT.md @@ -128,6 +128,16 @@ STRUCT 类型用于将多个字段组合成一个结构体，每个字段可以 | 1728923 | +--------------------------------------------------+ ``` + +- 对于 `STRUCT` 列，还可以使用点运算符 `struct_col.field_name` 按名字访问子列，并支持嵌套访问，如 `struct_col.a.b`。 + + ```SQL + -- struct_col 是一个 STRUCT 列 + SELECT struct_col.name, struct_col.id FROM struct_table; + ``` + +- 字段名按**大小写不敏感**匹配。访问不存在的字段名或越界的位置会报错，且索引/字段名必须为常量。 + ## 示例 - 嵌套复杂类型 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 cd68b4285a992..55c8372fb1967 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 @@ -33,10 +33,10 @@ STRUCT_ELEMENT( , ) ## 使用说明 - 支持通过字段位置（索引）访问，索引从1开始 -- 支持通过字段名访问，字段名必须完全匹配 +- 支持通过字段名访问，字段名按**大小写不敏感**匹配 - 第二个参数必须是常量（不能是列） - 函数标记为 AlwaysNullable，返回值可能为 null -- `ELEMENT_AT(, ...)` 以及下标运算符 `[]` / `['']` 分别等价于 `STRUCT_ELEMENT(, )` 和 `STRUCT_ELEMENT(, '')` +- `ELEMENT_AT(, ...)`、下标运算符 `[]` / `['']` 以及点运算符 `.` 都是访问 struct 字段的等价写法。`STRUCT_ELEMENT` 现在是 `ELEMENT_AT` 的别名，为保持向后兼容而保留。 ## 举例 @@ -109,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，会报错： diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md index 550f0a74a61d7..f9bc791d6caf5 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/variant-functions/element-at.md @@ -27,7 +27,7 @@ ELEMENT_AT(container, key_or_index) - `key_or_index`： - 对于 `ARRAY`：为整数类型，索引从 **1** 开始； - 对于 `MAP`：为 `MAP` 中的键类型（`K`），可为任意支持的基础类型。 - - 对于 `STRUCT`：为常量整数（字段位置，从 **1** 开始）或常量字符串（字段名）。 + - 对于 `STRUCT`：为常量整数（字段位置，从 **1** 开始）或常量字符串（字段名，按**大小写不敏感**匹配）。 - 对于 `VARIANT`： 为字符串类型 ## 返回值