zclllyybb commented on code in PR #2804:
URL: https://github.com/apache/doris-website/pull/2804#discussion_r2346891975
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofweek.md:
##########
@@ -7,50 +7,63 @@
## 描述
-返回日期的工作日索引值，即星期日为 1，星期一为 2，星期六为 7。
+DAYOFWEEK 函数用于返回日期或时间表达式对应的星期索引值，遵循星期日为 1，星期一为 2，……，星期六为 7 的规则。
-## 别名
-
-- DOW
Review Comment:
别名呢？
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md:
##########
@@ -7,39 +7,124 @@
## 描述
-将日期转化为指定的时间间隔周期的最近向上取整时刻。
+DAY_CEIL 函数用于将指定的日期或时间值向上取整（ceil）到最近的指定天数周期的起点。即返回不小于输入日期时间的最小周期时刻，周期规则由
period（周期天数）和 origin（起始基准时间）共同定义。若未指定起始基准时间，默认以 0001-01-01 00:00:00 为基准计算。
+
+日期计算公式
+DAY_CEIL(`<date_or_time_expr>`, `<period>`, `<origin>`) = min{`<origin>` + k
× `<period>` × day | k ∈ ℤ ∧ `<origin>` + k × `<period>` × day ≥
`<date_or_time_expr>`}
+K 代表基准时间到达目标时间所需的周期数
## 语法
```sql
-DAY_CEIL(<datetime>)
-DAY_CEIL(<datetime>, <origin>)
-DAY_CEIL(<datetime>, <period>)
-DAY_CEIL(<datetime>, <period>, <origin>)
+DAY_CEIL(<date_or_time_expr>)
+DAY_CEIL(<date_or_time_expr>, <origin>)
+DAY_CEIL(<date_or_time_expr>, <period>)
+DAY_CEIL(<date_or_time_expr>, <period>, <origin>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<datetime>` | 合法的日期表达式 |
-| `<period>` | 参数是指定每个周期有多少天组成 |
-| `<origin>` | 开始的时间起点，如果不填，默认是 0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 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)
|
+| `<period>` | 参数是指定每个周期包含的天数，类型为 INT。若未指定，默认周期为 1 天。 |
+| `<origin>` | 参数是周期计算的起始基准时间，支持 date/datetime 类型|
## 返回值
-返回最近向上取整时刻的日期。
+返回的是一个日期或时间值，表示将输入值向上舍入到指定天数周期的结果。
+
+若输入有效，返回与 datetime 类型一致的取整结果：
+
+输入 DATE 时，返回 DATE；
+输入 DATETIME，返回 DATETIME（包含日期和时间，时间部分为 00:00:00，因周期基于天数）。
Review Comment:
不用在这里描述具体的值的情况
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md:
##########
@@ -7,39 +7,124 @@
## 描述
-将日期转化为指定的时间间隔周期的最近向上取整时刻。
+DAY_CEIL 函数用于将指定的日期或时间值向上取整（ceil）到最近的指定天数周期的起点。即返回不小于输入日期时间的最小周期时刻，周期规则由
period（周期天数）和 origin（起始基准时间）共同定义。若未指定起始基准时间，默认以 0001-01-01 00:00:00 为基准计算。
+
+日期计算公式
+DAY_CEIL(`<date_or_time_expr>`, `<period>`, `<origin>`) = min{`<origin>` + k
× `<period>` × day | k ∈ ℤ ∧ `<origin>` + k × `<period>` × day ≥
`<date_or_time_expr>`}
+K 代表基准时间到达目标时间所需的周期数
## 语法
```sql
-DAY_CEIL(<datetime>)
-DAY_CEIL(<datetime>, <origin>)
-DAY_CEIL(<datetime>, <period>)
-DAY_CEIL(<datetime>, <period>, <origin>)
+DAY_CEIL(<date_or_time_expr>)
+DAY_CEIL(<date_or_time_expr>, <origin>)
+DAY_CEIL(<date_or_time_expr>, <period>)
+DAY_CEIL(<date_or_time_expr>, <period>, <origin>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<datetime>` | 合法的日期表达式 |
-| `<period>` | 参数是指定每个周期有多少天组成 |
-| `<origin>` | 开始的时间起点，如果不填，默认是 0001-01-01T00:00:00 |
+| `<date_or_time_expr>` | 参数是合法的日期表达式，支持输入 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)
|
+| `<period>` | 参数是指定每个周期包含的天数，类型为 INT。若未指定，默认周期为 1 天。 |
+| `<origin>` | 参数是周期计算的起始基准时间，支持 date/datetime 类型|
## 返回值
-返回最近向上取整时刻的日期。
+返回的是一个日期或时间值，表示将输入值向上舍入到指定天数周期的结果。
+
+若输入有效，返回与 datetime 类型一致的取整结果：
+
+输入 DATE 时，返回 DATE；
Review Comment:
这有两个datelike输入，所以应该是任一输入为datetime时，返回datetime，否则返回date
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/day-ceil.md:
##########
@@ -7,39 +7,124 @@
## 描述
-将日期转化为指定的时间间隔周期的最近向上取整时刻。
+DAY_CEIL 函数用于将指定的日期或时间值向上取整（ceil）到最近的指定天数周期的起点。即返回不小于输入日期时间的最小周期时刻，周期规则由
period（周期天数）和 origin（起始基准时间）共同定义。若未指定起始基准时间，默认以 0001-01-01 00:00:00 为基准计算。
+
+日期计算公式
+DAY_CEIL(`<date_or_time_expr>`, `<period>`, `<origin>`) = min{`<origin>` + k
× `<period>` × day | k ∈ ℤ ∧ `<origin>` + k × `<period>` × day ≥
`<date_or_time_expr>`}
Review Comment:
这种都使用markdown的独立公式格式
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/dayofyear.md:
##########
@@ -7,38 +7,66 @@
## 描述
-获得日期中对应当年中的哪一天。
+DAYOFYEAR 函数用于计算日期或时间表达式对应的当年中天数，即该日期是当年的第几天。返回值为整数，范围从 1（1 月 1 日）到 366（闰年 12
月 31 日）。
-## 别名
-
-- DOY
Review Comment:
别名呢？
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md:
##########
@@ -7,36 +7,59 @@
## 描述
-给定一个天数，返回一个 DATE。
+FROM_DAYS 函数用于将一个整数天数转换为对应的日期（DATE 类型）。该函数以 “公元 0 年 1 月 1 日” 为基准（即天数 0 对应
0000-01-01），计算从基准日期开始经过指定天数后的日期。
-- 注意，为了和 mysql 保持一致的行为，不存在 0000-02-29 这个日期。
+注意：为与 MySQL 保持行为一致，FROM_DAYS 函数不支持 “公元 0 年 2 月 29
日”（0000-02-29），即使理论上该年份符合闰年规则，也会自动跳过该日期。
+历史日期限制：该函数基于公历（格里高利历）扩展历法计算，不适用于 1582 年公历推行之前的日期（此时实际使用的是儒略历），可能导致结果与历史真实日期偏差。
+
+该函数与 mysql 中的 [from_days
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_from-days)
行为一致
## 语法
```sql
-FROM_DAYS(<dt>)
+FROM_DAYS(<days>)
```
## 参数
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | 天数 |
+| `<days>` | 输入的天数，为 `INT` 类型 |
## 返回值
-返回对应天数的日期。
+返回值为 DATE 类型，格式为 YYYY-MM-DD，表示从基准日期（0000-01-01）开始经过 days 天后的日期。
+若 days 为负数，返回 NULL。
+若 days 超出有效日期范围（通常为 1 到 3652424，对应约公元 10000 年），返回错误
## 举例
```sql
+
+---从基准日期开始计算天数
select from_days(730669),from_days(5),from_days(59), from_days(60);
-```
-```text
+-------------------+--------------+---------------+---------------+
| from_days(730669) | from_days(5) | from_days(59) | from_days(60) |
+-------------------+--------------+---------------+---------------+
| 2000-07-03 | 0000-01-05 | 0000-02-28 | 0000-03-01 |
+-------------------+--------------+---------------+---------------+
+
+---输入参数为负数，返回 NULL
Review Comment:
等待行为变化
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/extract.md:
##########
@@ -7,43 +7,100 @@
## 描述
-`extract`
函数用于从日期或时间值中提取指定的部分，如年份、月份、日、小时、分钟、秒等。该函数常用于从日期时间字段中提取具体的时间组件进行计算、比较或展示。
+`EXTRACT` 函数用于从日期或时间值中提取指定的时间组件，如年份、月份,周、日、小时、分钟、秒等。该函数可精确获取日期时间中的特定部分.
+
+该函数与 mysql 中的 [extract
函数](https://dev.mysql.com/doc/refman/8.4/en/date-and-time-functions.html#function_extract)
行为基本一致，不同的是，doris 目前暂不支持联合单位输入，如:
+
+```sql
+mysql> SELECT EXTRACT(YEAR_MONTH FROM '2019-07-02 01:02:03');
+ -> 201907
+```
+
## 语法
-`EXTRACT(<unit> FROM <datetime>)`
+`EXTRACT(<unit> FROM <date_or_time_expr>)`
## 参数
| 参数 | 说明 |
| -- | -- |
-| `unit` | 提取 DATETIME 某个指定单位的值。单位可以为 year, month, day, hour, minute, second,
microsecond, dayofyear(doy), dayofweek(dow) |
-| `datetime` | 参数是合法的日期表达式 |
+| `unit` | 提取 DATETIME 某个指定单位的值。单位可以为 year, month,week, day, hour, minute,
second 或者 microsecond |
+| `datetime_or_time_expr` | 参数是合法的日期表达式，支持输入 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)
|
## 返回值
-返回的是提取出的日期或时间的某个部分（如整数），具体的部分取决于提取的单位。
+返回的是提取出的日期或时间的某个部分,类型为 INT，具体的部分取决于提取的单位。
+
+week 单位的取值范围为 0-53，计算规则如下：
+
+- 以 星期日为一周的第一天。
+- 当年的第一个星期日所在的周为第 1 周。
+- 在第一个星期日之前的日期属于第 0 周。
+单位为 year, month, day, hour, minute, second,microsecond 时，返回日期时间中对应的单位数值.
Review Comment:
这些空格注意一下
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-iso8601-date.md:
##########
@@ -18,22 +25,97 @@ from_iso8601_date(<dt>)
| 参数 | 说明 |
| -- | -- |
-| `<dt>` | ISO8601 格式的日期 |
+| `<date>` | ISO8601 格式的日期,为字符串类型 |
## 返回值
- date 类型的日期表达式。
+返回 DATE 类型，格式为 YYYY-MM-DD，表示解析后的具体日期。
+- 若输入格式无效（如周数超出 53），返回 NULL。
Review Comment:
等待行为变更
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-unixtime.md:
##########
@@ -22,49 +23,78 @@ FROM_UNIXTIME(<unix_timestamp> [, <string_format>])
| 参数 | 说明 |
| -- | -- |
-| `<unix_timestamp>` | unix 时间戳 |
-| `<string_format>` | format 格式，默认为 %Y-%m-%d %H:%i:%s|
+| `<unix_timestamp>` | 输入的 Unix 时间戳，类型为整数 BIGINT，表示从 1970-01-01 00:00:00 UTC
开始的秒数 |
+| `<string_format>` | format 格式,支持类型 varchar 和string，默认为 %Y-%m-%d %H:%i:%s,
具体格式请查看 [date-format](./date-format)|
## 返回值
-返回指定格式的日期。
+返回指定格式的日期,类型为 VARCHAR，返回的是UTC时区下当前时间的时间戳转换为当前时区的时间。
Review Comment:
UTC时区下当前时间的时间戳——这里并非当前时间，我记得上次已经评论过了。
应当是，将 UTC 时区下的时间戳转换为当前时区时间得到的结果。
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-days.md:
##########
@@ -7,36 +7,59 @@
## 描述
-给定一个天数，返回一个 DATE。
+FROM_DAYS 函数用于将一个整数天数转换为对应的日期（DATE 类型）。该函数以 “公元 0 年 1 月 1 日” 为基准（即天数 0 对应
0000-01-01），计算从基准日期开始经过指定天数后的日期。
Review Comment:
不存在公元0年这个说法，0000年是公元前1年
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/from-microsecond.md:
##########
@@ -17,23 +18,59 @@ FROM_MICROSECOND(<unix_timestamp>)
| 参数 | 说明 |
|--------------------|-----------------------------------------------------|
-| `<unix_timestamp>` | 必填，输入的 Unix 时间戳，表示从 1970-01-01 00:00:00 UTC 开始的微秒数。 |
+| `<unix_timestamp>` | 输入的 Unix 时间戳，类型为整数（BIGINT），表示从 1970-01-01
00:00:00 UTC 开始计算的微秒数 |
## 返回值
-- 返回一个 DATETIME 类型的值，表示输入的 Unix 时间戳对应的日期时间。
-- 如果 `<unix_timestamp>` 为 NULL，函数返回 NULL。
-- 如果 `<unix_timestamp>` 超出有效范围，函数返回错误。
+
+返回一个 DATETIME 类型的值，表示UTC时区下的unix时间戳，转换为当前时区的时间的结果
+- 如果 <unix_timestamp> 为 NULL，函数返回 NULL。
+- 若输入 <unix_timestamp> 能转换为整数秒，那么结果返回日期时间不带有 scale，如果不能，则结果返回带有 scale
+- 如果 <unix_timestamp> 小于 0 ，返回错误
+- 若 返回日期时间超过最大时间 9999-12-31 23:59:59 ，则返回错误
## 举例
```sql
+
+---当前机器所在时区是东八区，所以返回的时间相较于 UTC 加八个小时
+SELECT FROM_MICROSECOND(0);
++----------------------------+
+| FROM_MICROSECOND(0) |
++----------------------------+
+| 1970-01-01 08:00:00.000000 |
++----------------------------+
+
+---将 1700000000000000 微妙加在基准时间后转换为的日期时间
Review Comment:
typo，微秒
--
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]
