[docs] Document the optional group index of regexp_extract_all

docs/sql-manual/sql-functions/scalar-functions/string-functions/regexp-extract-all.md

@@ -23,7 +23,7 @@ Supported character matching types when the session variable `enable_extended_re
 ## Syntax
 
 ```sql
-REGEXP_EXTRACT_ALL(<str>, <pattern>)
+REGEXP_EXTRACT_ALL(<str>, <pattern>[, <idx>])
 ```
 
 ## Parameters
@@ -32,6 +32,7 @@ REGEXP_EXTRACT_ALL(<str>, <pattern>)
 | -- | -- |
 | `<str>` | This parameter is of type String. It represents the input string on which the regular expression matching will be performed. This can be a literal string value or a reference to a column in a table that contains string data.|
 | `<pattern>` | This parameter is also of type String. It specifies the regular expression pattern that will be used to match against the input string <str>. The pattern can include various regular expression constructs such as character classes, quantifiers, and sub - patterns.|
+| `<idx>` | Optional. This parameter is of type BIGINT. It specifies which capturing group to extract. `0` means the whole match, `1` means the first capturing group (the default), and so on. The value must be between `0` and the number of capturing groups in `<pattern>`; otherwise an error is thrown. Groups that do not participate in a match contribute an empty string to the result.|
 
 ## Return value
 
@@ -64,6 +65,52 @@ Pattern modifiers only take effect when using the default regex engine. If `enab
 | `(?U)`  | Non-greedy quantifiers: `*`, `+`, etc. match as little as possible           |
 | `(?-U)` | Greedy quantifiers (default): `*`, `+`, etc. match as much as possible       |
 
+## Extracting a specific capturing group
+
+By default, `REGEXP_EXTRACT_ALL` extracts the first capturing group. The optional `<idx>` parameter selects a different group, following the same contract as Spark:
+
+- `idx = 0` extracts the whole match. In this form the pattern does not need any capturing group.
+- `idx = N` extracts the N-th capturing group.
+- An `idx` outside the range `[0, number_of_capturing_groups]` raises an error.
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0) |
++----------------------------------------------------------------------------------+
+| ['x=18abc','x=17bcd']                                                            |
++----------------------------------------------------------------------------------+
+```
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2) |
++----------------------------------------------------------------------------------+
+| ['abc','bcd']                                                                    |
++----------------------------------------------------------------------------------+
+```
+
+Groups that do not participate in a match contribute an empty string:
+
+```sql
+mysql> SELECT regexp_extract_all('a b', '(a)|(b)', 2);
++------------------------------------------+
+| regexp_extract_all('a b', '(a)|(b)', 2)  |
++------------------------------------------+
+| ['','b']                                 |
++------------------------------------------+
+```
+
+An out-of-range group index raises an error:
+
+```sql
+SELECT regexp_extract_all('abc', '(b)', 2);
+```
+```text
+ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]The value of parameter(s) `idx` in `regexp_extract_all` is invalid: Expects group index between 0 and 1, but got 2.
+```
+
 ## Example
 
 Basic matching of lowercase letters around 'C'.In this example, the pattern ([[:lower:]]+)C([[:lower:]]+) matches the part of the string where one or more lowercase letters are followed by 'C' and then one or more lowercase letters. The first sub - pattern ([[:lower:]]+) before 'C' matches 'b', so the result is ['b'].

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/regexp-extract-all.md

@@ -43,7 +43,7 @@ Doris 支持通过会话变量 `enable_extended_regex`（默认为 `false`）来
 ## 语法
 
 ```sql
-REGEXP_EXTRACT_ALL(<str>, <pattern>)
+REGEXP_EXTRACT_ALL(<str>, <pattern>[, <idx>])
 ```
 
 ## 参数
@@ -52,6 +52,53 @@ REGEXP_EXTRACT_ALL(<str>, <pattern>)
 | -- | -- |
 | `<str>` | 该参数为 String 类型。表示要执行正则表达式匹配的输入字符串。可以是字面值字符串或包含字符串数据的表列引用。|
 | `<pattern>` | 该参数也为 String 类型。指定用于与输入字符串 <str> 匹配的正则表达式模式。该模式可以包含各种正则表达式构造，如字符类、量词和子模式。|
