diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index b459a44bea6fc..6b8353ac77e80 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -24,18 +24,28 @@ specific language governing permissions and limitations under the License. --> -## to_date -### description -#### Syntax -`DATE TO_DATE(DATETIME)` +## Description +Date conversion function, used to convert date time (DATETIME) to date type (DATE), that is, remove the time part and keep only the date (YYYY-MM-DD) -Return the DATE part of DATETIME value. +## Syntax +```sql +TO_DATE() +``` + +## Required parameter +| Parameter | Description | +|-----------------|--------------------------| +| `datetime_value` | DATETIME type date-time | -### example +## Example + +Convert `2020-02-02 00:00:00` to `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ @@ -43,6 +53,3 @@ mysql> select to_date("2020-02-02 00:00:00"); +--------------------------------+ ``` -### keywords - - TO_DATE diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index db0bd9c9179d1..d1668da81e81e 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -24,27 +24,42 @@ specific language governing permissions and limitations under the License. --> -## to_days -### Description -#### Syntax -`INT TO DAYS` +## Description +Date calculation function, which is used to convert a date into a day value, that is, to calculate the total number of days from December 31, 0 AD (the base date) to the specified date. +## Syntax -Days of returning date distance 0000-01-01 +```sql +TO_DAYS() +``` -The parameter is Date or Datetime type +## Required parameters +| Parameter | Description | +|----------------------------|-----------------------------------| +| `` | `datetime` or `date` type date-time | -### example +## Example +Query how many days are there since October 7, 2007 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index bee4e5fcc080e..86daeeecb7046 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -24,27 +24,59 @@ specific language governing permissions and limitations under the License. --> -## weeks_add -### description -#### Syntax +## Description +This function is used to add (or subtract) a certain number of weeks from a specified date or time value. -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## Syntax -ADD a specified number of weeks from a datetime or date +```sql +WEEKS_ADD(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `DATETIME` or `DATE` type date input value | +| `` | Integer, indicating the number of weeks to increase or decrease (positive number indicates increase, negative number indicates decrease) | + -### example +## example -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` -### keywords +1. Add one week to the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. Subtract one week from the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. Add one week to the date `2020-02-02` + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` + - WEEKS_ADD diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index e3579a9195453..a7f949cc2dbfe 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff -### description -#### Syntax +## Description +Calculates the number of complete weeks (in 7-day units) between two date or time values. -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +## Syntax -The difference between the start time and the end time is weeks +```sql +WEEKS_DIFF(, ) +``` -### example +## Required parameters +| Parameter Name | Data Type | Description | +|---------------|----------------------|-----------------------------| +| `end_date` | `DATE`, `DATETIME` | Later date or date-time | +| `start_date` | `DATE`, `DATETIME` | Earlier date or date-time | -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` -### keywords +## Example + +1. How many weeks are there between `2020-12-25` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` + +2. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25 12:10:02` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 3cb574fd0c556..f8ed6b096db21 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -24,27 +24,44 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub -### description -#### Syntax -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +## Description +Subtracts a specified number of weeks from a specified date or time value (i.e., subtracts weeks * 7 days). -Subtracts a specified number of weeks from a datetime or date +## Syntax +```sql +WEEKS_SUB(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|-----------------|-----------------------------------------------------------------------------------------------------| +| `date_value` | `DATE` or `DATETIME` type input value. | +| `week_period` | Integer, representing the number of weeks to subtract (positive to decrease, negative to increase). | -### example -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` +## Example -### keywords +1. Subtract one week from the datetime `2020-02-02 02:02:02` + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. Subtract one week from the date `2020-02-02` + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` \ No newline at end of file diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index b0477d29da018..41a14ed24a9ee 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,90 @@ specific language governing permissions and limitations under the License. --> -## year_floor -### description -#### Syntax -```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) -``` +## Description +It is used to round the given date down to the specified year interval starting point. It supports multiple variants, which can specify the starting time (origin) and period (period) in different ways to round. -Convert the date to the nearest rounding down time of the specified time interval period. +## Syntax -- datetime: a valid date expression. -- period: specifies how many years each cycle consists of. -- origin: starting from 0001-01-01T00:00:00. +```sql +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) +``` -### example +## Parameters +| **Parameter** | **Type** | **Description** | +|--------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value to be rounded. | +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value used as the reference point. If not provided, the default is `0001-01-01T00:00:00`. | +| `` | `INT` | The rounding interval, a positive integer indicating the number of years per cycle. | -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` -### keywords +## Example +1. Rounding to the whole year + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` - YEAR_FLOOR, YEAR, FLOOR +2. Round based on origin + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` -### Best Practice +3. Rounding with period as unit + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` -See also [date_floor](./date-floor) +4. Round origin and period + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index ab8bbfd323c9b..b307968150b04 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -24,25 +24,30 @@ specific language governing permissions and limitations under the License. --> -## to_date -## 描述 +## 描述 +日期转换函数，用于将日期时间（DATETIME）转换为日期类型（DATE），即去掉时间部分，仅保留日期（YYYY-MM-DD） + ## 语法 +```sql +TO_DATE() +``` -`DATE TO_DATE(DATETIME)` +## 必选参数 +| 参数 | 描述 | +|------------------|--------------------| +| `datetime_value` | DATETIME 类型日期时间 | -返回 DATETIME 类型中的日期部分。 ## 举例 +将 `2020-02-02 00:00:00` 转换为 `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ | 2020-02-02 | +--------------------------------+ -``` - -### keywords - - TO_DATE +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index 628ceda8b1138..22471d01de5a0 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -24,28 +24,43 @@ specific language governing permissions and limitations under the License. --> -## to_days + ## 描述 -## 语法 +日期计算函数，它用于将日期转换为天数数值，即计算从公元 0 年 12 月 31 日（基准日期）到指定日期的总天数。 -`INT TO_DAYS(DATETIME date)` +## 语法 +```sql +TO_DAYS() +``` -返回 date 距离 0000-01-01 的天数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-----------------------------| +| `` | `datetime` 或者 `date` 类型日期时间 | -参数为 Date 或者 Datetime 类型 ## 举例 +查询2007年10月7日距今有多少天 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index be4819050b2e0..941f2df64e0d8 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -24,27 +24,57 @@ specific language governing permissions and limitations under the License. --> -## weeks_add -## 描述 -## 语法 +## 描述 +函数用于在指定的日期或时间值上增加（或减少）一定数量的周 -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## 语法 +```sql +WEEKS_ADD(, ) +``` -从日期加上指定星期数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-------------------------------| +| `` | `DATETIME` 或者 `DATE` 类型的输入值 | +| `` | 整数，表示要增加或减少的周数（正数表示增加，负数表示减少） | -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 ## 举例 -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` +1. 在 `2020-02-02 02:02:02` 时间上增加一周 + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. 在 `2020-02-02 02:02:02` 时间上减少一周 + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. 给 `2020-02-02` 日期增加一周 + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` -### keywords - WEEKS_ADD diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index d036f74a43c0d..5c422870408f2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_DIFF", - "language": "zh-CN" + "title": "WEEKS_DIFF", + "language": "zh-CN" } --- @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff ## 描述 +用于计算两个日期或时间值之间相差的完整周数（以 7 天为单位）。 + ## 语法 -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +```sql +WEEKS_DIFF(, ) +``` + +## 必选参数 +| 参数名称 | 数据类型 | 描述 | +|--------------|--------------------|-------------| +| `end_date` | `DATE`, `DATETIME` | 较晚的日期或者日期时间 | +| `start_date` | `DATE`, `DATETIME` | 较早的日期或者日期时间 | -开始时间到结束时间相差几星期 ## 举例 -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` +1. `2020-12-25` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` -### keywords +2. `2020-12-25 10:10:02` 与 `2020-10-25 12:10:02` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. `2020-12-25 10:10:02` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 948cf2ed58297..99f2f9e43130d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -24,27 +24,43 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub ## 描述 -## 语法 - -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +用于在指定的日期或时间值上减少一定数量的周（即减去 weeks * 7 天）。 -从日期时间或日期减去指定星期数 +## 语法 +```sql +WEEKS_SUB(, ) +``` -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 +## 必选参数 +| 参数名称 | 描述 | +|---------------|-------------------------------------------------------------------| +| `date_value` | `DATE` 或 `DATETIME` 类型的输入值。 | +| `week_period` | 整数，表示要减少的周数（正数表示减少，负数表示增加）。 | + ## 举例 -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` - -### keywords +1. 在 `2020-02-02 02:02:02` 日期时间上减去一周 + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. 在 `2020-02-02` 日期上减去一周 + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index 24219c0fead82..cad0ad102e571 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,91 @@ specific language governing permissions and limitations under the License. --> -## year_floor ## 描述 -## 语法 +用于将给定的日期向下取整到指定的年份间隔起点。它支持多个变体，可按不同方式 指定起始时间 (origin) 和周期 (period) 进行取整。 +## 语法 ```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) ``` -将日期转化为指定的时间间隔周期的最近下取整时刻。 +## 参数 +| **参数** | **类型** | **说明** | +|----------------------|--------------------|--------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | 需要取整的 `DATE` 或 `DATETIME` 输入值。 | +| `` | `DATE`, `DATETIME` | 用作基准的 `DATE` 或 `DATETIME` 输入值，如果不填，默认值为 `0001-01-01T00:00:00`。 | +| `` | `INT` | 取整的时间间隔，正整数，表示以多少年为周期进行取整。 | -- datetime：参数是合法的日期表达式。 -- period：参数是指定每个周期有多少天组成。 -- origin：开始的时间起点，如果不填，默认是 0001-01-01T00:00:00。 ## 举例 +1. 按整年取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` + +2. 以 origin 为基准取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` + +3. 以 period 为单位取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` + +4. 以 origin 和 period 取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ``` -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` - -### keywords - - YEAR_FLOOR, YEAR, FLOOR -### Best Practice -还可参阅 [date_floor](./date-floor) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index ab8bbfd323c9b..d6ecdf2ef6290 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DATE", - "language": "zh-CN" + "title": "TO_DATE", + "language": "zh-CN" } --- @@ -24,25 +24,30 @@ specific language governing permissions and limitations under the License. --> -## to_date ## 描述 +日期转换函数，用于将日期时间（DATETIME）转换为日期类型（DATE），即去掉时间部分，仅保留日期（YYYY-MM-DD） + ## 语法 +```sql +TO_DATE() +``` -`DATE TO_DATE(DATETIME)` +## 必选参数 +| 参数 | 描述 | +|------------------|--------------------| +| `datetime_value` | DATETIME 类型日期时间 | -返回 DATETIME 类型中的日期部分。 ## 举例 +将 `2020-02-02 00:00:00` 转换为 `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ | 2020-02-02 | +--------------------------------+ -``` - -### keywords - - TO_DATE +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index 628ceda8b1138..bd5217e9a3f3c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DAYS", - "language": "zh-CN" + "title": "TO_DAYS", + "language": "zh-CN" } --- @@ -24,28 +24,43 @@ specific language governing permissions and limitations under the License. --> -## to_days + ## 描述 -## 语法 +日期计算函数，它用于将日期转换为天数数值，即计算从公元 0 年 12 月 31 日（基准日期）到指定日期的总天数。 -`INT TO_DAYS(DATETIME date)` +## 语法 +```sql +TO_DAYS() +``` -返回 date 距离 0000-01-01 的天数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-----------------------------| +| `` | `datetime` 或者 `date` 类型日期时间 | -参数为 Date 或者 Datetime 类型 ## 举例 +查询2007年10月7日距今有多少天 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index be4819050b2e0..4ec4b7d382a7e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_ADD", - "language": "zh-CN" + "title": "WEEKS_ADD", + "language": "zh-CN" } --- @@ -24,27 +24,57 @@ specific language governing permissions and limitations under the License. --> -## weeks_add ## 描述 -## 语法 +函数用于在指定的日期或时间值上增加（或减少）一定数量的周 -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## 语法 +```sql +WEEKS_ADD(, ) +``` -从日期加上指定星期数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-------------------------------| +| `` | `DATETIME` 或者 `DATE` 类型的输入值 | +| `` | 整数，表示要增加或减少的周数（正数表示增加，负数表示减少） | -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 ## 举例 -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` +1. 在 `2020-02-02 02:02:02` 时间上增加一周 + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. 在 `2020-02-02 02:02:02` 时间上减少一周 + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. 给 `2020-02-02` 日期增加一周 + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` -### keywords - WEEKS_ADD diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index d036f74a43c0d..5c422870408f2 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_DIFF", - "language": "zh-CN" + "title": "WEEKS_DIFF", + "language": "zh-CN" } --- @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff ## 描述 +用于计算两个日期或时间值之间相差的完整周数（以 7 天为单位）。 + ## 语法 -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +```sql +WEEKS_DIFF(, ) +``` + +## 必选参数 +| 参数名称 | 数据类型 | 描述 | +|--------------|--------------------|-------------| +| `end_date` | `DATE`, `DATETIME` | 较晚的日期或者日期时间 | +| `start_date` | `DATE`, `DATETIME` | 较早的日期或者日期时间 | -开始时间到结束时间相差几星期 ## 举例 -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` +1. `2020-12-25` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` -### keywords +2. `2020-12-25 10:10:02` 与 `2020-10-25 12:10:02` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. `2020-12-25 10:10:02` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 948cf2ed58297..a04993cdcf2bf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_SUB", - "language": "zh-CN" + "title": "WEEKS_SUB", + "language": "zh-CN" } --- @@ -24,27 +24,43 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub ## 描述 -## 语法 +用于在指定的日期或时间值上减少一定数量的周（即减去 weeks * 7 天）。 -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +## 语法 +```sql +WEEKS_SUB(, ) +``` -从日期时间或日期减去指定星期数 +## 必选参数 +| 参数名称 | 描述 | +|---------------|-------------------------------------------------------------------| +| `date_value` | `DATE` 或 `DATETIME` 类型的输入值。 | +| `week_period` | 整数，表示要减少的周数（正数表示减少，负数表示增加）。 | -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 ## 举例 -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` - -### keywords +1. 在 `2020-02-02 02:02:02` 日期时间上减去一周 + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. 在 `2020-02-02` 日期上减去一周 + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index 24219c0fead82..e3ff0df111cea 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,91 @@ specific language governing permissions and limitations under the License. --> -## year_floor ## 描述 -## 语法 +用于将给定的日期向下取整到指定的年份间隔起点。它支持多个变体，可按不同方式 指定起始时间 (origin) 和周期 (period) 进行取整。 +## 语法 ```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) ``` -将日期转化为指定的时间间隔周期的最近下取整时刻。 +## 参数 +| **参数** | **类型** | **说明** | +|----------------------|--------------------|--------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | 需要取整的 `DATE` 或 `DATETIME` 输入值。 | +| `` | `DATE`, `DATETIME` | 用作基准的 `DATE` 或 `DATETIME` 输入值，如果不填，默认值为 `0001-01-01T00:00:00`。 | +| `` | `INT` | 取整的时间间隔，正整数，表示以多少年为周期进行取整。 | -- datetime：参数是合法的日期表达式。 -- period：参数是指定每个周期有多少天组成。 -- origin：开始的时间起点，如果不填，默认是 0001-01-01T00:00:00。 ## 举例 +1. 按整年取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` +2. 以 origin 为基准取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` + +3. 以 period 为单位取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` -### keywords +4. 以 origin 和 period 取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ``` - YEAR_FLOOR, YEAR, FLOOR -### Best Practice -还可参阅 [date_floor](./date-floor) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index ab8bbfd323c9b..d6ecdf2ef6290 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DATE", - "language": "zh-CN" + "title": "TO_DATE", + "language": "zh-CN" } --- @@ -24,25 +24,30 @@ specific language governing permissions and limitations under the License. --> -## to_date ## 描述 +日期转换函数，用于将日期时间（DATETIME）转换为日期类型（DATE），即去掉时间部分，仅保留日期（YYYY-MM-DD） + ## 语法 +```sql +TO_DATE() +``` -`DATE TO_DATE(DATETIME)` +## 必选参数 +| 参数 | 描述 | +|------------------|--------------------| +| `datetime_value` | DATETIME 类型日期时间 | -返回 DATETIME 类型中的日期部分。 ## 举例 +将 `2020-02-02 00:00:00` 转换为 `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ | 2020-02-02 | +--------------------------------+ -``` - -### keywords - - TO_DATE +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index 628ceda8b1138..bd5217e9a3f3c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DAYS", - "language": "zh-CN" + "title": "TO_DAYS", + "language": "zh-CN" } --- @@ -24,28 +24,43 @@ specific language governing permissions and limitations under the License. --> -## to_days + ## 描述 -## 语法 +日期计算函数，它用于将日期转换为天数数值，即计算从公元 0 年 12 月 31 日（基准日期）到指定日期的总天数。 -`INT TO_DAYS(DATETIME date)` +## 语法 +```sql +TO_DAYS() +``` -返回 date 距离 0000-01-01 的天数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-----------------------------| +| `` | `datetime` 或者 `date` 类型日期时间 | -参数为 Date 或者 Datetime 类型 ## 举例 +查询2007年10月7日距今有多少天 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index be4819050b2e0..4ec4b7d382a7e 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_ADD", - "language": "zh-CN" + "title": "WEEKS_ADD", + "language": "zh-CN" } --- @@ -24,27 +24,57 @@ specific language governing permissions and limitations under the License. --> -## weeks_add ## 描述 -## 语法 +函数用于在指定的日期或时间值上增加（或减少）一定数量的周 -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## 语法 +```sql +WEEKS_ADD(, ) +``` -从日期加上指定星期数 +## 必选参数 +| 参数 | 描述 | +|----------------------------|-------------------------------| +| `` | `DATETIME` 或者 `DATE` 类型的输入值 | +| `` | 整数，表示要增加或减少的周数（正数表示增加，负数表示减少） | -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 ## 举例 -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` +1. 在 `2020-02-02 02:02:02` 时间上增加一周 + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. 在 `2020-02-02 02:02:02` 时间上减少一周 + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. 给 `2020-02-02` 日期增加一周 + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` -### keywords - WEEKS_ADD diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index d036f74a43c0d..3e05224b0a254 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_DIFF", - "language": "zh-CN" + "title": "WEEKS_DIFF", + "language": "zh-CN" } --- @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff ## 描述 +用于计算两个日期或时间值之间相差的完整周数（以 7 天为单位）。 + ## 语法 -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +```sql +WEEKS_DIFF(, ) +``` + +## 必选参数 +| 参数名称 | 数据类型 | 描述 | +|--------------|--------------------|-------------| +| `end_date` | `DATE`, `DATETIME` | 较晚的日期或者日期时间 | +| `start_date` | `DATE`, `DATETIME` | 较早的日期或者日期时间 | -开始时间到结束时间相差几星期 ## 举例 -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` +1. `2020-12-25` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` -### keywords +2. `2020-12-25 10:10:02` 与 `2020-10-25 12:10:02` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. `2020-12-25 10:10:02` 与 `2020-10-25` 相差多少周 + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 948cf2ed58297..a04993cdcf2bf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_SUB", - "language": "zh-CN" + "title": "WEEKS_SUB", + "language": "zh-CN" } --- @@ -24,27 +24,43 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub ## 描述 -## 语法 +用于在指定的日期或时间值上减少一定数量的周（即减去 weeks * 7 天）。 -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +## 语法 +```sql +WEEKS_SUB(, ) +``` -从日期时间或日期减去指定星期数 +## 必选参数 +| 参数名称 | 描述 | +|---------------|-------------------------------------------------------------------| +| `date_value` | `DATE` 或 `DATETIME` 类型的输入值。 | +| `week_period` | 整数，表示要减少的周数（正数表示减少，负数表示增加）。 | -参数 date 可以是 DATETIME 或者 DATE 类型，返回类型与参数 date 的类型一致。 ## 举例 -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` - -### keywords +1. 在 `2020-02-02 02:02:02` 日期时间上减去一周 + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. 在 `2020-02-02` 日期上减去一周 + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index 24219c0fead82..e3ff0df111cea 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,91 @@ specific language governing permissions and limitations under the License. --> -## year_floor ## 描述 -## 语法 +用于将给定的日期向下取整到指定的年份间隔起点。它支持多个变体，可按不同方式 指定起始时间 (origin) 和周期 (period) 进行取整。 +## 语法 ```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) ``` -将日期转化为指定的时间间隔周期的最近下取整时刻。 +## 参数 +| **参数** | **类型** | **说明** | +|----------------------|--------------------|--------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | 需要取整的 `DATE` 或 `DATETIME` 输入值。 | +| `` | `DATE`, `DATETIME` | 用作基准的 `DATE` 或 `DATETIME` 输入值，如果不填，默认值为 `0001-01-01T00:00:00`。 | +| `` | `INT` | 取整的时间间隔，正整数，表示以多少年为周期进行取整。 | -- datetime：参数是合法的日期表达式。 -- period：参数是指定每个周期有多少天组成。 -- origin：开始的时间起点，如果不填，默认是 0001-01-01T00:00:00。 ## 举例 +1. 按整年取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` +2. 以 origin 为基准取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` + +3. 以 period 为单位取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` -### keywords +4. 以 origin 和 period 取整 + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ``` - YEAR_FLOOR, YEAR, FLOOR -### Best Practice -还可参阅 [date_floor](./date-floor) diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index b459a44bea6fc..fd646744897e6 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DATE", - "language": "en" + "title": "TO_DATE", + "language": "en" } --- @@ -24,18 +24,28 @@ specific language governing permissions and limitations under the License. --> -## to_date -### description -#### Syntax -`DATE TO_DATE(DATETIME)` +## Description +Date conversion function, used to convert date time (DATETIME) to date type (DATE), that is, remove the time part and keep only the date (YYYY-MM-DD) -Return the DATE part of DATETIME value. +## Syntax +```sql +TO_DATE() +``` + +## Required parameter +| Parameter | Description | +|-----------------|--------------------------| +| `datetime_value` | DATETIME type date-time | -### example +## Example + +Convert `2020-02-02 00:00:00` to `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ @@ -43,6 +53,3 @@ mysql> select to_date("2020-02-02 00:00:00"); +--------------------------------+ ``` -### keywords - - TO_DATE diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index db0bd9c9179d1..79c20570551be 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DAYS", - "language": "en" + "title": "TO_DAYS", + "language": "en" } --- @@ -24,27 +24,43 @@ specific language governing permissions and limitations under the License. --> -## to_days -### Description -#### Syntax -`INT TO DAYS` +## Description +Date calculation function, which is used to convert a date into a day value, that is, to calculate the total number of days from December 31, 0 AD (the base date) to the specified date. +## Syntax -Days of returning date distance 0000-01-01 +```sql +TO_DAYS() +``` + +## Required parameters +| Parameter | Description | +|----------------------------|-----------------------------------| +| `` | `datetime` or `date` type date-time | -The parameter is Date or Datetime type -### example +## Example +Query how many days are there since October 7, 2007 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index bee4e5fcc080e..8f2dea5f110b1 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_ADD", - "language": "en" + "title": "WEEKS_ADD", + "language": "en" } --- @@ -24,27 +24,59 @@ specific language governing permissions and limitations under the License. --> -## weeks_add -### description -#### Syntax +## Description +This function is used to add (or subtract) a certain number of weeks from a specified date or time value. -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## Syntax -ADD a specified number of weeks from a datetime or date +```sql +WEEKS_ADD(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `DATETIME` or `DATE` type date input value | +| `` | Integer, indicating the number of weeks to increase or decrease (positive number indicates increase, negative number indicates decrease) | -### example -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` +## example + + +1. Add one week to the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. Subtract one week from the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. Add one week to the date `2020-02-02` + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` -### keywords - WEEKS_ADD diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index e3579a9195453..a69221380bc71 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_DIFF", - "language": "en" + "title": "WEEKS_DIFF", + "language": "en" } --- @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff -### description -#### Syntax +## Description +Calculates the number of complete weeks (in 7-day units) between two date or time values. -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +## Syntax -The difference between the start time and the end time is weeks +```sql +WEEKS_DIFF(, ) +``` -### example +## Required parameters +| Parameter Name | Data Type | Description | +|---------------|----------------------|-----------------------------| +| `end_date` | `DATE`, `DATETIME` | Later date or date-time | +| `start_date` | `DATE`, `DATETIME` | Earlier date or date-time | -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` -### keywords +## Example + +1. How many weeks are there between `2020-12-25` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` + +2. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25 12:10:02` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 3cb574fd0c556..07c721b1bde63 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_SUB", - "language": "en" + "title": "WEEKS_SUB", + "language": "en" } --- @@ -24,27 +24,44 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub -### description -#### Syntax -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +## Description +Subtracts a specified number of weeks from a specified date or time value (i.e., subtracts weeks * 7 days). -Subtracts a specified number of weeks from a datetime or date +## Syntax +```sql +WEEKS_SUB(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|-----------------|-----------------------------------------------------------------------------------------------------| +| `date_value` | `DATE` or `DATETIME` type input value. | +| `week_period` | Integer, representing the number of weeks to subtract (positive to decrease, negative to increase). | -### example -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` +## Example -### keywords +1. Subtract one week from the datetime `2020-02-02 02:02:02` + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. Subtract one week from the date `2020-02-02` + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` \ No newline at end of file diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index b0477d29da018..41a14ed24a9ee 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,90 @@ specific language governing permissions and limitations under the License. --> -## year_floor -### description -#### Syntax -```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) -``` +## Description +It is used to round the given date down to the specified year interval starting point. It supports multiple variants, which can specify the starting time (origin) and period (period) in different ways to round. -Convert the date to the nearest rounding down time of the specified time interval period. +## Syntax -- datetime: a valid date expression. -- period: specifies how many years each cycle consists of. -- origin: starting from 0001-01-01T00:00:00. +```sql +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) +``` -### example +## Parameters +| **Parameter** | **Type** | **Description** | +|--------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value to be rounded. | +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value used as the reference point. If not provided, the default is `0001-01-01T00:00:00`. | +| `` | `INT` | The rounding interval, a positive integer indicating the number of years per cycle. | -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` -### keywords +## Example +1. Rounding to the whole year + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` - YEAR_FLOOR, YEAR, FLOOR +2. Round based on origin + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` -### Best Practice +3. Rounding with period as unit + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` -See also [date_floor](./date-floor) +4. Round origin and period + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ``` diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md index b459a44bea6fc..9272f5c1db293 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-date.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DATE", - "language": "en" + "title": "TO_DATE", + "language": "en" } --- @@ -24,18 +24,27 @@ specific language governing permissions and limitations under the License. --> -## to_date -### description -#### Syntax -`DATE TO_DATE(DATETIME)` +## Description +Date conversion function, used to convert date time (DATETIME) to date type (DATE), that is, remove the time part and keep only the date (YYYY-MM-DD) -Return the DATE part of DATETIME value. +## Syntax +```sql +TO_DATE() +``` + +## Required parameter +| Parameter | Description | +|-----------------|--------------------------| +| `datetime_value` | DATETIME type date-time | -### example +## Example +Convert `2020-02-02 00:00:00` to `2020-02-02` +```sql +select to_date("2020-02-02 00:00:00"); ``` -mysql> select to_date("2020-02-02 00:00:00"); +```text +--------------------------------+ | to_date('2020-02-02 00:00:00') | +--------------------------------+ @@ -43,6 +52,3 @@ mysql> select to_date("2020-02-02 00:00:00"); +--------------------------------+ ``` -### keywords - - TO_DATE diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md index db0bd9c9179d1..79c20570551be 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/to-days.md @@ -1,7 +1,7 @@ --- { - "title": "TO_DAYS", - "language": "en" + "title": "TO_DAYS", + "language": "en" } --- @@ -24,27 +24,43 @@ specific language governing permissions and limitations under the License. --> -## to_days -### Description -#### Syntax -`INT TO DAYS` +## Description +Date calculation function, which is used to convert a date into a day value, that is, to calculate the total number of days from December 31, 0 AD (the base date) to the specified date. +## Syntax -Days of returning date distance 0000-01-01 +```sql +TO_DAYS() +``` + +## Required parameters +| Parameter | Description | +|----------------------------|-----------------------------------| +| `` | `datetime` or `date` type date-time | -The parameter is Date or Datetime type -### example +## Example +Query how many days are there since October 7, 2007 +```sql +select to_days('2007-10-07'); ``` -mysql> select to_days('2007-10-07'); -+-----------------------+ -| to_days('2007-10-07') | -+-----------------------+ -| 733321 | -+-----------------------+ +```text ++---------------------------------------+ +| to_days(cast('2007-10-07' as DATEV2)) | ++---------------------------------------+ +| 733321 | ++---------------------------------------+ ``` -### keywords - TO_DAYS,TO,DAYS +```sql +select to_days('2007-10-07 10:03:09'); +``` +```text ++------------------------------------------------+ +| to_days(cast('2007-10-07 10:03:09' as DATEV2)) | ++------------------------------------------------+ +| 733321 | ++------------------------------------------------+ +``` diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md index bee4e5fcc080e..8f2dea5f110b1 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-add.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_ADD", - "language": "en" + "title": "WEEKS_ADD", + "language": "en" } --- @@ -24,27 +24,59 @@ specific language governing permissions and limitations under the License. --> -## weeks_add -### description -#### Syntax +## Description +This function is used to add (or subtract) a certain number of weeks from a specified date or time value. -`DATETIME WEEKS_ADD(DATETIME date, INT weeks)` +## Syntax -ADD a specified number of weeks from a datetime or date +```sql +WEEKS_ADD(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| `` | `DATETIME` or `DATE` type date input value | +| `` | Integer, indicating the number of weeks to increase or decrease (positive number indicates increase, negative number indicates decrease) | -### example -``` -mysql> select weeks_add("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_add('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-02-09 02:02:02 | -+-------------------------------------+ -``` +## example + + +1. Add one week to the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_add('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-02-09 02:02:02 | + +-------------------------------------+ + ``` + +2. Subtract one week from the time `2020-02-02 02:02:02` + ```sql + select weeks_add("2020-02-02 02:02:02", -1); + ``` + ```text + +-------------------------------------------------------------+ + | weeks_add(cast('2020-02-02 02:02:02' as DATETIMEV2(0)), -1) | + +-------------------------------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------------------------------+ + ``` + +3. Add one week to the date `2020-02-02` + ```sql + select weeks_add("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_add(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-02-09 | + +--------------------------------------------+ + ``` -### keywords - WEEKS_ADD diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md index e3579a9195453..a69221380bc71 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-diff.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_DIFF", - "language": "en" + "title": "WEEKS_DIFF", + "language": "en" } --- @@ -24,25 +24,56 @@ specific language governing permissions and limitations under the License. --> -## weeks_diff -### description -#### Syntax +## Description +Calculates the number of complete weeks (in 7-day units) between two date or time values. -`INT weeks_diff(DATETIME enddate, DATETIME startdate)` +## Syntax -The difference between the start time and the end time is weeks +```sql +WEEKS_DIFF(, ) +``` -### example +## Required parameters +| Parameter Name | Data Type | Description | +|---------------|----------------------|-----------------------------| +| `end_date` | `DATE`, `DATETIME` | Later date or date-time | +| `start_date` | `DATE`, `DATETIME` | Earlier date or date-time | -``` -mysql> select weeks_diff('2020-12-25','2020-10-25'); -+----------------------------------------------------------+ -| weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | -+----------------------------------------------------------+ -| 8 | -+----------------------------------------------------------+ -``` -### keywords +## Example + +1. How many weeks are there between `2020-12-25` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25','2020-10-25'); + ``` + ```text + +----------------------------------------------------------+ + | weeks_diff('2020-12-25 00:00:00', '2020-10-25 00:00:00') | + +----------------------------------------------------------+ + | 8 | + +----------------------------------------------------------+ + ``` + +2. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25 12:10:02` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25 12:10:02'); + ``` + ```text + +--------------------------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25 12:10:02' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------------+ + | 8 | + +--------------------------------------------------------------------------------------------------------+ + ``` - weeks_diff +3. How many weeks are there between `2020-12-25 10:10:02` and `2020-10-25` + ```sql + select weeks_diff('2020-12-25 10:10:02','2020-10-25'); + ``` + ```text + +----------------------------------------------------------------------------------------+ + | weeks_diff(cast('2020-12-25 10:10:02' as DATETIMEV2(0)), cast('2020-10-25' as DATEV2)) | + +----------------------------------------------------------------------------------------+ + | 8 | + +----------------------------------------------------------------------------------------+ + ``` \ No newline at end of file diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md index 3cb574fd0c556..07c721b1bde63 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/weeks-sub.md @@ -1,7 +1,7 @@ --- { - "title": "WEEKS_SUB", - "language": "en" + "title": "WEEKS_SUB", + "language": "en" } --- @@ -24,27 +24,44 @@ specific language governing permissions and limitations under the License. --> -## weeks_sub -### description -#### Syntax -`DATETIME WEEKS_SUB(DATETIME date, INT weeks)` +## Description +Subtracts a specified number of weeks from a specified date or time value (i.e., subtracts weeks * 7 days). -Subtracts a specified number of weeks from a datetime or date +## Syntax +```sql +WEEKS_SUB(, ) +``` -The parameter date can be DATETIME or DATE, and the return type is consistent with that of the parameter date. +## Required parameters +| Parameter | Description | +|-----------------|-----------------------------------------------------------------------------------------------------| +| `date_value` | `DATE` or `DATETIME` type input value. | +| `week_period` | Integer, representing the number of weeks to subtract (positive to decrease, negative to increase). | -### example -``` -mysql> select weeks_sub("2020-02-02 02:02:02", 1); -+-------------------------------------+ -| weeks_sub('2020-02-02 02:02:02', 1) | -+-------------------------------------+ -| 2020-01-26 02:02:02 | -+-------------------------------------+ -``` +## Example -### keywords +1. Subtract one week from the datetime `2020-02-02 02:02:02` + ```sql + select weeks_sub("2020-02-02 02:02:02", 1); + ``` + ```text + +-------------------------------------+ + | weeks_sub('2020-02-02 02:02:02', 1) | + +-------------------------------------+ + | 2020-01-26 02:02:02 | + +-------------------------------------+ + ``` - WEEKS_SUB +2. Subtract one week from the date `2020-02-02` + ```sql + select weeks_sub("2020-02-02", 1); + ``` + ```text + +--------------------------------------------+ + | weeks_sub(cast('2020-02-02' as DATEV2), 1) | + +--------------------------------------------+ + | 2020-01-26 | + +--------------------------------------------+ + ``` \ No newline at end of file diff --git a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md index b0477d29da018..41a14ed24a9ee 100644 --- a/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md +++ b/versioned_docs/version-3.0/sql-manual/sql-functions/scalar-functions/date-time-functions/year-floor.md @@ -24,39 +24,90 @@ specific language governing permissions and limitations under the License. --> -## year_floor -### description -#### Syntax -```sql -DATETIME YEAR_FLOOR(DATETIME datetime) -DATETIME YEAR_FLOOR(DATETIME datetime, DATETIME origin) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period) -DATETIME YEAR_FLOOR(DATETIME datetime, INT period, DATETIME origin) -``` +## Description +It is used to round the given date down to the specified year interval starting point. It supports multiple variants, which can specify the starting time (origin) and period (period) in different ways to round. -Convert the date to the nearest rounding down time of the specified time interval period. +## Syntax -- datetime: a valid date expression. -- period: specifies how many years each cycle consists of. -- origin: starting from 0001-01-01T00:00:00. +```sql +YEAR_FLOOR(, [ | ]) +YEAR_FLOOR(, , ) +``` -### example +## Parameters +| **Parameter** | **Type** | **Description** | +|--------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------| +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value to be rounded. | +| `` | `DATE`, `DATETIME` | The `DATE` or `DATETIME` input value used as the reference point. If not provided, the default is `0001-01-01T00:00:00`. | +| `` | `INT` | The rounding interval, a positive integer indicating the number of years per cycle. | -``` -mysql> select year_floor("2023-07-13 22:28:18", 5); -+-------------------------------------------------------------+ -| year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5) | -+-------------------------------------------------------------+ -| 2020-01-01 00:00:00 | -+-------------------------------------------------------------+ -1 row in set (0.11 sec) -``` -### keywords +## Example +1. Rounding to the whole year + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18'); + ``` + ``` + +----------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0))) | + +----------------------------------------------------------+ + | 2023-01-01 00:00:00 | + +----------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13'); + ``` + ``` + +-------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0))) | + +-------------------------------------------------+ + | 2023-01-01 00:00:00 | + +-------------------------------------------------+ + ``` - YEAR_FLOOR, YEAR, FLOOR +2. Round based on origin + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', '2020-03-15'); + ``` + ``` + +-----------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), cast('2020-03-15' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------------+ + | 2023-03-15 00:00:00 | + +-----------------------------------------------------------------------------------------------+ + ``` -### Best Practice +3. Rounding with period as unit + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5); + ``` + ``` + +----------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5) | + +----------------------------------------------------+ + | 2020-01-01 00:00:00 | + +----------------------------------------------------+ + ``` -See also [date_floor](./date-floor) +4. Round origin and period + ```sql + SELECT YEAR_FLOOR('2023-07-13 22:28:18', 5, '2018-06-01'); + ``` + ``` + +--------------------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13 22:28:18' as DATETIMEV2(0)), 5, cast('2018-06-01' as DATETIMEV2(0))) | + +--------------------------------------------------------------------------------------------------+ + | 2023-06-01 00:00:00 | + +--------------------------------------------------------------------------------------------------+ + ``` + ```sql + SELECT YEAR_FLOOR('2023-07-13', 5, '2016-01-01'); + ``` + ``` + +-----------------------------------------------------------------------------------------+ + | year_floor(cast('2023-07-13' as DATETIMEV2(0)), 5, cast('2016-01-01' as DATETIMEV2(0))) | + +-----------------------------------------------------------------------------------------+ + | 2021-01-01 00:00:00 | + +-----------------------------------------------------------------------------------------+ + ```