zclllyybb commented on code in PR #2694: URL: https://github.com/apache/doris-website/pull/2694#discussion_r2346877877
########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## @@ -20,38 +21,98 @@ CONVERT_TZ(<dt>, <from_tz>, <to_tz>) | 参数 | 说明 | | -- | -- | -| `<dt>` | 需要被转换的 datetime 值 | -| `<from_tz>` | dt 的原始时区 | -| `<to_tz>` | 需要转换的时区 | +| `<date_or_time_expr>` | 需要被转换的值,为 datetime 或者 date 类型，具体 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)) | +| `<from_tz>` | dt 的原始时区,该参数为 `varchar` 类型 | +| `<to_tz>` | 需要转换的时区 ，该参数为 `varchar` 类型| ## 返回值 -转换后的 datetime 值 +- 转换后的 datetime 值 +- 返回的scale 跟输入的scale 相同 + - 不带有 scale 的 datetime 输入, 返回结果也不带有 scale + - 带有 scale 的输入，返回的结果带有 scale Review Comment: 带有相同的scale ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## @@ -20,38 +21,98 @@ CONVERT_TZ(<dt>, <from_tz>, <to_tz>) | 参数 | 说明 | | -- | -- | -| `<dt>` | 需要被转换的 datetime 值 | -| `<from_tz>` | dt 的原始时区 | -| `<to_tz>` | 需要转换的时区 | +| `<date_or_time_expr>` | 需要被转换的值,为 datetime 或者 date 类型，具体 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)) | +| `<from_tz>` | dt 的原始时区,该参数为 `varchar` 类型 | +| `<to_tz>` | 需要转换的时区 ，该参数为 `varchar` 类型| ## 返回值 -转换后的 datetime 值 +- 转换后的 datetime 值 +- 返回的scale 跟输入的scale 相同 + - 不带有 scale 的 datetime 输入, 返回结果也不带有 scale + - 带有 scale 的输入，返回的结果带有 scale + +特殊情况: +- 如果任何参数为 NULL，返回 NULL。 Review Comment: 等待行为变更 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/curtime.md: ########## Review Comment: 拆成两个文档，并说明互为别名 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/current-timestamp.md: ########## @@ -21,19 +21,28 @@ CURRENT_TIMESTAMP([<precision>]) | `<precision>` | 可选参数，表示返回值的小数秒部分的精度，取值范围为 0 到 6。默认为 0，即不返回小数秒部分。 <br/>受限于 JDK 实现，如果用户使用 JDK8 构建 FE，则精度最多支持到毫秒（小数点后三位），更大的精度位将全部填充 0。如果用户有更高精度需求，请使用 JDK11。 | ## 返回值 + - 返回当前系统时间，类型为 `DATETIME` - 如果指定的 `<precision>` 超出范围（如为负数或大于 6），函数会返回错误。 +- 如果输入 NULL, 返回 NULL ## 举例 ```sql +--不同精度返回结果 select CURRENT_TIMESTAMP(),CURRENT_TIMESTAMP(3),CURRENT_TIMESTAMP(6); Review Comment: 负数或者大于6的例子。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md: ########## @@ -7,7 +7,8 @@ ## 描述 -`date_ceil` 将日期转化为指定的时间间隔周期的最近上取整时刻。 +DATE_CEIL 函数用于将指定的日期或时间值向上取整（ceil）到最近的指定时间间隔周期的起点。即返回不小于输入日期时间的最小周期时刻，周期规则由 period（周期数量）和 type（周期单位）共同定义，且所有周期均以固定起点 0001-01-01 00:00:00 为基准计算。 Review Comment: 之前说的公式描述呢 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-sub.md: ########## Review Comment: 同date-add ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date.md: ########## @@ -6,34 +6,70 @@ --- ## 描述 -提取日期时间中的日期。 +DATE 函数用于从日期时间值（包含日期和时间）中提取出纯日期部分，忽略时间信息。该函数可将 DATETIME 类型转换为 DATE 类型，仅保留年、月、日信息。 + +该函数与 mysql 中的 [date 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_date) 行为一致 ## 语法 ```sql -DATE(<datetime>) +DATE(<date_or_time_part>) ``` ## 参数 | 参数 | 说明 | | -- | -- | -| `<datetime>` | 合法的日期表达式 | +| `<date_or_time_part>` | 合法的日期表达式,支持的类型为 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)) | ## 返回值 -返回日期时间的日期部分。 +若输入有效，返回 DATE 类型的纯日期值（格式为 YYYY-MM-DD），不含时间部分。 +特殊情况： +- 输入为 NULL 时，返回 NULL； ## 举例 ```sql -select date('2010-12-02 19:28:30'); -``` +---提取日期时间中的日期部分 +mysql> select date(cast('2010-12-02 19:28:30' as datetime)); ++-----------------------------------------------+ +| date(cast('2010-12-02 19:28:30' as datetime)) | ++-----------------------------------------------+ +| 2010-12-02 | ++-----------------------------------------------+ + + +--- 提取日期中的日期部分 +mysql> select date(cast('2015-11-02' as date)); ++----------------------------------+ +| date(cast('2015-11-02' as date)) | ++----------------------------------+ +| 2015-11-02 | ++----------------------------------+ + +-- 支持不同分隔符的日期时间字符串(具体日期格式支持那些写法请观看日期类型文档) +mysql> select date('2023/04/01 08:30:00'); ++-----------------------------+ +| date('2023/04/01 08:30:00') | ++-----------------------------+ +| 2023-04-01 | ++-----------------------------+ + +---输入为NULL +mysql> select date(NULL); ++------------+ +| date(NULL) | ++------------+ +| NULL | ++------------+ + + +mysql> select date('0000-00-00 12:00:00'); Review Comment: 这种case不要了，之前提过的，等同于输入null ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-add.md: ########## @@ -7,7 +7,18 @@ ## 描述 -向日期添加指定的时间间隔。 +DATE_ADD 函数用于向指定的日期或时间值添加指定的时间间隔，并返回计算后的结果。 + +- 支持的输入日期类型包括 DATE、DATETIME，或符合格式的字符串（如 '2023-12-31'、'2023-12-31 23:59:59'）。 Review Comment: 不涉及字符串cast，只说明支持date、DATETIME ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md: ########## @@ -17,93 +18,120 @@ | 参数 | 说明 | | -- | -- | -| `datetime` | 参数是合法的日期表达式 | -| `period` | 参数是指定每个周期有多少个单位组成，开始的时间起点为 0001-01-01T00:00:00 | -| `type` | 参数可以是：YEAR, QUARTER, MONTH, DAY, HOUR, MINUTE, SECOND | +| `date_or_time_expr` | 参数是合法的日期表达式，支持输入 为 datetime 或者 date 类型,具体 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))| +| `period` | 参数是指定每个周期有多少个单位组成，类型为 INT ，开始的时间起点为 0001-01-01T00:00:00 | +| `type` | 参数可以是：YEAR, Quarter, MONTH, WEEK ,DAY, HOUR, MINUTE, SECOND| ## 返回值 返回的是一个日期或时间值，表示将输入值向上舍入到指定单位的结果。 +返回与 datetime 类型一致的取整结果： +- 输入 DATE 时，返回 DATE（仅日期部分，时间默认为 00:00:00）； +- 输入 DATETIME，返回 DATETIME（包含日期和时间）。 +- 对于带有 scale 的 datetime, 返回值也会带有 scale. +特殊情况： Review Comment: 这里是不是应该有个换行 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/curdate.md: ########## @@ -22,11 +24,12 @@ CURDATE() ## 返回值 -当前的日期。 +当前的日期,返回值为 date 类型。 ## 示例 ```sql +---获取当前的日期 SELECT CURDATE(); ``` Review Comment: 输入和输出之间是否放在同一个sql block中，还是像这样拆分为sql+text block？所有文档需要统一 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/curtime.md: ########## @@ -22,9 +22,9 @@ CURTIME() ## 返回值 -返回当前的时间 +返回当前时间。 Review Comment: 类型 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## @@ -20,38 +21,98 @@ CONVERT_TZ(<dt>, <from_tz>, <to_tz>) | 参数 | 说明 | | -- | -- | -| `<dt>` | 需要被转换的 datetime 值 | -| `<from_tz>` | dt 的原始时区 | -| `<to_tz>` | 需要转换的时区 | +| `<date_or_time_expr>` | 需要被转换的值,为 datetime 或者 date 类型，具体 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)) | +| `<from_tz>` | dt 的原始时区,该参数为 `varchar` 类型 | +| `<to_tz>` | 需要转换的时区 ，该参数为 `varchar` 类型| ## 返回值 -转换后的 datetime 值 +- 转换后的 datetime 值 Review Comment: 转换后的值，类型为 `DATETIME` ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/current-timestamp.md: ########## @@ -21,19 +21,28 @@ CURRENT_TIMESTAMP([<precision>]) | `<precision>` | 可选参数，表示返回值的小数秒部分的精度，取值范围为 0 到 6。默认为 0，即不返回小数秒部分。 <br/>受限于 JDK 实现，如果用户使用 JDK8 构建 FE，则精度最多支持到毫秒（小数点后三位），更大的精度位将全部填充 0。如果用户有更高精度需求，请使用 JDK11。 | Review Comment: 关于JDK的描述删掉 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## @@ -20,38 +21,98 @@ CONVERT_TZ(<dt>, <from_tz>, <to_tz>) | 参数 | 说明 | | -- | -- | -| `<dt>` | 需要被转换的 datetime 值 | -| `<from_tz>` | dt 的原始时区 | -| `<to_tz>` | 需要转换的时区 | +| `<date_or_time_expr>` | 需要被转换的值,为 datetime 或者 date 类型，具体 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)) | +| `<from_tz>` | dt 的原始时区,该参数为 `varchar` 类型 | +| `<to_tz>` | 需要转换的时区 ，该参数为 `varchar` 类型| ## 返回值 -转换后的 datetime 值 +- 转换后的 datetime 值 +- 返回的scale 跟输入的scale 相同 + - 不带有 scale 的 datetime 输入, 返回结果也不带有 scale + - 带有 scale 的输入，返回的结果带有 scale + +特殊情况: +- 如果任何参数为 NULL，返回 NULL。 +- 当输入的时区不合法的时候，返回NULL。 时区的设置参考 [时区管理](../../../../admin-manual/cluster-management/time-zone)。 +- 输入为date类型，时间部分自动转换为 00:00:00 ## 示例 ```sql -select CONVERT_TZ('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles'); -``` -```text +---中国上海时间转换到美国洛杉矶 +mysql> select CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATETIME), 'Asia/Shanghai', 'America/Los_Angeles'); +---------------------------------------------------------------------------+ -| convert_tz('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles') | +| CONVERT_TZ('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles') | +---------------------------------------------------------------------------+ | 2019-07-31 22:21:03 | +---------------------------------------------------------------------------+ -``` -```sql -select CONVERT_TZ('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles'); -``` +---将 东八区（+08:00）的时间 '2019-08-01 13:21:03' 转换为 美国洛杉矶 +select CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATETIME), '+08:00', 'America/Los_Angeles'); -```text +--------------------------------------------------------------------+ | convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles') | +--------------------------------------------------------------------+ | 2019-07-31 22:21:03 | +--------------------------------------------------------------------+ -``` + +---输入为date类型，时间部分自动转换为 00:00:00 +mysql> select CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATE), 'Asia/Shanghai', 'America/Los_Angeles'); ++-------------------------------------------------------------------------------------------+ +| CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATEV2), 'Asia/Shanghai', 'America/Los_Angeles') | ++-------------------------------------------------------------------------------------------+ +| 2019-07-31 09:00:00 | ++-------------------------------------------------------------------------------------------+ + Review Comment: 注意换行情况 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/convert-tz.md: ########## @@ -20,38 +21,98 @@ CONVERT_TZ(<dt>, <from_tz>, <to_tz>) | 参数 | 说明 | | -- | -- | -| `<dt>` | 需要被转换的 datetime 值 | -| `<from_tz>` | dt 的原始时区 | -| `<to_tz>` | 需要转换的时区 | +| `<date_or_time_expr>` | 需要被转换的值,为 datetime 或者 date 类型，具体 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)) | +| `<from_tz>` | dt 的原始时区,该参数为 `varchar` 类型 | +| `<to_tz>` | 需要转换的时区 ，该参数为 `varchar` 类型| ## 返回值 -转换后的 datetime 值 +- 转换后的 datetime 值 +- 返回的scale 跟输入的scale 相同 + - 不带有 scale 的 datetime 输入, 返回结果也不带有 scale + - 带有 scale 的输入，返回的结果带有 scale + +特殊情况: +- 如果任何参数为 NULL，返回 NULL。 +- 当输入的时区不合法的时候，返回NULL。 时区的设置参考 [时区管理](../../../../admin-manual/cluster-management/time-zone)。 +- 输入为date类型，时间部分自动转换为 00:00:00 ## 示例 ```sql -select CONVERT_TZ('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles'); -``` -```text +---中国上海时间转换到美国洛杉矶 +mysql> select CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATETIME), 'Asia/Shanghai', 'America/Los_Angeles'); +---------------------------------------------------------------------------+ -| convert_tz('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles') | +| CONVERT_TZ('2019-08-01 13:21:03', 'Asia/Shanghai', 'America/Los_Angeles') | +---------------------------------------------------------------------------+ | 2019-07-31 22:21:03 | +---------------------------------------------------------------------------+ -``` -```sql -select CONVERT_TZ('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles'); -``` +---将 东八区（+08:00）的时间 '2019-08-01 13:21:03' 转换为 美国洛杉矶 +select CONVERT_TZ(CAST('2019-08-01 13:21:03' AS DATETIME), '+08:00', 'America/Los_Angeles'); -```text +--------------------------------------------------------------------+ | convert_tz('2019-08-01 13:21:03', '+08:00', 'America/Los_Angeles') | +--------------------------------------------------------------------+ | 2019-07-31 22:21:03 | +--------------------------------------------------------------------+ -``` + +---输入为date类型，时间部分自动转换为 00:00:00 Review Comment: ---输入为 DATE 类型，输出 DATETIME 类型 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md: ########## @@ -17,93 +18,120 @@ | 参数 | 说明 | | -- | -- | -| `datetime` | 参数是合法的日期表达式 | -| `period` | 参数是指定每个周期有多少个单位组成，开始的时间起点为 0001-01-01T00:00:00 | -| `type` | 参数可以是：YEAR, QUARTER, MONTH, DAY, HOUR, MINUTE, SECOND | +| `date_or_time_expr` | 参数是合法的日期表达式，支持输入 为 datetime 或者 date 类型,具体 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))| +| `period` | 参数是指定每个周期有多少个单位组成，类型为 INT ，开始的时间起点为 0001-01-01T00:00:00 | +| `type` | 参数可以是：YEAR, Quarter, MONTH, WEEK ,DAY, HOUR, MINUTE, SECOND| Review Comment: 注意大小写 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/current-timestamp.md: ########## Review Comment: 说明是now的别名函数，保持文档内容一致 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -47,10 +49,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) 星期日是一周的第一天, [week](./week),模式 0 | +| %u | 周 (00-53) 星期一是一周的第一天 [week](./week),模式 1 | Review Comment: 空格，标点符号保持一致 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-floor.md: ########## Review Comment: 和ceil相同 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc.md: ########## @@ -7,7 +7,9 @@ ## 描述 -将 datetime 按照指定的时间单位截断。 +DATE_TRUNC 函数用于将日期或时间值（datetime）按照指定的时间单位（time_unit）截断，即保留指定单位及更高层级的时间信息，将更低层级的时间信息清至最小日期时间。例如，按 “小时” 截断时，会保留年、月、日、小时，将分钟、秒等清零，按照年截断时，会把日，月截断为 xxxx-01-01。 + +该函数与 postgresql 中的 [date_trunc函数](https://www.postgresql.org/docs/16/functions-datetime.html#FUNCTIONS-DATETIME-TRUNC) 行为基本一致,不同的是,doris暂不支持 second 单位以下的截断， postgresql 支持到 microsecond 。 Review Comment: 注意下中英文，标点之间的空格 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-floor.md: ########## @@ -17,108 +17,79 @@ | 参数 | 说明 | | -- | -- | -| `datetime` | 参数是合法的日期表达式 | -| `period` | 参数是指定每个周期有多少个单位组成，开始的时间起点为 0001-01-01T00:00:00 | -| `type` | 参数可以是：YEAR, QUARTER, MONTH, DAY, HOUR, MINUTE, SECOND | +| `date_or_time_expr` | 参数是合法的日期表达式，类型为 为 datetime 或者 date 类型,具体 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)) | +| `period` | 参数是指定每个周期有多少个单位组成,为 `INT` 类型，开始的时间起点为 0001-01-01T00:00:00 | +| `type` | 参数可以是：YEAR, MONTH, WEEK,DAY, HOUR, MINUTE, SECOND | ## 返回值 -返回的是一个日期或时间值，表示将输入值向下舍入到指定单位的结果。 +返回一个日期按照 period 周期向下取整的结果，类型和 datetime 保持一致 +返回与 datetime 类型一致的取整结果： +- 输入 DATE 时，返回 DATE（仅日期部分，时间默认为 00:00:00）； +- 输入 DATETIME 时，返回 DATETIME（包含日期和时间）。 +- 输入带有 scale 的日期时间，返回值也会带有 scale +特殊情况： +- 任何参数为 NULL 时，返回 NULL； +- 非法 period（非正整数）或 type 时，返回错误； +举例 Review Comment: ？ ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc.md: ########## @@ -20,107 +22,100 @@ DATE_TRUNC(<time_unit>, <datetime>) | 参数 | 说明 | | -- | -- | -| `<datetime>` | 合法的日期表达式 | +| `<date_or_time_part>` | 合法的日期表达式,类型为 datetime 或者 date 类型,具体 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)) | | `<time_unit>` | 希望截断的时间间隔，可选的值如下：[`second`,`minute`,`hour`,`day`,`week`,`month`,`quarter`,`year`] | ## 返回值 -按照指定的时间单位截断的时间 +返回与 datetime 类型一致的截断结果： +- 输入 DATE 时，返回 DATE（仅日期部分，时间默认为 00:00:00）； Review Comment: date并没有时间部分，不存在默认，看下类似的表述 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -70,92 +72,106 @@ yyyy-MM-dd HH:mm:ss Review Comment: 说明一下这三种特殊格式分别是什么含义（对应到标准的是什么格式） ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date.md: ########## @@ -6,34 +6,70 @@ --- ## 描述 -提取日期时间中的日期。 +DATE 函数用于从日期时间值（包含日期和时间）中提取出纯日期部分，忽略时间信息。该函数可将 DATETIME 类型转换为 DATE 类型，仅保留年、月、日信息。 + +该函数与 mysql 中的 [date 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_date) 行为一致 ## 语法 ```sql -DATE(<datetime>) +DATE(<date_or_time_part>) ``` ## 参数 | 参数 | 说明 | | -- | -- | -| `<datetime>` | 合法的日期表达式 | +| `<date_or_time_part>` | 合法的日期表达式,支持的类型为 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)) | ## 返回值 -返回日期时间的日期部分。 +若输入有效，返回 DATE 类型的纯日期值（格式为 YYYY-MM-DD），不含时间部分。 +特殊情况： +- 输入为 NULL 时，返回 NULL； ## 举例 ```sql -select date('2010-12-02 19:28:30'); -``` +---提取日期时间中的日期部分 +mysql> select date(cast('2010-12-02 19:28:30' as datetime)); ++-----------------------------------------------+ +| date(cast('2010-12-02 19:28:30' as datetime)) | ++-----------------------------------------------+ +| 2010-12-02 | ++-----------------------------------------------+ + + +--- 提取日期中的日期部分 +mysql> select date(cast('2015-11-02' as date)); ++----------------------------------+ +| date(cast('2015-11-02' as date)) | ++----------------------------------+ +| 2015-11-02 | ++----------------------------------+ + +-- 支持不同分隔符的日期时间字符串(具体日期格式支持那些写法请观看日期类型文档) +mysql> select date('2023/04/01 08:30:00'); Review Comment: 这个函数并不支持字符串输入，实际上都是先做了到DATETIME的转换，所以这个case和类似的表述可以去掉。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/date-format.md: ########## @@ -70,92 +72,106 @@ yyyy-MM-dd HH:mm:ss ## 返回值 -格式化后的日期字符串，特殊情况： - -- 当前支持最大 128 字节的字符串，如果返回值长度超过 128，则返回 NULL。 +格式化后的日期字符串,类型为 Varchar。 +特殊情况： +- format 为 NULL 或空字符串 返回 NULL。 +- 任一参数为 NULL 返回 NULL。 +- 如果返回值超过 128 字符长度 并且在 BE 执行的情况下，返回 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'); -``` -```text -+------------------------------------------------------------+ -| date_format('1900-10-04 22:23:00', '%D %y %a %d %m %b %j') | -+------------------------------------------------------------+ -| 4th 00 Thu 04 10 Oct 277 | -+------------------------------------------------------------+ -``` - -```sql -select date_format('1997-10-04 22:23:00', '%H %k %I %r %T %S %w'); -``` +-- 组合多种格式符和普通字符 +select date_format('1900-10-04 22:23:00', 'Day: %D, Year: %y, Month: %b, DayOfYear: %j'); -```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 | -+------------------------------------------------------------+ -``` ++-----------------------------------------------------------------------------------+ +| 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('1999-01-01 00:00:00', '%X %V'); -``` +-- %X（年份）与 %V（周数）搭配（星期日为周首） +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 | ++-----------------------------------------------------------+ + +---匹配字符串未引用任何时间的结果 +select date_format('2023-12-31 23:59:59', 'ghg'); ++-------------------------------------------+ +| date_format('2023-12-31 23:59:59', 'ghg') | ++-------------------------------------------+ +| ghg | ++-------------------------------------------+ + +---特殊格式 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 | ++-------------------------------+ + + +---超出函数返回字符串长度范围，返回 NULL +mysql> select date_format('2022-01-12',repeat('a',129)); Review Comment: 等待行为变更 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/datediff.md: ########## @@ -19,35 +21,63 @@ DATEDIFF(<expr1>, <expr2>) | 参数 | 说明 | | -- | -- | -| `<expr1>` | 日期被减数 | -| `<expr2>` | 日期减数 | +| `<expr1>` | 日期被减数，支持的类型为 datetime 或者 date 类型,具体 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)) | +| `<expr2>` | 日期减数,支持的类型为 date 和 datetime | ## 返回值 -返回 expr1 - expr2 的值，结果精确到天。 +返回 expr1 - expr2 的值，结果精确到天,类型为 INT。 + +特殊情况: +- expr1 大于 expr2 ,返回正数，反之返回负数 +- 若输入任一参数为 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 | ++------------------------------+ + + Review Comment: 换行数量 -- 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]
