[doc](fix) fix_datefunction_convert_to_datediff #2694

dwdwqfwe · 2025-08-02T17:31:55Z

Versions

dev
3.0
2.1
2.0

Languages

Chinese
English

Docs Checklist

Checked by AI
Test Cases Built

zclllyybb · 2025-08-02T19:12:01Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md

@@ -7,8 +7,7 @@

 ## 描述

-转换 datetime 值，从 from_tz 给定时区转到 to_tz 给定时区，并返回结果值。特殊情况：
- 如果参数无效该函数返回 NULL。
+转换 datetime 值，从 from_tz 给定时区转到 to_tz 给定时区，并返回结果值,时区设置请观看 time-zone 文档。


观看 -> 查看。
文档要给个内链，内链用相对路径，不带文件后缀名

zclllyybb · 2025-08-02T19:12:22Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md

-| `<dt>` | 需要被转换的 datetime 值 |
-| `<from_tz>` | dt 的原始时区 |
-| `<to_tz>` | 需要转换的时区 |
+| `<dt>` | 需要被转换的值,为 `datetime` 或者 `date` 类型，最高有六位秒数的精度(如 23:59:59.999999) |


例子错误，23:59:59.999999不是一个合法的datetime或date

zclllyybb · 2025-08-02T19:12:44Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md


 ## 返回值

-转换后的 datetime 值
+转换后的 timestamp 值
+对于不带有 scale 的 datetime 输入, 返回结果也不带有 scale, 带有 scale 的输入，返回也没有scale


“带有 scale 的输入，返回也没有scale”？

zclllyybb · 2025-08-02T19:13:36Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md

+转换后的 timestamp 值
+对于不带有 scale 的 datetime 输入, 返回结果也不带有 scale, 带有 scale 的输入，返回也没有scale
+特殊情况:
+- 如果参数无效（如无效的 datetime 格式、不存在的时区标识等），该函数返回 NULL。


无效的datetime格式是什么？

zclllyybb · 2025-08-02T19:16:31Z

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

-向日期添加指定的时间间隔。
+DATE_ADD 函数用于向指定的日期或时间值添加指定的时间间隔，并返回计算后的结果。
+
+- 支持的输入日期类型包括 DATE、DATETIME、TIMESTAMP，或符合格式的字符串（如 '2023-12-31'、'2023-12-31 23:59:59'）。


下面参数列表写了“待处理的日期 / 时间值。支持类型：DATE,DATETIME”，这里怎么会还接受字符串呢？

zclllyybb · 2025-08-02T19:22:51Z

...nt-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md

- 当前支持最大 128 字节的字符串，如果返回值长度超过 128，则返回 NULL。
+格式化后的日期字符串。
+特殊情况：
+- 输入日期无效（如 '2023-13-01'）返回 NULL。


这个函数还有长度限制问题。

zclllyybb · 2025-08-02T19:25:47Z

...ntent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/datediff.md