+| `<idx>` | 可选。该参数为 BIGINT 类型。指定提取第几个捕获组：`0` 表示整体匹配，`1` 表示第一个捕获组（默认值），以此类推。取值必须在 `0` 到 `<pattern>` 捕获组数量之间，否则抛出错误。未参与某次匹配的捕获组在结果中以空字符串表示。|
+
+## 提取指定的捕获组
+
+默认情况下，`REGEXP_EXTRACT_ALL` 提取第一个捕获组。可选参数 `<idx>` 用于指定其他捕获组，语义与 Spark 一致：
+
+- `idx = 0` 提取整体匹配，此时模式中可以不包含任何捕获组。
+- `idx = N` 提取第 N 个捕获组。
+- `idx` 超出 `[0, 捕获组数量]` 范围时抛出错误。
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0) |
++----------------------------------------------------------------------------------+
+| ['x=18abc','x=17bcd']                                                            |
++----------------------------------------------------------------------------------+
+```
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2) |
++----------------------------------------------------------------------------------+
+| ['abc','bcd']                                                                    |
++----------------------------------------------------------------------------------+
+```
+
+未参与匹配的捕获组在结果中以空字符串表示：
+
+```sql
+mysql> SELECT regexp_extract_all('a b', '(a)|(b)', 2);
++------------------------------------------+
+| regexp_extract_all('a b', '(a)|(b)', 2)  |
++------------------------------------------+
+| ['','b']                                 |
++------------------------------------------+
+```
+
+组索引越界时抛出错误：
+
+```sql
+SELECT regexp_extract_all('abc', '(b)', 2);
+```
+```text
+ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]The value of parameter(s) `idx` in `regexp_extract_all` is invalid: Expects group index between 0 and 1, but got 2.
+```
 
 ## 返回值
 

i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/regexp-extract-all.md

@@ -43,7 +43,7 @@ Doris 支持通过会话变量 `enable_extended_regex`（默认为 `false`）来
 ## 语法
 
 ```sql
-REGEXP_EXTRACT_ALL(<str>, <pattern>)
+REGEXP_EXTRACT_ALL(<str>, <pattern>[, <idx>])
 ```
 
 ## 参数
@@ -52,6 +52,53 @@ REGEXP_EXTRACT_ALL(<str>, <pattern>)
 | -- | -- |
 | `<str>` | 该参数为 String 类型。表示要执行正则表达式匹配的输入字符串。可以是字面值字符串或包含字符串数据的表列引用。|
 | `<pattern>` | 该参数也为 String 类型。指定用于与输入字符串 <str> 匹配的正则表达式模式。该模式可以包含各种正则表达式构造，如字符类、量词和子模式。|
+| `<idx>` | 可选。该参数为 BIGINT 类型。指定提取第几个捕获组：`0` 表示整体匹配，`1` 表示第一个捕获组（默认值），以此类推。取值必须在 `0` 到 `<pattern>` 捕获组数量之间，否则抛出错误。未参与某次匹配的捕获组在结果中以空字符串表示。|
+
+## 提取指定的捕获组
+
+默认情况下，`REGEXP_EXTRACT_ALL` 提取第一个捕获组。可选参数 `<idx>` 用于指定其他捕获组，语义与 Spark 一致：
+
+- `idx = 0` 提取整体匹配，此时模式中可以不包含任何捕获组。
+- `idx = N` 提取第 N 个捕获组。
+- `idx` 超出 `[0, 捕获组数量]` 范围时抛出错误。
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0) |
++----------------------------------------------------------------------------------+
+| ['x=18abc','x=17bcd']                                                            |
++----------------------------------------------------------------------------------+
+```
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2) |
++----------------------------------------------------------------------------------+
+| ['abc','bcd']                                                                    |
++----------------------------------------------------------------------------------+
+```
+
+未参与匹配的捕获组在结果中以空字符串表示：
+
+```sql
+mysql> SELECT regexp_extract_all('a b', '(a)|(b)', 2);
++------------------------------------------+
+| regexp_extract_all('a b', '(a)|(b)', 2)  |
++------------------------------------------+
+| ['','b']                                 |
++------------------------------------------+
+```
+
+组索引越界时抛出错误：
+
+```sql
+SELECT regexp_extract_all('abc', '(b)', 2);
+```
+```text
+ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]The value of parameter(s) `idx` in `regexp_extract_all` is invalid: Expects group index between 0 and 1, but got 2.
+```
 
 ## 返回值
 

versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/regexp-extract-all.md

@@ -23,7 +23,7 @@ Supported character matching types when the session variable `enable_extended_re
 ## Syntax
 
 ```sql
-REGEXP_EXTRACT_ALL(<str>, <pattern>)
+REGEXP_EXTRACT_ALL(<str>, <pattern>[, <idx>])
 ```
 
 ## Parameters
@@ -32,6 +32,7 @@ REGEXP_EXTRACT_ALL(<str>, <pattern>)
 | -- | -- |
 | `<str>` | This parameter is of type String. It represents the input string on which the regular expression matching will be performed. This can be a literal string value or a reference to a column in a table that contains string data.|
 | `<pattern>` | This parameter is also of type String. It specifies the regular expression pattern that will be used to match against the input string <str>. The pattern can include various regular expression constructs such as character classes, quantifiers, and sub - patterns.|
+| `<idx>` | Optional. This parameter is of type BIGINT. It specifies which capturing group to extract. `0` means the whole match, `1` means the first capturing group (the default), and so on. The value must be between `0` and the number of capturing groups in `<pattern>`; otherwise an error is thrown. Groups that do not participate in a match contribute an empty string to the result.|
 
 ## Return value
 
@@ -64,6 +65,52 @@ Pattern modifiers only take effect when using the default regex engine. If `enab
 | `(?U)`  | Non-greedy quantifiers: `*`, `+`, etc. match as little as possible           |
 | `(?-U)` | Greedy quantifiers (default): `*`, `+`, etc. match as much as possible       |
 
+## Extracting a specific capturing group
+
+By default, `REGEXP_EXTRACT_ALL` extracts the first capturing group. The optional `<idx>` parameter selects a different group, following the same contract as Spark:
+
+- `idx = 0` extracts the whole match. In this form the pattern does not need any capturing group.
+- `idx = N` extracts the N-th capturing group.
+- An `idx` outside the range `[0, number_of_capturing_groups]` raises an error.
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 0) |
++----------------------------------------------------------------------------------+
+| ['x=18abc','x=17bcd']                                                            |
++----------------------------------------------------------------------------------+
+```
+
+```sql
+mysql> SELECT regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2);
++----------------------------------------------------------------------------------+
+| regexp_extract_all('x=a3&x=18abc&x=2&y=3&x=4&x=17bcd', 'x=([0-9]+)([a-z]+)', 2) |
++----------------------------------------------------------------------------------+
+| ['abc','bcd']                                                                    |
++----------------------------------------------------------------------------------+
+```
+
+Groups that do not participate in a match contribute an empty string:
+
+```sql
+mysql> SELECT regexp_extract_all('a b', '(a)|(b)', 2);
++------------------------------------------+
+| regexp_extract_all('a b', '(a)|(b)', 2)  |
++------------------------------------------+
+| ['','b']                                 |
++------------------------------------------+
+```
+
+An out-of-range group index raises an error:
+
+```sql
+SELECT regexp_extract_all('abc', '(b)', 2);
+```
+```text
+ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]The value of parameter(s) `idx` in `regexp_extract_all` is invalid: Expects group index between 0 and 1, but got 2.
+```
+
 ## Example
 
 Basic matching of lowercase letters around 'C'.In this example, the pattern ([[:lower:]]+)C([[:lower:]]+) matches the part of the string where one or more lowercase letters are followed by 'C' and then one or more lowercase letters. The first sub - pattern ([[:lower:]]+) before 'C' matches 'b', so the result is ['b'].