zclllyybb commented on code in PR #2694: URL: https://github.com/apache/doris-website/pull/2694#discussion_r2262202178
########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## Review Comment: 过长导致为null的case呢？ ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -70,92 +70,107 @@ yyyy-MM-dd HH:mm:ss ## 返回值 -格式化后的日期字符串，特殊情况： - -- 当前支持最大 128 字节的字符串，如果返回值长度超过 128，则返回 NULL。 +格式化后的日期字符串。 +特殊情况： +- 若输入参数无效（如格式错误的日期 ( 例如 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. ## 举例 ```sql -select date_format('2009-10-04 22:23:00', '%W %M %Y'); -``` +-- 输出星期名、月名、4位年份 +select date_format(cast('2009-10-04 22:23:00' as datetime), '%W %M %Y'); -```text -+------------------------------------------------+ -| date_format('2009-10-04 22:23:00', '%W %M %Y') | -+------------------------------------------------+ -| Sunday October 2009 | -+------------------------------------------------+ -``` ++------------------------------------------------------------------+ +| date_format(cast('2009-10-04 22:23:00' as datetime), '%W %M %Y') | ++------------------------------------------------------------------+ +| Sunday October 2009 | ++------------------------------------------------------------------+ -```sql +-- 输出24小时制时间（时:分:秒） select date_format('2007-10-04 22:23:00', '%H:%i:%s'); -``` -```text +------------------------------------------------+ | date_format('2007-10-04 22:23:00', '%H:%i:%s') | +------------------------------------------------+ | 22:23:00 | +------------------------------------------------+ -``` -```sql -select date_format('1900-10-04 22:23:00', '%D %y %a %d %m %b %j'); -``` +-- 组合多种格式符和普通字符 +select date_format('1900-10-04 22:23:00', 'Day: %D, Year: %y, Month: %b, DayOfYear: %j'); -```text -+------------------------------------------------------------+ -| date_format('1900-10-04 22:23:00', '%D %y %a %d %m %b %j') | -+------------------------------------------------------------+ -| 4th 00 Thu 04 10 Oct 277 | -+------------------------------------------------------------+ -``` ++-----------------------------------------------------------------------------------+ +| date_format('1900-10-04 22:23:00', 'Day: %D, Year: %y, Month: %b, DayOfYear: %j') | ++-----------------------------------------------------------------------------------+ +| Day: 4th, Year: 00, Month: Oct, DayOfYear: 277 | ++-----------------------------------------------------------------------------------+ -```sql -select date_format('1997-10-04 22:23:00', '%H %k %I %r %T %S %w'); -``` +-- %X（年份）与 %V（周数）搭配（星期日为周首） +select date_format('1999-01-01 00:00:00', '%X-%V'); -```text -+------------------------------------------------------------+ -| date_format('1997-10-04 22:23:00', '%H %k %I %r %T %S %w') | -+------------------------------------------------------------+ -| 22 22 10 10:23:00 PM 22:23:00 00 6 | -+------------------------------------------------------------+ -``` - -```sql -select date_format('1999-01-01 00:00:00', '%X %V'); -``` - -```text +---------------------------------------------+ -| date_format('1999-01-01 00:00:00', '%X %V') | +| date_format('1999-01-01 00:00:00', '%X-%V') | +---------------------------------------------+ -| 1998 52 | +| 1998-52 | +---------------------------------------------+ -``` - -```sql -select date_format('2006-06-01', '%d'); -``` -```text -+------------------------------------------+ -| date_format('2006-06-01 00:00:00', '%d') | -+------------------------------------------+ -| 01 | -+------------------------------------------+ -``` - -```sql -select date_format('2006-06-01', '%%%d'); -``` +-- 输出 % 字符（需用 %% 转义） +select date_format(cast('2006-06-01' as date), '%%%d/%m'); + ++----------------------------------------------------+ +| date_format(cast('2006-06-01' as date), '%%%d/%m') | ++----------------------------------------------------+ +| %01/06 | ++----------------------------------------------------+ + +---特殊的格式 yyyy-MM-dd HH:mm:ss +select date_format('2023-12-31 23:59:59', 'yyyy-MM-dd HH:mm:ss'); ++-----------------------------------------------------------+ +| date_format('2023-12-31 23:59:59', 'yyyy-MM-dd HH:mm:ss') | ++-----------------------------------------------------------+ +| 2023-12-31 23:59:59 | ++-----------------------------------------------------------+ + +---特殊格式 yyyyMMdd +select date_format('2023-12-31 23:59:59', 'yyyyMMdd'); ++------------------------------------------------+ +| date_format('2023-12-31 23:59:59', 'yyyyMMdd') | ++------------------------------------------------+ +| 20231231 | ++------------------------------------------------+ -```text -+--------------------------------------------+ -| date_format('2006-06-01 00:00:00', '%%%d') | -+--------------------------------------------+ -| %01 | -+--------------------------------------------+ +---特殊格式 yyyy-MM-dd +select date_format('2023-12-31 23:59:59', 'yyyy-MM-dd'); ++--------------------------------------------------+ +| date_format('2023-12-31 23:59:59', 'yyyy-MM-dd') | ++--------------------------------------------------+ +| 2023-12-31 | ++--------------------------------------------------+ + +---参数为 null +mysql> select date_format(NULL, '%Y-%m-%d'); ++-------------------------------+ +| date_format(NULL, '%Y-%m-%d') | ++-------------------------------+ +| NULL | ++-------------------------------+ + +---datetime 无效 + +mysql> select date_format('2023-12-32 23:59:59', 'yyyy-MM-dd'); Review Comment: 这种case和严格模式还有关系，不糅合了 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc.md: ########## @@ -7,7 +7,7 @@ ## 描述 -将 datetime 按照指定的时间单位截断。 +DATE_TRUNC 函数用于将日期或时间值（`datetime`）按照指定的时间单位（`time_unit`）截断，即保留指定单位及更高层级的时间信息，将更低层级的时间信息清零。例如，按 “小时” 截断时，会保留年、月、日、小时，将分钟、秒等清零。 Review Comment: 按照year的话，month、day的“清零”是什么含义？并非set to zero ########## i18n/zh-CN/docusaurus-plugin-content-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) 文档。 Review Comment: [xxx](../../../../admin-manual/cluster-management/time-zone) ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/curdate.md: ########## @@ -39,6 +40,7 @@ SELECT CURDATE(); ``` ```sql +---获取当前的日期以数字表示 Review Comment: 这种case不要了，直接删掉吧，和函数本身没啥关系。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## Review Comment: 应该把时区offset上下限测到，以及非null输入算出null的case。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-add.md: ########## @@ -7,7 +7,11 @@ ## 描述 -向日期添加指定的时间间隔。 +DATE_ADD 函数用于向指定的日期或时间值添加指定的时间间隔，并返回计算后的结果。 + +- 支持的输入日期类型包括 DATE、DATETIME、TIMESTAMP，或符合格式的字符串（如 '2023-12-31'、'2023-12-31 23:59:59'）。 Review Comment: TIMESTAMP是啥？ ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -47,10 +47,10 @@ DATE_FORMAT(<date>, <format>) | %S | 秒 (00-59) | | %s | 秒 (00-59) | | %T | 时间，24-小时 (hh:mm:ss) | -| %U | 周 (00-53) 星期日是一周的第一天。[WEEK](./week) 模式0 | -| %u | 周 (00-53) 星期一是一周的第一天。[WEEK](./week) 模式1 | -| %V | 周 (01-53) 星期日是一周的第一天。[WEEK](./week) 模式2，与 %X 使用 | -| %v | 周 (01-53) 星期一是一周的第一天。[WEEK](./week) 模式3，与 %x 使用 | +| %U | 周 (00-53) 星期日是一周的第一天 | Review Comment: dont remove ########## i18n/zh-CN/docusaurus-plugin-content-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) 文档。 Review Comment: 链接用相对路径 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md: ########## @@ -17,81 +17,134 @@ | 参数 | 说明 | | -- | -- | -| `datetime` | 参数是合法的日期表达式 | -| `period` | 参数是指定每个周期有多少个单位组成，开始的时间起点为 0001-01-01T00:00:00 | -| `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 | Review Comment: WEEK放到合适的地方 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -70,92 +70,107 @@ yyyy-MM-dd HH:mm:ss ## 返回值 -格式化后的日期字符串，特殊情况： - -- 当前支持最大 128 字节的字符串，如果返回值长度超过 128，则返回 NULL。 +格式化后的日期字符串。 +特殊情况： +- 若输入参数无效（如格式错误的日期 ( 例如 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. Review Comment: 当使用FE常量折叠执行时。。。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/datediff.md: ########## @@ -19,35 +19,77 @@ DATEDIFF(<expr1>, <expr2>) | 参数 | 说明 | | -- | -- | -| `<expr1>` | 日期被减数 | -| `<expr2>` | 日期减数 | +| `<expr1>` | 日期被减数，支持的类型为 `datetime` 或者 `date` 类型和符合格式的字符串类型, 最高有六位秒数的精度(如 2022-12-28 23:59:59.999999) | +| `<expr2>` | 日期减数,支持的类型为 `date` 和 `datetime` | ## 返回值 返回 expr1 - expr2 的值，结果精确到天。 +特殊情况: +- 若输入参数无效（如格式错误的日期 ( 例如 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。 +- 若输入任一参数为 NULL, 返回 NULL. + ## 举例 ```sql + +-- 两个日期相差1天（忽略时间部分） select datediff(CAST('2007-12-31 23:59:59' AS DATETIME), CAST('2007-12-30' AS DATETIME)); -``` -```text +-----------------------------------------------------------------------------------+ | datediff(CAST('2007-12-31 23:59:59' AS DATETIME), CAST('2007-12-30' AS DATETIME)) | +-----------------------------------------------------------------------------------+ | 1 | +-----------------------------------------------------------------------------------+ -``` -```sql +-- 前一个日期早于后一个日期，返回负数 select datediff(CAST('2010-11-30 23:59:59' AS DATETIME), CAST('2010-12-31' AS DATETIME)); -``` -```text +-----------------------------------------------------------------------------------+ | datediff(CAST('2010-11-30 23:59:59' AS DATETIME), CAST('2010-12-31' AS DATETIME)) | +-----------------------------------------------------------------------------------+ | -31 | +-----------------------------------------------------------------------------------+ + +--- 任一参数为 NULL +mysql> select datediff('2023-01-01', NULL); ++------------------------------+ +| datediff('2023-01-01', NULL) | ++------------------------------+ +| NULL | ++------------------------------+ + +---含有无效日期，返回 NULL +mysql> select datediff('2023-02-30', '2023-01-01'); ++--------------------------------------+ +| datediff('2023-02-30', '2023-01-01') | ++--------------------------------------+ +| NULL | ++--------------------------------------+ + +---跨年度的计算 +mysql> mysql -uroot -P9031 -h127.0.0.1 ++--------------------------------------+ +| datediff('2024-03-01', '2023-12-31') | ++--------------------------------------+ +| 61 | ++--------------------------------------+ + + +---日期不在范围[0000-01-01,9999-12-31]之内，返回 NULL +mysql> select datediff(cast('20241-03-01' as date), '2023-12-31'); ++-----------------------------------------------------+ +| datediff(cast('20241-03-01' as date), '2023-12-31') | ++-----------------------------------------------------+ +| NULL | ++-----------------------------------------------------+ + +---若输入 datetime 类型，会忽略时间部分 +select datediff('2023-01-02 13:00:00', '2023-01-01 12:00:00'); Review Comment: 再测一个arg0的time 小于arg1的time，才能证明忽略时间部分 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