@@ -29,25 +29,47 @@ DATEDIFF(<expr1>, <expr2>)
 ## 举例

 ```sql
+
+-- 两个日期相差1天（忽略时间部分）


这里需要一些关键例子：
2000-01-01 12:00:00 和 2000-01-02
2000-01-03 12:00:00 和 2000-01-02 13:00:00
来说明忽略time部分。

zclllyybb · 2025-08-02T19:26:49Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-floor.md

+-------------------------------------------------------+
+
+---datetime 无效，返回 NULL
+mysql> select date_floor("2023-02-30 22:28:18", INTERVAL 5 DAY); 


0是否也无效？给个例子

zclllyybb · 2025-08-08T07:39:09Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md

@@ -7,8 +7,7 @@

 ## 描述

-转换 datetime 值，从 from_tz 给定时区转到 to_tz 给定时区，并返回结果值。特殊情况：
- 如果参数无效该函数返回 NULL。
+转换 datetime 值，从 from_tz 给定时区转到 to_tz 给定时区，并返回结果值,时区设置请查看 [时区管理](https://doris.apache.org/zh-CN/docs/3.0/admin-manual/cluster-management/time-zone) 文档。


链接用相对路径

zclllyybb · 2025-08-08T07:41:09Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md

应该把时区offset上下限测到，以及非null输入算出null的case。

zclllyybb · 2025-08-08T07:44:21Z

...ontent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/curdate.md

@@ -39,6 +40,7 @@ SELECT CURDATE();
 ```

 ```sql
+---获取当前的日期以数字表示


这种case不要了，直接删掉吧，和函数本身没啥关系。

zclllyybb · 2025-08-08T07:44:42Z

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

-向日期添加指定的时间间隔。
+DATE_ADD 函数用于向指定的日期或时间值添加指定的时间间隔，并返回计算后的结果。
+
+- 支持的输入日期类型包括 DATE、DATETIME、TIMESTAMP，或符合格式的字符串（如 '2023-12-31'、'2023-12-31 23:59:59'）。


TIMESTAMP是啥？

zclllyybb · 2025-08-08T07:45:25Z

...tent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md

-| `type` | 参数可以是：YEAR, MONTH, DAY, HOUR, MINUTE, SECOND |
+| `datetime` | 参数是合法的日期表达式，支持输入 为 `datetime` 或者 `date` 类型和符合格式的字符串类型 |
+| `period` | 参数是指定每个周期有多少个单位组成，类型为 INT ，开始的时间起点为 0001-01-01T00:00:00 |
+| `type` | 参数可以是：YEAR, MONTH, DAY, HOUR, MINUTE, SECOND,WEEK |


WEEK放到合适的地方

zclllyybb · 2025-08-08T07:49:13Z

...nt-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md

过长导致为null的case呢？

zclllyybb · 2025-08-08T07:50:37Z

...ent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc.md

@@ -7,7 +7,7 @@

 ## 描述

-将 datetime 按照指定的时间单位截断。
+DATE_TRUNC 函数用于将日期或时间值（`datetime`）按照指定的时间单位（`time_unit`）截断，即保留指定单位及更高层级的时间信息，将更低层级的时间信息清零。例如，按 “小时” 截断时，会保留年、月、日、小时，将分钟、秒等清零。


按照year的话，month、day的“清零”是什么含义？并非set to zero

zclllyybb · 2025-08-08T07:55:27Z

...ntent-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/datediff.md

+-----------------------------------------------------+
+
+---若输入 datetime 类型，会忽略时间部分
+select datediff('2023-01-02 13:00:00', '2023-01-01 12:00:00');


再测一个arg0的time 小于arg1的time，才能证明忽略时间部分

zclllyybb · 2025-08-08T08:01:06Z

...nt-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md

-| %u     | 周 (00-53) 星期一是一周的第一天。[WEEK](./week) 模式1    |
-| %V     | 周 (01-53) 星期日是一周的第一天。[WEEK](./week) 模式2，与 %X 使用 |
-| %v     | 周 (01-53) 星期一是一周的第一天。[WEEK](./week) 模式3，与 %x 使用 |
+| %U     | 周 (00-53) 星期日是一周的第一天    |


dont remove

zclllyybb · 2025-08-08T08:01:43Z

...nt-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md

+- 若输入参数无效（如格式错误的日期 ( 例如 2022-02-32 13:21:03, 具体 datetime 和 date 格式请查看 [datetime 的转换](https://doris.apache.org/zh-CN/docs/dev/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion/) 和 [date 的转换](https://doris.apache.org/zh-CN/docs/dev/sql-manual/basic-element/sql-data-types/conversion/date-conversion/))), 返回 NULL。
+- `format` 为 NULL 或空字符串 返回 NULL。
+- 任一参数为 NULL 返回 NULL。
+- 如果返回值超过 128 字符长度，返回 NULL. 


当使用FE常量折叠执行时。。。

Copilot

Pull Request Overview

This pull request updates and standardizes the documentation for date/time functions across multiple Doris versions. The changes improve function descriptions, parameter documentation, and provide comprehensive examples with MySQL compatibility references.

Enhanced function descriptions with detailed explanations of behavior and purpose
Standardized parameter documentation with proper type specifications and format references
Added comprehensive examples covering edge cases, error scenarios, and MySQL compatibility notes

Reviewed Changes

Copilot reviewed 72 out of 72 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
datediff.md	Enhanced description, added comprehensive examples and MySQL compatibility reference
date.md	Improved function description, added edge case examples and MySQL compatibility
date-trunc.md	Detailed behavior explanation, comprehensive examples with error cases
date-sub.md	Enhanced with MySQL compatibility notes and comprehensive parameter documentation
date-format.md	Improved format specifier documentation and added extensive examples
date-floor.md	Detailed period-based behavior explanation with comprehensive examples
date-ceil.md	Enhanced with period-based rounding documentation and error case examples
date-add.md	Added MySQL compatibility notes and comprehensive parameter documentation
curtime.md	Added MySQL compatibility reference
current-timestamp.md	Enhanced description and added MySQL compatibility reference
curdate.md	Improved description and added MySQL compatibility reference
convert-tz.md	Enhanced with comprehensive time zone conversion examples

Comments suppressed due to low confidence (2)

versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc.md:1

Inconsistent capitalization in the type parameter values. 'Quarter' should be 'QUARTER' to match the other uppercase values.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-08-29T02:16:37Z

..._docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md

+-- Invalid parameter, period is negative
+mysql> select date_ceil("2023-01-13 22:28:18",interval -5 month);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can`t be negative or zero


