[Feature](func) Support function PERIOD_ADD and PERIOD_DIFF

docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md

@@ -0,0 +1,80 @@
+---
+{
+    "title": "PERIOD_ADD",
+    "language": "en"
+}
+---
+
+## Description
+Calculate the result of increasing the `<period>` by `<month>` months.
+
+The `<period>` is an integer, the last two digits represent the month (01-12), and the preceding digits represent the year.
+The function returns the calculated period in the format of an integer (year + month).
+
+If the year part is less than 100, it will be processed into a four-digit year format according to [certain rules](#parameters).
+For example: PERIOD_ADD(2501, 0) will return 202501, not 2501.
+
+This function behaves consistently with MySQL's [PERIOD_ADD function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-add).
+
+## Syntax
+
+```sql
+PERIOD_ADD(`<period>`, `month`)
+```
+
+## Parameters
+
+| Parameter  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<period>` | represents a period composed of year and month. <ul><li>**Format**: The month occupies the last two digits, which must be within the range `[1, 12]`. The preceding digits represent the year, and the number of digits for the year is unlimited; it can exceed four digits.</li><li>**Year Inference**: The year value is directly taken from all digits except the last two. If the year is a two-digit number (range: [00, 99]), if the year is less than 70, it is interpreted as 20YY; if it is 70 or greater, it is interpreted as 19YY.</li><li>**Value Range**: Accepts integer parameters within the range `[0, 2^63-1]`.</li></ul> |
+| `<month>`  | The number of months to add to `<period>`. Accepts integer values in the range `[-2^63, 2^63-1]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+
+## Return Value
+
+Returns an integer representing the calculated period in YYYYMM format. As noted in the parameter description, the year part is not limited to four digits.
+
+If any parameter is NULL, or if the `period` parameter cannot be converted to BIGINT, the function returns NULL.
+
+If the `period` parameter is negative or its month part is invalid, the function will throw an error.
+
+## Examples
+
+```sql
+SELECT `period`, `month`, PERIOD_ADD(`period`, `month`) AS ans FROM test_period_add;
+```
+```text
++----------+--------+----------+
+| period   | month  | ans      |
++----------+--------+----------+
+|   200803 |      2 |   200805 |
+|   200809 |      5 |   200902 |
+|      803 |      2 |   200805 |
+|     6910 |      3 |   207001 |
+|     7001 |      1 |   197002 |
+| 12345611 | 123456 | 13374411 |
+|     NULL |     10 |     NULL |
+|   202510 |   NULL |     NULL |
++----------+--------+----------+
+```
+
+```sql
+-- Month part exceeds the range [1, 12]
+SELECT PERIOD_ADD(202513, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: 202513
+
+-- Period exceeds BIGINT range
+SELECT PERIOD_ADD(-1, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
+
+```sql
+SELECT PERIOD_ADD(9223372036854775807, 1);
+```
+```text
++------------------------------------+
+| PERIOD_ADD(9223372036854775807, 1) |
++------------------------------------+
+|               -9223372036854775808 |
++------------------------------------+
+```
+Explanation: Doris uses int64_t for internal calculations, so overflow may occur. This behavior is consistent with MySQL.

docs/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md

@@ -0,0 +1,62 @@
+---
+{
+    "title": "PERIOD_DIFF",
+    "language": "en"
+}
+---
+
+## Description
+Calculates the difference in months between two periods.
+
+where `<period>` is an integer, the last two digits represent the month (01-12), and the preceding digits represent the year.
+The function returns the absolute result of period_1 - period_2.
+
+If the year part is less than 100, it will be converted to a four-digit year format according to [certain rules](#parameters).
+
+This function behaves consistently with MySQL's [PERIOD_DIFF function](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-diff).
+
+## Syntax
+
+```sql
+PERIOD_DIFF(`<period_1>`, `<period_2>`)
+```
+
+## Parameters
+
+| Parameter      | Description                                                                                     |
+|----------------|-------------------------------------------------------------------------------------------------|
+| `<period_1>`   | represents a period composed of year and month. <ul><li>**Format**: The month occupies the last two digits, which must be within the range `[1, 12]`. The preceding digits represent the year, and the number of digits for the year is unlimited; it can exceed four digits.</li><li>**Year Inference**: The year value is directly taken from all digits except the last two. If the year is a two-digit number (range: [00, 99]), if the year is less than 70, it is interpreted as 20YY; if it is 70 or greater, it is interpreted as 19YY.</li><li>**Value Range**: Accepts integer parameters within the range `[0, 2^63-1]`.</li></ul> |
+| `<period_2>`   | Represents another period. The format requirements are the same as `<period_1>`. |
+
+## Return Value
+
+Returns an integer representing the total number of months in `<period_1>` minus the total number of months in `<period_2>`.
+
+If any parameter is NULL, or if the values cannot be converted to BIGINT, the function returns NULL.
+
+If the parameters are negative or their month parts are invalid, the function will throw an error.
+
+## Examples
+
+```sql
+SELECT `period_1`, `period_2`, PERIOD_DIFF(`period_1`, `period_2`) AS DIFF FROM `test_period_diff`;
+```
+```text
++---------------------+----------+---------------------+
+| period_1            | period_2 | DIFF                |
++---------------------+----------+---------------------+
+| 200802              |   200703 |                  11 |
+| 200703              |   200802 |                 -11 |
+| 7001                |     6912 |               -1199 |
+| NULL                |     2510 |                NULL |
+| 2510                |     NULL |                NULL |
+| 9223372036854775807 |      101 | 1106804644422549090 |
+| 9223372036854775808 |      101 |                NULL |
++---------------------+----------+---------------------+
+```
+In the last row, `period_1` exceeds the BIGINT upper limit (2^63-1), so the output is NULL.
+
+```sql
+SELECT PERIOD_DIFF(1, -1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-add.md

@@ -0,0 +1,80 @@
+---
+{
+    "title": "PERIOD_ADD",
+    "language": "zh-CN"
+}
+---
+
+## 描述
+计算周期 `<period>`增加 `<month>` 个月的结果。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回计算后的周期，格式为整数（年份+月份）。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+如: PERIOD_ADD(2501, 0) 会返回 202501, 而不是2501。
+
+该函数与 MySQL 的 [PERIOD_ADD 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-add) 行为一致。
+
+## 语法
+
+```sql
+PERIOD_ADD(`<period>`, `month`)
+```
+
+## 参数
+
+| 参数            | 说明       |
+|---------------|-------------------------------------------------------|
+| `<period>` | 代表一个由年和月组成的周期。<ul><li>**格式**：月份固定占末尾两位，必须在 `[1, 12]` 范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00, 99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0, 2^63-1]` 范围内的整型参数。</li></ul> |
+| `<month>` | 在 `<period>` 基础上需要增加的月份数。接受 `[-2^63, 2^63-1]` 范围内的整型。 |
+
+## 返回值
+
+返回一个整型，代表计算之后得到的周期。格式为YYYYMM。 同参数说明，年份部分不一定为四位数字。
+
+当任一参数为 NULL，或 period 参数因数值无法转换为 BIGINT 时，返回 NULL。
+
+当 `period` 参数为负数或其月份部分无效时，函数将报错。
+
+## 举例
+
+```sql
+SELECT `period`, `month`, PERIOD_ADD(`period`, `month`) AS ans FROM test_period_add;
+```
+```text
++----------+--------+----------+
+| period   | month  | ans      |
++----------+--------+----------+
+|   200803 |      2 |   200805 |
+|   200809 |      5 |   200902 |
+|      803 |      2 |   200805 |
+|     6910 |      3 |   207001 |
+|     7001 |      1 |   197002 |
+| 12345611 | 123456 | 13374411 |
+|     NULL |     10 |     NULL |
+|   202510 |   NULL |     NULL |
++----------+--------+----------+
+```
+
+```sql
+-- 月份部分超出范围[1, 12]
+SELECT PERIOD_ADD(202513, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: 202513
+
+-- period 超出BIGINT范围
+SELECT PERIOD_ADD(-1, 1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```
+
+```sql
+SELECT PERIOD_ADD(9223372036854775807, 1);
+```
+```text
++------------------------------------+
+| PERIOD_ADD(9223372036854775807, 1) |
++------------------------------------+
+|               -9223372036854775808 |
++------------------------------------+
+```
+解释: 在 Doris 内部使用int64_t进行计算，所以会存在数值溢出的情况，此行为与 MySQL 一致。

i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff.md

@@ -0,0 +1,62 @@
+---
+{
+    "title": "PERIOD_DIFF",
+    "language": "zh-CN"
+}
+---
+
+## 描述
+计算两个周期之间的月份差值。
+
+其中 `<period>` 是一个整数，最后两位表示月份（01-12），前面的数字表示年份。
+函数返回period_1 - period_2的绝对结果。
+
+若年份部分小于 100 会按[一定规则](#参数)补为四位数年份格式处理。
+
+该函数与 MySQL 的 [PERIOD_DIFF 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_period-diff) 行为一致。
+
+## 语法
+
+```sql
+PERIOD_DIFF(`<period_1>`, `<period_2>`)
+```
+
+## 参数
+
+| 参数            | 说明       |
+|---------------|-------------------------------------------------------|
+| `<period_1>` | 代表一个由年和月组成的周期。<ul><li>**格式**：月份固定占末尾两位，必须在 `[1, 12]` 范围内。前面的数字表示年份，年份位数不限，可以超过四位。</li><li>**年份推断**：年份取值直接使用除最后两位外的所有数字。当年份为两位数(范围:[00, 99]), 此时若年份小于 70 则解读为 20YY，若大于等于 70 则解读为 19YY。</li><li>**值范围**：接受 `[0, 2^63-1]` 范围内的整型参数。</li></ul> |
+| `<period_2>` | 代表另一个周期，格式要求与 `<period_1>` 相同。 |
+
+## 返回值
+
+返回一个整型，表示`<period_1>` 的总月份数减去 `<period_2>` 的总月份数的值。
+
+当任一参数为 NULL，因数值无法转换为 BIGINT 时，返回 NULL。
+
+当参数为负数或其月份部分无效时，函数将报错。
+
+## 举例
+
+```sql
+SELECT `period_1`, `period_2`, PERIOD_DIFF(`period_1`, `period_2`) AS DIFF FROM `test_period_diff`;
+```
+```text
++---------------------+----------+---------------------+
+| period_1            | period_2 | DIFF                |
++---------------------+----------+---------------------+
+| 200802              |   200703 |                  11 |
+| 200703              |   200802 |                 -11 |
+| 7001                |     6912 |               -1199 |
+| NULL                |     2510 |                NULL |
+| 2510                |     NULL |                NULL |
+| 9223372036854775807 |      101 | 1106804644422549090 |
+| 9223372036854775808 |      101 |                NULL |
++---------------------+----------+---------------------+
+```
+最后一行中period_1超出了BIGINT的上限(2^63-1), 故输出 NULL
+
+```sql
+SELECT PERIOD_DIFF(1, -1);
+-- ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]Period function got invalid period: -1
+```

sidebars.json

@@ -1385,6 +1385,8 @@
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/months-sub",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/now",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/next-day",
+                                        "sql-manual/sql-functions/scalar-functions/date-time-functions/period-add",
+                                        "sql-manual/sql-functions/scalar-functions/date-time-functions/period-diff",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-add",
                                         "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-sub",