This is an automated email from the ASF dual-hosted git repository.
Mryange 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 2dd2b1e9007 [doc](function) Correct SQL function examples and
edge-case behavior (#4201)
2dd2b1e9007 is described below
commit 2dd2b1e90074d26a90761116f3a7595c49ae4ae6
Author: Mryange <[email protected]>
AuthorDate: Sat Oct 10 14:32:37 2026 +0800
[doc](function) Correct SQL function examples and edge-case behavior (#4201)
[doc](function) Correct SQL function examples and edge-case behavior
Correct four SQL function pages where examples or edge-case descriptions
disagree with existing behavior:
- Document WEEK mode normalization as `mode & 7`, including mode 8
versus modes 0 and 7.
- Document the empty array returned by SPLIT_BY_STRING for an empty
source string.
- Use TO_IPV4 in IPV4_CIDR_TO_RANGE examples, correct the /16 upper
bound, and document NULL propagation.
- Document zero arrays for a NULL MULTI_SEARCH_ALL_POSITIONS haystack
and empty arrays for NULL needles.
Synchronize English and Chinese pages for dev, 4.x, and 3.x. Function
implementations, page paths, and navigation are unchanged.
Validation: manually executed constant and nullable-column SQL with FE
folding, BE folding, and folding disabled on Doris `9a5f86ec82b`.
Checked 4.0/4.1 source compatibility, metadata, code fences,
version/language coverage, and `git diff --check`. The website build was
not run.
## Versions
- [x] dev
- [x] 4.x
- [x] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync
---
.../scalar-functions/date-time-functions/week.md | 22 +++++++++--
.../ip-functions/ipv4-cidr-to-range.md | 42 +++++++++++++++++----
.../string-functions/multi-search-all-positions.md | 18 ++++++++-
.../string-functions/split-by-string.md | 4 +-
.../scalar-functions/date-time-functions/week.md | 22 +++++++++--
.../ip-functions/ipv4-cidr-to-range.md | 44 +++++++++++++++++-----
.../string-functions/multi-search-all-positions.md | 18 ++++++++-
.../string-functions/split-by-string.md | 4 +-
.../scalar-functions/date-time-functions/week.md | 16 ++++++++
.../ip-functions/ipv4-cidr-to-range.md | 14 +++----
.../string-functions/multi-search-all-positions.md | 16 ++++++++
.../string-functions/split-by-string.md | 12 ++++++
.../scalar-functions/date-time-functions/week.md | 23 +++++++++--
.../ip-functions/ipv4-cidr-to-range.md | 44 +++++++++++++++++-----
.../string-functions/multi-search-all-positions.md | 18 ++++++++-
.../string-functions/split-by-string.md | 4 +-
.../scalar-functions/date-time-functions/week.md | 16 ++++++++
.../ip-functions/ipv4-cidr-to-range.md | 14 +++----
.../string-functions/multi-search-all-positions.md | 16 ++++++++
.../string-functions/split-by-string.md | 12 ++++++
.../scalar-functions/date-time-functions/week.md | 22 +++++++++--
.../ip-functions/ipv4-cidr-to-range.md | 42 +++++++++++++++++----
.../string-functions/multi-search-all-positions.md | 18 ++++++++-
.../string-functions/split-by-string.md | 4 +-
24 files changed, 390 insertions(+), 75 deletions(-)
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index 4c0f1387978..f426ba17f6a 100644
--- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -37,16 +37,32 @@ WEEK(`<date_or_time_expr>`, `<mode>`)
| Parameter | Description |
|-----------|-------------|
| `<date_or_time_expr>` | Input datetime value, supports
DATE/DATETIME/TIMESTAMP_NS types. For datetime and date formats, please refer
to [datetime
conversion](../../../../sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../sql-manual/basic-element/sql-data-types/conversion/date-conversion)|
-| `mode` | Specified calculation method for the first week of the year, type
INT, range 0-7 |
+| `<mode>` | Optional INT, default 0. The calculation rule is determined by
`mode & 7`, selecting mode 0-7 from the table above. |
## Return Value
Returns INT type, representing the week number for the specified date, with
specific range determined by `<mode>` (0-53 or 1-53).
-- If `<mode>` is an integer outside 0-7, calculation is performed using Mode 7;
+- If `<mode>` is an integer outside 0-7, its lowest three bits (`mode & 7`)
determine the calculation mode. For example, 8 selects mode 0, 9 selects mode
1, and -1 selects mode 7;
- If any parameter is NULL, returns NULL;
- Cross-year dates may return the last week of the previous year (e.g.,
January 1, 2023 belongs to week 52 of 2022 in some modes).
## Examples
+
+Out-of-range modes use their lowest three bits. For example, 8 selects mode 0:
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```sql
-- 2020-01-01 is Wednesday, the first Sunday of the year is 2020-01-05, so it
belongs to week 0
SELECT WEEK('2020-01-01') AS week_result;
@@ -74,7 +90,7 @@ SELECT
| 1 | 52 |
+--------+--------+
--- Input outside 0-7 range, processed as mode 7
+-- -1 & 7 = 7, so mode 7 is used
SELECT WEEK('2023-01-01', -1) AS week_result;
+-------------+
| week_result |
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/docs/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index ebe1216c0b0..82493305c57 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -15,12 +15,16 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
```
### Parameters
-- `<ipv4_address>`: IPv4 type address
-- `<cidr_prefix>`: CIDR prefix length (SMALLINT type, range 0-32)
+| Parameter | Description |
+|-----------|-------------|
+| `<ipv4_address>` | An IPv4 address. Use `TO_IPV4` to convert an address
string to IPv4; `INET_ATON` returns BIGINT and cannot be used for this
parameter. |
+| `<cidr_prefix>` | CIDR prefix length, SMALLINT type, range 0-32. |
### Return Value
Return Type: STRUCT<min: IPv4, max: IPv4>
+Returns NULL if either parameter is NULL.
+
Return Value Meaning:
- Returns a struct containing two fields:
- `min`: Minimum IPv4 address of the network segment
@@ -35,7 +39,9 @@ Return Value Meaning:
Calculate address range for /24 network segment.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 24) as range;
+```
+```text
+------------------------------------------------+
| range |
+------------------------------------------------+
@@ -45,19 +51,23 @@ SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as
range;
Calculate address range for /16 network segment.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('10.0.0.1'), 16) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('10.0.0.1'), 16) as range;
+```
+```text
+----------------------------------------------+
| range |
+----------------------------------------------+
-| {"min": "10.0.0.0", "max": "10.255.255.255"} |
+| {"min": "10.0.0.0", "max": "10.0.255.255"} |
+----------------------------------------------+
```
Access specific fields in the struct.
```sql
SELECT
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).min as min_ip,
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).max as max_ip;
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).min as min_ip,
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).max as max_ip;
+```
+```text
+------------+--------------+
| min_ip | max_ip |
+------------+--------------+
@@ -67,10 +77,26 @@ SELECT
CIDR prefix out of range throws an exception.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 33);
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 33);
+```
+```text
ERROR 1105 (HY000): errCode = 2, detailMessage =
(...)[INVALID_ARGUMENT]Illegal cidr value '33'
```
+NULL inputs:
+
+```sql
+SELECT ipv4_cidr_to_range(NULL, 24) AS null_address,
+ ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), NULL) AS null_prefix;
+```
+```text
++--------------+-------------+
+| null_address | null_prefix |
++--------------+-------------+
+| NULL | NULL |
++--------------+-------------+
+```
+
### Keywords
IPV4_CIDR_TO_RANGE
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/docs/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index 1188634285c..6d8bd15e45f 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -31,7 +31,8 @@ Special cases:
- Position counting starts from 1
- If substring is not found, the corresponding position returns 0
- Search is case-sensitive
-- If `<haystack>` or `<needles>` is NULL, returns NULL
+- If `<haystack>` is NULL, returns an array of zeros with the same length as
`<needles>`
+- If `<needles>` is NULL, returns an empty array `[]`, including when both
parameters are NULL
- Returns byte position, not the n-th character position
## Examples
@@ -96,6 +97,21 @@ SELECT multi_search_all_positions('ṭṛì ḍḍumai Hello',
['ṭṛì', 'Hel
+----------------------------------------------------------------------------------------+
```
+NULL inputs:
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
### Keywords
MULTI_SEARCH,SEARCH,POSITIONS
diff --git
a/docs/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/docs/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index 4da6a234778..0b99afc29c1 100644
---
a/docs/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/docs/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -34,7 +34,7 @@ Splitting rules:
Special cases:
- If any parameter is NULL, returns NULL
-- If str is empty string, returns array with one empty string [""]
+- If str is an empty string, returns an empty array `[]`
- If separator is empty string, str is split by characters (each character
becomes an array element)
- If separator doesn't exist in str, returns array containing the original
string
- If str contains only separators, returns corresponding number of empty
strings based on separator count
@@ -97,7 +97,7 @@ SELECT SPLIT_BY_STRING('', ','), SPLIT_BY_STRING('hello',
'xyz');
+---------------------------+----------------------------------+
| SPLIT_BY_STRING('', ',') | SPLIT_BY_STRING('hello', 'xyz') |
+---------------------------+----------------------------------+
-| [""] | ["hello"] |
+| [] | ["hello"] |
+---------------------------+----------------------------------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index 5c953bf9f55..12fb001706f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -35,16 +35,32 @@ WEEK(`<date_or_time_expr>`,`<mode>`)
| 参数 | 描述 |
|----------------------------|-----------------------------|
| `<datetime_or_date>` | 输入的日期时间值，支持输入 DATE/DATETIME/TIMESTAMP_NS 类型，具体
datetime 和 date 格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
-| `mode` | 指定的一年第一周规则计算方法，为 INT 类型，范围为 0-7|
+| `<mode>` | 可选，INT 类型，默认值为 0。计算规则由 `mode & 7` 决定，对应上表中的模式 0-7。|
## 返回值
返回类型为 INT，表示指定日期对应的星期数，具体范围由 `<mode>` 决定（0-53 或 1-53）。
-- 若 `<mode>` 为非 0-7 的整数，则以 Mode 7 进行计算；
+- 若 `<mode>` 为非 0-7 的整数，则使用其低 3 位（`mode & 7`）对应的模式计算。例如，8 对应模式 0，9 对应模式 1，-1
对应模式 7；
- 若任一参数为 NULL，返回 NULL；
- 跨年日期可能返回上一年的最后一周（如 2023 年 1 月 1 日在部分模式下属于 2022 年第 52 周）。
## 举例
+
+越界 mode 使用其低 3 位。例如，8 对应模式 0：
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```sql
-- 2020-01-01是星期三，当年第一个周日是2020-01-05，故属于第0周
@@ -81,7 +97,7 @@ SELECT WEEK('2023-01-01', 7) AS week_result;
| 52 |
+-------------+
----输入范围不是 0-7 的整数，以 mode 7 进行处理
+-- -1 & 7 = 7，因此使用模式 7
SELECT WEEK('2023-01-01', -1) AS week_result;
+-------------+
| week_result |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index 9f3b11b22c4..ec43b72ccd6 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -20,12 +20,16 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
```
### 参数
-- `<ipv4_address>`：IPv4 类型的地址
-- `<cidr_prefix>`：CIDR 前缀长度（SMALLINT 类型，范围 0-32）
+| 参数 | 说明 |
+|------|------|
+| `<ipv4_address>` | IPv4 类型的地址。可使用 `TO_IPV4` 将地址字符串转换为 IPv4；`INET_ATON` 返回
BIGINT，不能用作此参数。 |
+| `<cidr_prefix>` | CIDR 前缀长度，SMALLINT 类型，范围 0-32。 |
### 返回值
返回类型：STRUCT<min: IPv4, max: IPv4>
+任一参数为 NULL 时返回 NULL。
+
返回值含义：
- 返回一个结构体，包含两个字段：
- `min`：网段的最小 IPv4 地址
@@ -40,7 +44,9 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
计算 /24 网段的地址范围。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 24) as range;
+```
+```text
+----------------------------------------+
| range |
+----------------------------------------+
@@ -50,19 +56,23 @@ SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as
range;
计算 /16 网段的地址范围。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('10.0.0.1'), 16) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('10.0.0.1'), 16) as range;
+```
+```text
+----------------------------------------+
| range |
+----------------------------------------+
-| {"min": "10.0.0.0", "max": "10.255.255.255"} |
+| {"min": "10.0.0.0", "max": "10.0.255.255"} |
+----------------------------------------+
```
访问结构体中的具体字段。
```sql
SELECT
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).min as min_ip,
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).max as max_ip;
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).min as min_ip,
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).max as max_ip;
+```
+```text
+-------------+-------------+
| min_ip | max_ip |
+-------------+-------------+
@@ -72,12 +82,26 @@ SELECT
CIDR 前缀超出范围会抛出异常。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 33);
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 33);
+```
+```text
ERROR 1105 (HY000): errCode = 2, detailMessage =
(...)[INVALID_ARGUMENT]Illegal cidr value '33'
```
-### Keywords
+NULL 输入：
-IPV4_CIDR_TO_RANGE
+```sql
+SELECT ipv4_cidr_to_range(NULL, 24) AS null_address,
+ ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), NULL) AS null_prefix;
+```
+```text
++--------------+-------------+
+| null_address | null_prefix |
++--------------+-------------+
+| NULL | NULL |
++--------------+-------------+
+```
+### Keywords
+IPV4_CIDR_TO_RANGE
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index ab0587e7f33..8e91d03e235 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -31,7 +31,8 @@ MULTI_SEARCH_ALL_POSITIONS(<haystack>, <needles>)
- 位置从 1 开始计数
- 如果子串未找到，对应位置返回 0
- 查找是大小写敏感的
-- 如果 `<haystack>` 或 `<needles>` 为 NULL，返回 NULL
+- 如果 `<haystack>` 为 NULL，返回与 `<needles>` 长度相同、元素均为 0 的数组
+- 如果 `<needles>` 为 NULL，返回空数组 `[]`，包括两个参数均为 NULL 的情况
- 返回的是字节位置，不是第 n 个字符位置
## 示例
@@ -96,6 +97,21 @@ SELECT multi_search_all_positions('ṭṛì ḍḍumai Hello',
['ṭṛì', 'Hel
+----------------------------------------------------------------------------------------+
```
+NULL 输入：
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
### Keywords
MULTI_SEARCH,SEARCH,POSITIONS
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index cf0bf8e9f9a..7c96b67244b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -34,7 +34,7 @@ SPLIT_BY_STRING(<str>, <separator>)
特殊情况：
- 如果任意参数为 NULL，返回 NULL
-- 如果 str 为空字符串，返回包含一个空字符串的数组 [""]
+- 如果 str 为空字符串，返回空数组 `[]`
- 如果 separator 为空字符串，str 会按字符进行拆分（每个字符成为数组的一个元素）
- 如果 separator 在 str 中不存在，返回包含原字符串的数组
- 如果 str 只包含分隔符，根据分隔符数量返回相应数量的空字符串
@@ -97,7 +97,7 @@ SELECT SPLIT_BY_STRING('', ','), SPLIT_BY_STRING('hello',
'xyz');
+---------------------------+----------------------------------+
| SPLIT_BY_STRING('', ',') | SPLIT_BY_STRING('hello', 'xyz') |
+---------------------------+----------------------------------+
-| [""] | ["hello"] |
+| [] | ["hello"] |
+---------------------------+----------------------------------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index 04e87a6c6ac..68eb2da37af 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -28,6 +28,22 @@
参数为 Date 或者 Datetime 类型
## 举例
+
+越界 mode 使用其低 3 位。例如，8 对应模式 0：
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```
mysql> select week('2020-1-1');
+------------------+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index 029243a674f..34d1ddff575 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -17,7 +17,7 @@ IPV4_CIDR_TO_RANGE(<ip_v4>, <cidr>)
## 参数
| Parameter | Description |
|-----------|--------------------------------------------------|
-| `<ip_v4>` | 字符串类型的 ipv4 地址 |
+| `<ip_v4>` | IPv4 类型的地址，可使用 `TO_IPV4` 转换地址字符串；`INET_ATON` 和
`ipv4_string_to_num` 返回 BIGINT，不能用作此参数 |
| `<cidr>` | cidr 值 |
## 返回值
@@ -27,12 +27,12 @@ IPV4_CIDR_TO_RANGE(<ip_v4>, <cidr>)
## 举例
```sql
-SELECT ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16) as re1,
ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) as re2, ipv4_cidr_to_range(NULL,
NULL) as re3;
+SELECT ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) as re1,
ipv4_cidr_to_range(NULL, NULL) as re3;
```
```text
-+------------------------------------------------+------------------------------------------------+------+
-| re1 | re2
| re3 |
-+------------------------------------------------+------------------------------------------------+------+
-| {"min":"192.168.0.0", "max":"192.168.255.255"} | {"min":"192.168.0.0",
"max":"192.168.255.255"} | NULL |
-+------------------------------------------------+------------------------------------------------+------+
++------------------------------------------------+------+
+| re1 | re3 |
++------------------------------------------------+------+
+| {"min":"192.168.0.0", "max":"192.168.255.255"} | NULL |
++------------------------------------------------+------+
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index fe4084f9e46..cbf86805f7e 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -16,6 +16,22 @@
## 举例
+NULL 输入：
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
+
```
mysql> select multi_search_all_positions('Hello, World!', ['hello', '!',
'world']);
+----------------------------------------------------------------------+
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index b7e0b724fed..39e5fee097d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -28,10 +28,22 @@ SPLIT_BY_STRING ( <str>, <separator> )
返回按照指定的字符串拆分成字符串数组。特殊情况：
- 任意参数中有一个为 NULL，则返回 NULL
+- 如果 `<str>` 为空字符串，返回空数组 `[]`
- `<separator>`为空字符串时，`<str>`会按字节进行拆分
## 举例
+```sql
+SELECT split_by_string('', ',') AS result;
+```
+```text
++--------+
+| result |
++--------+
+| [] |
++--------+
+```
+
```sql
SELECT split_by_string('hello','l');
```
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index aae0a49f2c5..cf52ff04194 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -35,16 +35,32 @@ WEEK(`<date_or_time_expr>`,`<mode>`)
| 参数 | 描述 |
|----------------------------|-----------------------------|
| `<datetime_or_date>` | 输入的日期时间值，支持输入 date/datetime 类型，具体 datetime 和 date
格式请查看 [datetime
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
和 [date
的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/date-conversion)
|
-| `mode` | 指定的一年第一周规则计算方法，为 INT 类型，范围为 0-7|
+| `<mode>` | 可选，INT 类型，默认值为 0。计算规则由 `mode & 7` 决定，对应上表中的模式 0-7。|
## 返回值
返回类型为 INT，表示指定日期对应的星期数，具体范围由 `<mode>` 决定（0-53 或 1-53）。
-- 若 `<mode>` 为非 0-7 的整数，则以 Mode 7 进行计算；
+- 若 `<mode>` 为非 0-7 的整数，则使用其低 3 位（`mode & 7`）对应的模式计算。例如，8 对应模式 0，9 对应模式 1，-1
对应模式 7；
- 若任一参数为 NULL，返回 NULL；
- 跨年日期可能返回上一年的最后一周（如 2023 年 1 月 1 日在部分模式下属于 2022 年第 52 周）。
## 举例
+
+越界 mode 使用其低 3 位。例如，8 对应模式 0：
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```sql
-- 2020-01-01是星期三，当年第一个周日是2020-01-05，故属于第0周
@@ -81,7 +97,7 @@ SELECT WEEK('2023-01-01', 7) AS week_result;
| 52 |
+-------------+
----输入范围不是 0-7 的整数，以 mode 7 进行处理
+-- -1 & 7 = 7，因此使用模式 7
SELECT WEEK('2023-01-01', -1) AS week_result;
+-------------+
| week_result |
@@ -105,4 +121,3 @@ SELECT WEEK('2023-12-31 23:59:59', NULL),WEEK(NULL,3);
| NULL | NULL |
+-----------------------------------+--------------+
```
-
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index 9f3b11b22c4..ec43b72ccd6 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -20,12 +20,16 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
```
### 参数
-- `<ipv4_address>`：IPv4 类型的地址
-- `<cidr_prefix>`：CIDR 前缀长度（SMALLINT 类型，范围 0-32）
+| 参数 | 说明 |
+|------|------|
+| `<ipv4_address>` | IPv4 类型的地址。可使用 `TO_IPV4` 将地址字符串转换为 IPv4；`INET_ATON` 返回
BIGINT，不能用作此参数。 |
+| `<cidr_prefix>` | CIDR 前缀长度，SMALLINT 类型，范围 0-32。 |
### 返回值
返回类型：STRUCT<min: IPv4, max: IPv4>
+任一参数为 NULL 时返回 NULL。
+
返回值含义：
- 返回一个结构体，包含两个字段：
- `min`：网段的最小 IPv4 地址
@@ -40,7 +44,9 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
计算 /24 网段的地址范围。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 24) as range;
+```
+```text
+----------------------------------------+
| range |
+----------------------------------------+
@@ -50,19 +56,23 @@ SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as
range;
计算 /16 网段的地址范围。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('10.0.0.1'), 16) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('10.0.0.1'), 16) as range;
+```
+```text
+----------------------------------------+
| range |
+----------------------------------------+
-| {"min": "10.0.0.0", "max": "10.255.255.255"} |
+| {"min": "10.0.0.0", "max": "10.0.255.255"} |
+----------------------------------------+
```
访问结构体中的具体字段。
```sql
SELECT
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).min as min_ip,
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).max as max_ip;
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).min as min_ip,
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).max as max_ip;
+```
+```text
+-------------+-------------+
| min_ip | max_ip |
+-------------+-------------+
@@ -72,12 +82,26 @@ SELECT
CIDR 前缀超出范围会抛出异常。
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 33);
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 33);
+```
+```text
ERROR 1105 (HY000): errCode = 2, detailMessage =
(...)[INVALID_ARGUMENT]Illegal cidr value '33'
```
-### Keywords
+NULL 输入：
-IPV4_CIDR_TO_RANGE
+```sql
+SELECT ipv4_cidr_to_range(NULL, 24) AS null_address,
+ ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), NULL) AS null_prefix;
+```
+```text
++--------------+-------------+
+| null_address | null_prefix |
++--------------+-------------+
+| NULL | NULL |
++--------------+-------------+
+```
+### Keywords
+IPV4_CIDR_TO_RANGE
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index ab0587e7f33..8e91d03e235 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -31,7 +31,8 @@ MULTI_SEARCH_ALL_POSITIONS(<haystack>, <needles>)
- 位置从 1 开始计数
- 如果子串未找到，对应位置返回 0
- 查找是大小写敏感的
-- 如果 `<haystack>` 或 `<needles>` 为 NULL，返回 NULL
+- 如果 `<haystack>` 为 NULL，返回与 `<needles>` 长度相同、元素均为 0 的数组
+- 如果 `<needles>` 为 NULL，返回空数组 `[]`，包括两个参数均为 NULL 的情况
- 返回的是字节位置，不是第 n 个字符位置
## 示例
@@ -96,6 +97,21 @@ SELECT multi_search_all_positions('ṭṛì ḍḍumai Hello',
['ṭṛì', 'Hel
+----------------------------------------------------------------------------------------+
```
+NULL 输入：
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
### Keywords
MULTI_SEARCH,SEARCH,POSITIONS
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index cf0bf8e9f9a..7c96b67244b 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -34,7 +34,7 @@ SPLIT_BY_STRING(<str>, <separator>)
特殊情况：
- 如果任意参数为 NULL，返回 NULL
-- 如果 str 为空字符串，返回包含一个空字符串的数组 [""]
+- 如果 str 为空字符串，返回空数组 `[]`
- 如果 separator 为空字符串，str 会按字符进行拆分（每个字符成为数组的一个元素）
- 如果 separator 在 str 中不存在，返回包含原字符串的数组
- 如果 str 只包含分隔符，根据分隔符数量返回相应数量的空字符串
@@ -97,7 +97,7 @@ SELECT SPLIT_BY_STRING('', ','), SPLIT_BY_STRING('hello',
'xyz');
+---------------------------+----------------------------------+
| SPLIT_BY_STRING('', ',') | SPLIT_BY_STRING('hello', 'xyz') |
+---------------------------+----------------------------------+
-| [""] | ["hello"] |
+| [] | ["hello"] |
+---------------------------+----------------------------------+
```
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index 5bfe7ab14ce..57878952f63 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -29,6 +29,22 @@ The following table describes how the mode argument works.
The parameter is Date or Datetime type
### example
+
+Out-of-range modes use their lowest three bits. For example, 8 selects mode 0:
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```
mysql> select week('2020-1-1');
+------------------+
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index f8c8d729c3f..0146db9649c 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -17,7 +17,7 @@ IPV4_CIDR_TO_RANGE(<ip_v4>, <cidr>)
## Parameters
| Parameter | Description |
|-----------|--------------------------------------------------|
-| `<ip_v4>` | An IPv4 address of type String |
+| `<ip_v4>` | An IPv4 address. Use `TO_IPV4` to convert an address
string; `INET_ATON` and `ipv4_string_to_num` return BIGINT and cannot be used
for this parameter. |
| `<cidr>` | The cidr value |
@@ -28,12 +28,12 @@ Returns a struct that contains two IPv4 fields representing
the lower range (min
## Example
```sql
-SELECT ipv4_cidr_to_range(ipv4_string_to_num('192.168.5.2'), 16) as re1,
ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) as re2, ipv4_cidr_to_range(NULL,
NULL) as re3;
+SELECT ipv4_cidr_to_range(to_ipv4('192.168.5.2'), 16) as re1,
ipv4_cidr_to_range(NULL, NULL) as re3;
```
```text
-+------------------------------------------------+------------------------------------------------+------+
-| re1 | re2
| re3 |
-+------------------------------------------------+------------------------------------------------+------+
-| {"min":"192.168.0.0", "max":"192.168.255.255"} | {"min":"192.168.0.0",
"max":"192.168.255.255"} | NULL |
-+------------------------------------------------+------------------------------------------------+------+
++------------------------------------------------+------+
+| re1 | re3 |
++------------------------------------------------+------+
+| {"min":"192.168.0.0", "max":"192.168.255.255"} | NULL |
++------------------------------------------------+------+
```
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index 46de55c8025..f7814e94c35 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -16,6 +16,22 @@ Returns an `ARRAY` where the `i`-th element is the position
of the `i`-th elemen
### example
+NULL inputs:
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
+
```
mysql> select multi_search_all_positions('Hello, World!', ['hello', '!',
'world']);
+----------------------------------------------------------------------+
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index 28ed4bcce0c..0d739fe44c2 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -28,10 +28,22 @@ SPLIT_BY_STRING ( <str>, <separator> )
Returns a string array split according to the specified string. Special cases:
- If any of the parameters is NULL, NULL is returned.
+- If `<str>` is an empty string, returns an empty array `[]`.
- When `<separator>` is an empty string, `<str>` will be split to byte
sequence.
## Examples
+```sql
+SELECT split_by_string('', ',') AS result;
+```
+```text
++--------+
+| result |
++--------+
+| [] |
++--------+
+```
+
```sql
SELECT split_by_string('hello','l');
```
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
index 44c0a39e45a..8a4293a2f64 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/week.md
@@ -37,16 +37,32 @@ WEEK(`<date_or_time_expr>`, `<mode>`)
| Parameter | Description |
|-----------|-------------|
| `<date_or_time_expr>` | Input datetime value, supports date/datetime types.
For datetime and date formats, please refer to [datetime
conversion](../../../../sql-manual/basic-element/sql-data-types/conversion/datetime-conversion)
and [date
conversion](../../../../sql-manual/basic-element/sql-data-types/conversion/date-conversion)|
-| `mode` | Specified calculation method for the first week of the year, type
INT, range 0-7 |
+| `<mode>` | Optional INT, default 0. The calculation rule is determined by
`mode & 7`, selecting mode 0-7 from the table above. |
## Return Value
Returns INT type, representing the week number for the specified date, with
specific range determined by `<mode>` (0-53 or 1-53).
-- If `<mode>` is an integer outside 0-7, calculation is performed using Mode 7;
+- If `<mode>` is an integer outside 0-7, its lowest three bits (`mode & 7`)
determine the calculation mode. For example, 8 selects mode 0, 9 selects mode
1, and -1 selects mode 7;
- If any parameter is NULL, returns NULL;
- Cross-year dates may return the last week of the previous year (e.g.,
January 1, 2023 belongs to week 52 of 2022 in some modes).
## Examples
+
+Out-of-range modes use their lowest three bits. For example, 8 selects mode 0:
+
+```sql
+SELECT WEEK('2021-01-01', 8) AS mode_8,
+ WEEK('2021-01-01', 0) AS mode_0,
+ WEEK('2021-01-01', 7) AS mode_7;
+```
+```text
++--------+--------+--------+
+| mode_8 | mode_0 | mode_7 |
++--------+--------+--------+
+| 0 | 0 | 52 |
++--------+--------+--------+
+```
+
```sql
-- 2020-01-01 is Wednesday, the first Sunday of the year is 2020-01-05, so it
belongs to week 0
SELECT WEEK('2020-01-01') AS week_result;
@@ -74,7 +90,7 @@ SELECT
| 1 | 52 |
+--------+--------+
--- Input outside 0-7 range, processed as mode 7
+-- -1 & 7 = 7, so mode 7 is used
SELECT WEEK('2023-01-01', -1) AS week_result;
+-------------+
| week_result |
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
index ebe1216c0b0..82493305c57 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/ip-functions/ipv4-cidr-to-range.md
@@ -15,12 +15,16 @@ IPV4_CIDR_TO_RANGE(<ipv4_address>, <cidr_prefix>)
```
### Parameters
-- `<ipv4_address>`: IPv4 type address
-- `<cidr_prefix>`: CIDR prefix length (SMALLINT type, range 0-32)
+| Parameter | Description |
+|-----------|-------------|
+| `<ipv4_address>` | An IPv4 address. Use `TO_IPV4` to convert an address
string to IPv4; `INET_ATON` returns BIGINT and cannot be used for this
parameter. |
+| `<cidr_prefix>` | CIDR prefix length, SMALLINT type, range 0-32. |
### Return Value
Return Type: STRUCT<min: IPv4, max: IPv4>
+Returns NULL if either parameter is NULL.
+
Return Value Meaning:
- Returns a struct containing two fields:
- `min`: Minimum IPv4 address of the network segment
@@ -35,7 +39,9 @@ Return Value Meaning:
Calculate address range for /24 network segment.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 24) as range;
+```
+```text
+------------------------------------------------+
| range |
+------------------------------------------------+
@@ -45,19 +51,23 @@ SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 24) as
range;
Calculate address range for /16 network segment.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('10.0.0.1'), 16) as range;
+SELECT ipv4_cidr_to_range(TO_IPV4('10.0.0.1'), 16) as range;
+```
+```text
+----------------------------------------------+
| range |
+----------------------------------------------+
-| {"min": "10.0.0.0", "max": "10.255.255.255"} |
+| {"min": "10.0.0.0", "max": "10.0.255.255"} |
+----------------------------------------------+
```
Access specific fields in the struct.
```sql
SELECT
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).min as min_ip,
- ipv4_cidr_to_range(INET_ATON('172.16.1.1'), 24).max as max_ip;
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).min as min_ip,
+ ipv4_cidr_to_range(TO_IPV4('172.16.1.1'), 24).max as max_ip;
+```
+```text
+------------+--------------+
| min_ip | max_ip |
+------------+--------------+
@@ -67,10 +77,26 @@ SELECT
CIDR prefix out of range throws an exception.
```sql
-SELECT ipv4_cidr_to_range(INET_ATON('192.168.1.1'), 33);
+SELECT ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), 33);
+```
+```text
ERROR 1105 (HY000): errCode = 2, detailMessage =
(...)[INVALID_ARGUMENT]Illegal cidr value '33'
```
+NULL inputs:
+
+```sql
+SELECT ipv4_cidr_to_range(NULL, 24) AS null_address,
+ ipv4_cidr_to_range(TO_IPV4('192.168.1.1'), NULL) AS null_prefix;
+```
+```text
++--------------+-------------+
+| null_address | null_prefix |
++--------------+-------------+
+| NULL | NULL |
++--------------+-------------+
+```
+
### Keywords
IPV4_CIDR_TO_RANGE
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
index 1188634285c..6d8bd15e45f 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/multi-search-all-positions.md
@@ -31,7 +31,8 @@ Special cases:
- Position counting starts from 1
- If substring is not found, the corresponding position returns 0
- Search is case-sensitive
-- If `<haystack>` or `<needles>` is NULL, returns NULL
+- If `<haystack>` is NULL, returns an array of zeros with the same length as
`<needles>`
+- If `<needles>` is NULL, returns an empty array `[]`, including when both
parameters are NULL
- Returns byte position, not the n-th character position
## Examples
@@ -96,6 +97,21 @@ SELECT multi_search_all_positions('ṭṛì ḍḍumai Hello',
['ṭṛì', 'Hel
+----------------------------------------------------------------------------------------+
```
+NULL inputs:
+
+```sql
+SELECT multi_search_all_positions(NULL, ['a', 'b']) AS null_haystack,
+ multi_search_all_positions('a', NULL) AS null_needles,
+ multi_search_all_positions(NULL, NULL) AS both_null;
+```
+```text
++---------------+--------------+-----------+
+| null_haystack | null_needles | both_null |
++---------------+--------------+-----------+
+| [0, 0] | [] | [] |
++---------------+--------------+-----------+
+```
+
### Keywords
MULTI_SEARCH,SEARCH,POSITIONS
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
index 4da6a234778..0b99afc29c1 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/string-functions/split-by-string.md
@@ -34,7 +34,7 @@ Splitting rules:
Special cases:
- If any parameter is NULL, returns NULL
-- If str is empty string, returns array with one empty string [""]
+- If str is an empty string, returns an empty array `[]`
- If separator is empty string, str is split by characters (each character
becomes an array element)
- If separator doesn't exist in str, returns array containing the original
string
- If str contains only separators, returns corresponding number of empty
strings based on separator count
@@ -97,7 +97,7 @@ SELECT SPLIT_BY_STRING('', ','), SPLIT_BY_STRING('hello',
'xyz');
+---------------------------+----------------------------------+
| SPLIT_BY_STRING('', ',') | SPLIT_BY_STRING('hello', 'xyz') |
+---------------------------+----------------------------------+
-| [""] | ["hello"] |
+| [] | ["hello"] |
+---------------------------+----------------------------------+
```
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