The word 'can`t' should use an apostrophe instead of a backtick: 'can't'.

Suggested change

ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can`t be negative or zero

ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can't be negative or zero

Copilot · 2025-08-29T02:16:38Z

..._docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md

+-- Invalid parameter, period is negative
+mysql> select date_ceil("2023-01-13 22:28:18",interval -5 month);
+ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can`t be negative or zero


The word 'can`t' should use an apostrophe instead of a backtick: 'can't'.

Suggested change

ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can`t be negative or zero

ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can't be negative or zero

Copilot · 2025-08-29T02:16:38Z

...rsion-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/current-timestamp.md

 +---------------------+-------------------------+----------------------------+
 | now()               | now(3)                  | now(6)                     |
 +---------------------+-------------------------+----------------------------+
 | 2025-01-23 11:26:01 | 2025-01-23 11:26:01.771 | 2025-01-23 11:26:01.771000 |
 +---------------------+-------------------------+----------------------------+
+
+---Return NULL if input NULL


Missing article in the comment: should be '-- Return NULL if input is NULL' or '-- Returns NULL if input is NULL'.

Suggested change

---Return NULL if input NULL

-- Return NULL if input is NULL

zclllyybb requested changes Aug 2, 2025

View reviewed changes

zclllyybb reviewed Aug 8, 2025

View reviewed changes

dwdwqfwe force-pushed the date_c_to_date_function branch from 1131d39 to 811cb8e Compare August 13, 2025 02:04

dwdwqfwe force-pushed the date_c_to_date_function branch 2 times, most recently from 9bd2555 to e338019 Compare August 27, 2025 11:39

zclllyybb requested a review from Copilot August 29, 2025 02:15

Copilot AI reviewed Aug 29, 2025

View reviewed changes

dwdwqfwe force-pushed the date_c_to_date_function branch from 5843d7e to c93cda0 Compare September 9, 2025 02:10

jh-v1

f4029cb

dwdwqfwe force-pushed the date_c_to_date_function branch from c93cda0 to f4029cb Compare September 9, 2025 02:15

dwdwqfwe and others added 2 commits September 9, 2025 14:17

jh-b2

8905f87

Merge branch 'master' into date_c_to_date_function

87d527f

	ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can`t be negative or zero
	ERROR 1105 (HY000): errCode = 2, detailMessage = (10.16.10.3)[INVALID_ARGUMENT]Operation month_ceil of 2023-01-13 22:28:18, -5 input wrong parameters, period can't be negative or zero

[doc](fix) fix_datefunction_convert_to_datediff #2694

Are you sure you want to change the base?

[doc](fix) fix_datefunction_convert_to_datediff #2694

Uh oh!

Conversation

dwdwqfwe commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Versions

Languages

Docs Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dwdwqfwe commented Aug 2, 2025 •

edited

Loading