zclllyybb commented on code in PR #2816: URL: https://github.com/apache/doris-website/pull/2816#discussion_r2346959430
########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timediff.md: ########## @@ -6,39 +6,93 @@ --- ## 描述 -`TIMEDIFF` 函数用于计算两个日期时间值之间的差值。该函数接受两个参数，并返回其差值，结果为 `TIME` 类型。 + +TIMEDIFF 函数用于计算两个日期时间值之间的差值，并以 TIME 类型返回结果。该函数支持处理 DATETIME、DATE 类型，若输入为 DATE 类型，默认其时间部分为 00:00:00。 + +该函数与 mysql 中的 [timediff 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_timediff) 行为一致 ## 语法 ```sql -TIMEDIFF(<end_datetime>, <start_datetime>) +TIMEDIFF(<date_or_time_expr1>, <date_or_time_expr2>) ``` ## 参数 | 参数 | 说明 | |-------------------|-------------------------------| -| `<end_datetime>` | 结束的时间或日期时间值 | -| `<start_datetime>` | 开始的时间或日期时间值 | +| `<date_or_time_expr1>` | 结束的时间或日期时间值,支持输入 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) | +| `<date_or_time_expr2>` | 开始的时间或日期时间值,支持输入 date/datetime 类型 | ## 返回值 返回一个 `TIME` 类型的值，表示两个输入之间的时间差： - 当 `<end_datetime>` 晚于 `<start_datetime>` 时，返回正的时间差。 - 当 `<end_datetime>` 早于 `<start_datetime>` 时，返回负的时间差。 - 当 `<end_datetime>` 和 `<start_datetime>` 相等时，返回 `00:00:00`。 - 如果 `<end_datetime>` 或 `<start_datetime>` 为 `NULL`，函数返回 `NULL`。 -- 如果 `<end_datetime>` 或 `<start_datetime>` 为非法时间或日期时间值（如 `0000-00-00 00:00:00`），函数返回 `NULL`。 +- 当返回时间差不为整数秒时，返回时间带有 scale. +- 当计算机结果超出 time 范围[-838:59:59,828:59:59],返回错误 Review Comment: 计算结果。另外范围上界也不对吧 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/second-timestamp.md: ########## @@ -6,8 +6,7 @@ --- ## 描述 -函数将输入的 `DATETIME` 值转换为从 `1970-01-01 00:00:00 UTC` 开始的 Unix 时间戳（以秒为单位）。 - +SECOND_TIMESTAMP 函数用于将输入的日期时间值转换为 Unix 时间戳（以秒为单位），该时间戳表示从 1970-01-01 00:00:00 UTC 开始到指定日期时间的总秒数。该函数支持处理 DATETIME，该函数结果会加上机器所在的时区偏移，时区部分请查看 [时区管理](../../../../admin-manual/cluster-management/time-zone)。 Review Comment: 和unix_timestamp有什么关系？ ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/time-to-sec.md: ########## @@ -6,33 +6,102 @@ --- ## 描述 -函数将输入的 `TIME` 或 `DATETIME` 类型的值转换为以秒为单位的总时间。如果输入为 `DATETIME` 类型，函数会自动提取时间部分（`HH:MM:SS`）。 +TIME_TO_SEC 函数用于将输入的时间值转换为以秒为单位的总秒数。该函数支持处理 TIME、DATETIME 类型：若输入为 DATETIME 类型，会自动提取其中的时间部分（HH:MM:SS）进行计算；若输入为纯时间值，则直接转换为总秒数。 + +该函数与 mysql 中的 [time_to_sec 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_time-to-sec) 使用 SECOND 为单位的行为一致 Review Comment: “使用 SECOND 为单位的行为一致”多余的，看看还有没有别的复制粘贴出问题的 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timestamp.md: ########## @@ -7,30 +7,31 @@ ## 描述 -TIMESTAMP 函数有两种用法： +TIMESTAMP 将 datetime 字符串转换为 DATETIME 类型 -1. 将日期时间字符串转换为 DATETIME 类型 -2. 将两个参数组合成一个 DATETIME 类型 +具体 datetime 格式请查看 [datetime 的转换](../../../../../current/sql-manual/basic-element/sql-data-types/conversion/datetime-conversion). + +该函数与 mysql 中的 [timestamp 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_timestamp) 有些差异，doris 暂不支持带有第二个 time 参数进行日期时间增减。 ## 语法 ```sql TIMESTAMP(string) -TIMESTAMP(date, time) ``` ## 参数 | 参数 | 说明 | | ---- | ---- | -| `string` | 日期时间字符串 | -| `date` | 日期值，可以是 DATE 类型或格式正确的日期字符串 | -| `time` | 时间值，可以是 TIME 类型或格式正确的时间字符串 | +| `string` | 日期时间字符串或者 datetime 类型 | Review Comment: 描述错误 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md: ########## @@ -1,66 +1,99 @@ --- { - "title": "TIMESTAMPADD", - "language": "zh-CN" + "title": "TIMESTAMPADD", + "language": "zh-CN" } --- ## 描述 -`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个日期上。这个函数通常用于日期和时间的计算。 +与 [date_add 函数](./date-add) 作用一致 +TIMESTAMPADD 函数用于向指定的日期时间值添加（或减去）指定单位的时间间隔，并返回计算后的日期时间值。该函数支持多种时间单位（如秒、分、时、日、周、月、年等），可灵活处理日期时间的偏移计算，负数间隔表示减去对应时间。 + +该函数与 mysql 中的 [date_add 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_date-add) 行为一致 Review Comment: mysql有timestampadd ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timestamp.md: ########## @@ -7,30 +7,31 @@ ## 描述 -TIMESTAMP 函数有两种用法： +TIMESTAMP 将 datetime 字符串转换为 DATETIME 类型 Review Comment: 符合datetime格式的字符串 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/sec-to-time.md: ########## @@ -20,17 +23,62 @@ SEC_TO_TIME(<seconds>) | `<seconds>` | 必填，输入的秒数，表示从一天起点时间（00:00:00）开始计算的秒数，支持正整数或负整数类型。 | ## 返回值 -- 返回一个 TIME 类型值，格式为 `HH:MM:SS`，表示从起点时间（00:00:00）开始计算的时间。 -- 如果输入的 `<seconds>` 为 NULL，函数返回 NULL。 +返回一个秒数转换为 TIME 类型的值 +- 若输入秒数超出 TIME 类型的有效范围（-838:59:59 至 838:59:59，对应秒数范围 -3023999 至 3023999），返回错误； Review Comment: sec_to_time超出范围后不报错。 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampdiff.md: ########## @@ -1,89 +1,113 @@ --- { - "title": "TIMESTAMPDIFF", - "language": "zh-CN" + "title": "TIMESTAMPDIFF", + "language": "zh-CN" } --- ## 描述 -`timestampdiff` 函数用于计算两个日期之间的差值，返回两个日期之间的时间间隔。可以计算两者之间的差异，以指定的时间单位（支持秒、分钟、小时、天、月、季度、年）返回结果。 +与 [date-diff 函数](./datediff) 作用一致 +TIMESTAMPDIFF 函数用于计算两个日期时间值之间的差值，并以指定的时间单位返回结果。该函数支持多种时间单位（如秒、分、时、日、周、月、年） + +该函数与 mysql 中的 [date_diff 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_date-diff) 行为一致 ## 语法 -`TIMESTAMPDIFF(<unit>, <datetime_expr1>, <datetime_expr2>)` +```sql +TIMESTAMPDIFF(<unit>, <date_or_time_expr1>, <date_or_time_expr2>) +``` ## 参数 | 参数 | 说明 | | -- |-----------------------------------------------------------| -| `unit` | 时间单位，指定要返回差异的单位，支持 SECOND、MINUTE、HOUR、DAY、MONTH、QUARTER、YEAR | -|`datetime_expr1`| 第一个日期时间，合法的日期格式 | -|`datetime_expr2`| 第二个日期时间，合法的日期格式 | +| `<unit>` | 时间单位，指定要返回差异的单位，常见的值有 SECOND、MINUTE、HOUR、DAY、MONTH、QUARTERYEAR 等 | Review Comment: typo ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/timestampadd.md: ########## @@ -1,66 +1,99 @@ --- { - "title": "TIMESTAMPADD", - "language": "zh-CN" + "title": "TIMESTAMPADD", + "language": "zh-CN" } --- ## 描述 -`timestampadd` 函数用于将指定的时间单位（如年、月、日、小时、分钟、秒等）添加到一个日期上。这个函数通常用于日期和时间的计算。 +与 [date_add 函数](./date-add) 作用一致 +TIMESTAMPADD 函数用于向指定的日期时间值添加（或减去）指定单位的时间间隔，并返回计算后的日期时间值。该函数支持多种时间单位（如秒、分、时、日、周、月、年等），可灵活处理日期时间的偏移计算，负数间隔表示减去对应时间。 + +该函数与 mysql 中的 [date_add 函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_date-add) 行为一致 ## 语法 -`TIMESTAMPADD(<unit>, <interval>, <datetime_expr>)` +```sql +TIMESTAMPADD(<unit>, <interval>, <date_or_time_expr>) +``` ## 参数 | 参数 | 说明 | | -- |-------------------------------------------------------------------| -| `unit` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR | -|`interval`| 要添加的时间间隔，通常是一个整数，可以是正数或负数，表示添加或减去的时间长度 | -| `datetime_expr` | 合法的目标日期，为 `DATETIME` 类型 | +| `<unit>` | 时间单位，指定要添加的时间单位，常见的值有 SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR | Review Comment: 所有文档里这个应该统一，参数说明里的参数是否带尖括号 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 +3. 当遇到普通字母的匹配，则查看两字符串现在指针所指向的字符是否相等，不相等则返回 NULL，相等则解析下一个字符 +4. 当任日期指针指向字符串末尾时，若日期时间只包含日期部分，则格式字符串会检查是否包含匹配时间部分的字符(如 %H),若包含，则会设置时间部分为 00:00:00。 +5. 当格式字符串指向末尾时，匹配结束。 +6. 最后检查匹配时间部分是否合法(如月份必须在 [1,12] 区间内)，如果不合法，则返回 NULL，合法则返回解析出的日期时间 + + +- 若 <datetime_str> 与 <format> 格式不匹配（如字符串为 2023/13/01 而格式为 %Y-%m-%d），返回 NULL； Review Comment: 这条在上面描述了吧 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 +3. 当遇到普通字母的匹配，则查看两字符串现在指针所指向的字符是否相等，不相等则返回 NULL，相等则解析下一个字符 +4. 当任日期指针指向字符串末尾时，若日期时间只包含日期部分，则格式字符串会检查是否包含匹配时间部分的字符(如 %H),若包含，则会设置时间部分为 00:00:00。 +5. 当格式字符串指向末尾时，匹配结束。 +6. 最后检查匹配时间部分是否合法(如月份必须在 [1,12] 区间内)，如果不合法，则返回 NULL，合法则返回解析出的日期时间 + + +- 若 <datetime_str> 与 <format> 格式不匹配（如字符串为 2023/13/01 而格式为 %Y-%m-%d），返回 NULL； +- 若任一参数为 NULL，返回 NULL； +- 若 <format> 为空字符串，返回 NULL； +- 若 <datetime_str> 缺少时间部分（仅日期），解析后时间部分默认为 00:00:00；若缺少日期部分（仅时间），日期部分默认为 0000-00-00（无效日期，返回 NULL）。 Review Comment: 报错，等待行为变更，不需要描述默认为多少了 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 +3. 当遇到普通字母的匹配，则查看两字符串现在指针所指向的字符是否相等，不相等则返回 NULL，相等则解析下一个字符 Review Comment: 报错，等待行为变更 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 Review Comment: “跳过解析下一个字符串”是什么意思？ ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 +3. 当遇到普通字母的匹配，则查看两字符串现在指针所指向的字符是否相等，不相等则返回 NULL，相等则解析下一个字符 +4. 当任日期指针指向字符串末尾时，若日期时间只包含日期部分，则格式字符串会检查是否包含匹配时间部分的字符(如 %H),若包含，则会设置时间部分为 00:00:00。 +5. 当格式字符串指向末尾时，匹配结束。 +6. 最后检查匹配时间部分是否合法(如月份必须在 [1,12] 区间内)，如果不合法，则返回 NULL，合法则返回解析出的日期时间 + + +- 若 <datetime_str> 与 <format> 格式不匹配（如字符串为 2023/13/01 而格式为 %Y-%m-%d），返回 NULL； +- 若任一参数为 NULL，返回 NULL； +- 若 <format> 为空字符串，返回 NULL； +- 若 <datetime_str> 缺少时间部分（仅日期），解析后时间部分默认为 00:00:00；若缺少日期部分（仅时间），日期部分默认为 0000-00-00（无效日期，返回 NULL）。 ## 举例 -将常见的日期时间字符串转换为 DATETIME 类型 ```sql -SELECT STR_TO_DATE('2025-01-23 12:34:56', '%Y-%m-%d %H:%i:%s'),STR_TO_DATE('2025-01-23 12:34:56', 'yyyy-MM-dd HH:mm:ss'); -``` -```text -+---------------------------------------------------------+-----------------------------------------------------------+ -| str_to_date('2025-01-23 12:34:56', '%Y-%m-%d %H:%i:%s') | str_to_date('2025-01-23 12:34:56', 'yyyy-MM-dd HH:mm:ss') | -+---------------------------------------------------------+-----------------------------------------------------------+ -| 2025-01-23 12:34:56.000000 | 2025-01-23 12:34:56.000000 | -+---------------------------------------------------------+-----------------------------------------------------------+ -``` -其他 +-- 使用标准格式符解析 +SELECT STR_TO_DATE('2025-01-23 12:34:56', '%Y-%m-%d %H:%i:%s') AS result; ++---------------------+ +| result | ++---------------------+ +| 2025-01-23 12:34:56 | ++---------------------+ -```sql -select STR_TO_DATE('200442 Monday', '%X%V %W'),STR_TO_DATE('2023','%Y'); -``` -```text -+-----------------------------------------+---------------------------+ -| str_to_date('200442 Monday', '%X%V %W') | str_to_date('2023', '%Y') | -+-----------------------------------------+---------------------------+ -| 2004-10-18 | 2023-01-01 | -+-----------------------------------------+---------------------------+ +-- 使用代用格式解析 +SELECT STR_TO_DATE('2025-01-23 12:34:56', 'yyyy-MM-dd HH:mm:ss') AS result; ++---------------------+ +| result | ++---------------------+ +| 2025-01-23 12:34:56 | ++---------------------+ + +-- 仅日期字符串（时间默认 00:00:00） +SELECT STR_TO_DATE('20230713', 'yyyyMMdd') AS result; ++---------------------+ +| result | ++---------------------+ +| 2023-07-13 00:00:00 | ++---------------------+ + +-- 仅时间字符串（日期无效，返回空字符串） +SELECT STR_TO_DATE('15:30:45', '%H:%i:%s') AS result; Review Comment: 我们现在是这个行为吗？这个应该有bug的 ########## i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/str-to-date.md: ########## @@ -31,31 +33,110 @@ STR_TO_DATE(<datetime_str>, <format>) |`yyyy-MM-dd HH:mm:ss`|`%Y-%m-%d %H:%i:%s`| ## 返回值 -- 返回一个 DATETIME 类型值，表示转换后的日期时间。 -- 如果输入的 `<datetime_str>` 或 `<format>` 无效，函数返回 NULL。 +返回一个 DATETIME 类型值，表示转换后的日期时间。 + +日期时间匹配方式，用两根指针指向两字符串起始位置 +1. 当遇格式字符串到 % 符号时，会根据 %下一个字母匹配时间字符对应的时间部分，若不匹配(如 %Y 匹配日期时间部分却为 10:10:10 或者 % 不支持解析的字符如 %*)，则返回 NULL，匹配成功则移动到下一个字符解析。 +2. 任意时刻两串中的任一个遇到空格字符，直接跳过解析下一个字符串 +3. 当遇到普通字母的匹配，则查看两字符串现在指针所指向的字符是否相等，不相等则返回 NULL，相等则解析下一个字符 +4. 当任日期指针指向字符串末尾时，若日期时间只包含日期部分，则格式字符串会检查是否包含匹配时间部分的字符(如 %H),若包含，则会设置时间部分为 00:00:00。 +5. 当格式字符串指向末尾时，匹配结束。 +6. 最后检查匹配时间部分是否合法(如月份必须在 [1,12] 区间内)，如果不合法，则返回 NULL，合法则返回解析出的日期时间 Review Comment: ditto -- 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]
