---
url: /v6.2/calculation-function-date.md
---
# 日期函数

## add_day

| 语法         | add_day(T,I)              |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的天数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始日期算起，数值字段对应天数之后的日期，如果数值字段是负数，则返回对应天数之前的日期。 |
| 例子         | add_day('2018-02-02', 3)，返回：2018-02-05 |

## add_hour

| 语法         | add_hour(T,I)             |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的小时数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始时间算起，数值字段对应小时数之后的时间，如果数值字段是负数，则返回对应小时数之前的时间。 |
| 例子         | add_hour('2018-02-02 08:30:00.000', 3)，返回：2018-02-02 11:30:00.000 |

## add_minute

| 语法         | add_minute(T,I)           |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的分钟数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始时间算起，数值字段对应分钟数之后的时间，如果数值字段是负数，则返回对应分钟数之前的时间。 |
| 例子         | add_minute('2018-02-02 08:30:00.000', 3)，返回：2018-02-02 08:33:00.000 |

## add_month

| 语法         | add_month(T,I)            |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的月数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始日期算起，数值字段对应月数之后的日期，如果数值字段是负数，则返回对应月数之前的日期。 |
| 例子         | add_month('2018-02-02', 3)，返回：2018-05-02 |

## add_quarter

| 语法         | add_quarter(T,I)          |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的季度数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始日期算起，数值字段对应季度数之后的日期，如果数值字段是负数，则返回对应季度数之前的日期。 |
| 例子         | add_quarter('2018-02-02', 3)，返回：2018-05-02 |

## add_week

| 语法         | add_week(T,I)             |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的周数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始日期算起，数值字段对应星期数之后的日期，如果数值字段是负数，则返回对应星期数之前的日期。 |
| 例子         | add_week('2018-02-02', 3)，返回：2018-05-02 |

## add_year

| 语法         | add_year(T,I)             |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的年数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 返回从起始日期算起，数值字段对应年数之后的日期，如果数值字段是负数，则返回对应年数之前的日期。 |
| 例子         | add_year('2018-02-02', 3)，返回：2021-02-02 |

## add_year_keep_woy

| 语法         | add_year_keep_woy(T,I)    |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 要增加的年数，可选类型：数字 |
| 返回值类型   | 时间                  |
| 描述         | 和 add_year 类似，但是调整日期使得年中周数保持不变 |
| 例子         | add_year_keep_woy('2023-01-01', 1)，返回：2024-01-01（示例，具体结果因周数计算逻辑而异） |
| 不支持的数据源 | mysql、tidb、sqlserver、redshift、spark、hive、impala、presto、db2、mongodb、maxcompute |

## age_in_days

| 语法         | age_in_days(START, END)   |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在日期上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_days('2021-05-31 00:00:50', '2022-05-31 00:00:00')，返回：364 |

## age_in_hours

| 语法         | age_in_hours(START, END)  |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在小时上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_hours('2021-05-31 00:00:50', '2022-05-31 00:00:00')，返回：8759 |

## age_in_milliseconds

| 语法         | age_in_milliseconds(START, END) |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在毫秒上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_milliseconds('2021-05-31 00:00:00.531', '2022-05-31 00:00:00.000')，返回：31535999469 |

## age_in_minutes

| 语法         | age_in_minutes(START, END) |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在分钟上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_minutes('2021-05-31 00:00:50', '2022-05-31 00:00:00')，返回：525599 |

## age_in_months

| 语法         | age_in_months(START, END) |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在月份上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_months('2021-05-31 00:00:50', '2022-05-31 00:00:00')，返回：11 |

## age_in_seconds

| 语法         | age_in_seconds(START, END) |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在秒上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_seconds('2021-05-31 00:00:00.531', '2022-05-31 00:00:00.000')，返回：31535999 |

## age_in_years

| 语法         | age_in_years(START, END)  |
|--------------|---------------------------|
| 参数说明     | 1. 起始时间，时间类型参数；2. 结束时间，时间类型参数 |
| 返回值类型   | 数字                    |
| 描述         | 比较两个时间在年份上的差异，所有时间部分均参与运算。 |
| 例子         | age_in_years('2021-05-31 00:00:50', '2022-05-31 00:00:00')，返回：0 |

## diff_in_day

| 语法         | diff_in_day(START,END)    |
|--------------|---------------------------|
| 参数说明     | 1. 指定起始，可选类型：时间；2. 指定结束，可选类型：时间 |
| 返回值类型   | 数字                  |
| 描述         | 比较两个日期在天数上的差异。 |
| 例子         | diff_in_day('2015-02-03', '2018-02-03')，返回：1095 |

## diff_in_hour

| 语法         | diff_in_hour(START,END)   |
|--------------|---------------------------|
| 参数说明     | 1. 指定起始，可选类型：时间；2. 指定结束，可选类型：时间 |
| 返回值类型   | 数字                  |
| 描述         | 比较两个时间在小时上的差异。 |
| 例子         | diff_in_hour('2015-03-24 16:32:32', '2018-02-02 12:34:43')，返回：25100 |

## diff_in_minute

| 语法         | diff_in_minute(START,END) |
|--------------|---------------------------|
| 参数说明     | 1. 指定起始，可选类型：时间；2. 指定结束，可选类型：时间 |
| 返回值类型   | 数字                  |
| 描述         | 比较两个时间在分钟上的差异。 |
| 例子         | diff_in_minute('2015-03-24 16:32:32', '2018-02-02 12:34:43')，返回：1506002 |

## diff_in_month

| 语法         | diff_in_month(START,END)  |
|--------------|---------------------------|
| 参数说明     | 1. 指定起始，可选类型：时间；2. 指定结束，可选类型：时间 |
| 返回值类型   | 数字                  |
| 描述         | 比较两个日期在月份上的差异。 |
| 例子         | diff_in_month('2015-02-03', '2018-02-03')，返回：36 |

## diff_in_year

| 语法         | diff_in_year(START,END)   |
|--------------|---------------------------|
| 参数说明     | 1. 指定起始，可选类型：时间；2. 指定结束，可选类型：时间 |
| 返回值类型   | 数字                  |
| 描述         | 比较两个时间在年份上的差异。 |
| 例子         | diff_in_year('2015-02-03', '2018-02-03')，返回：3 |

## end_of_month

| 语法         | end_of_month(T)           |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 获取时间字段所在的月末最后一天的起始时间 |
| 例子         | end_of_month('2018-02-02')，返回：2018-02-28 |

## extract_day

| 语法         | extract_day(T)            |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的天部分，表示当天是当月是第几天。 |
| 例子         | extract_day('2018-02-02')，返回：2 |

## extract_dow

| 语法         | extract_dow(T)            |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的天部分，表示当天是星期几。 |
| 例子         | extract_dow('2018-02-02')，返回：5 |

## extract_doy

| 语法         | extract_doy(T)            |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的天部分，表示当天是一年是第几天。 |
| 例子         | extract_doy('2018-02-02')，返回：33 |

## extract_hour

| 语法         | extract_hour(T)           |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的小时部分，表示当前小时数。 |
| 例子         | extract_hour('2018-02-03 13:23:21')，返回：13 |

## extract_minute

| 语法         | extract_minute(T)         |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的分钟部分，表示当前分钟数。 |
| 例子         | extract_minute('2018-02-03 13:23:21')，返回：23 |

## extract_month

| 语法         | extract_month(T)          |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的月份部分。 |
| 例子         | extract_month('2018-02-02')，返回：2 |

## extract_quarter

| 语法         | extract_quarter(T)        |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的季度部分。 |
| 例子         | extract_quarter('2018-02-02')，返回：1 |

## extract_second

| 语法         | extract_second(T)         |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的秒部分，表示当前秒数。 |
| 例子         | extract_second('2018-02-03 13:23:21')，返回：21 |

## extract_week

| 语法         | extract_week(T)           |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的星期部分，表示当天所属星期是一年是第几个星期。 |
| 例子         | extract_week('2018-02-02')，返回：4 |

## extract_year

| 语法         | extract_year(T)          |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数中的年份部分。 |
| 例子         | extract_year('2018-02-02')，返回：2018 |

## month_weekday_count

| 语法         | month_weekday_count(YEAR,MONTH) |
|--------------|---------------------------|
| 参数说明     | 1. 年份，可选类型：数字；2. 月份，可选类型：数字 |
| 返回值类型   | 数字                  |
| 描述         | 获取参数所在月份的工作日天数。 |
| 例子         | month_weekday_count(2018, 2)，返回：20 |
| 不支持的数据源 | mysql、tidb、sqlserver、redshift、oracle、impala、hive、spark、db2、mongodb、maxcompute |

## now

| 语法         | now()                     |
|--------------|---------------------------|
| 参数说明     | 无参数 |
| 返回值类型   | 时间                  |
| 描述         | 返回当前时间，包含了时、分、秒信息 |
| 例子         | now()，返回：当前系统时间（如 2024-05-20 15:30:45） |

## parse_time

| 语法         | parse_time(S,LITERAL_PATTERN) |
|--------------|---------------------------|
| 参数说明     | 1. 文本类型参数；2. 指定模式，可选类型：字符串 |
| 返回值类型   | 时间                  |
| 描述         | 使用 literal_pattern 将 s 参数解析成时间类型 |
| 例子         | parse_time('2024-05-20', 'yyyy-MM-dd')，返回：2024-05-20 |
| 不支持的数据源 | sqlserver |

## time_in_range

| 语法         | time_in_range(T,S)        |
|--------------|---------------------------|
| 参数说明     | 1. 时间类型参数；2. 文本类型参数 |
| 返回值类型   | 布尔                  |
| 描述         | 判断日期 date 是否在指定的范围，可选范围有：'Current Year', 'Current Year-to-Date', 'Current Quarter', 'Current Quarter-to-Date', 'Current Month', 'Current Month-to-Date', 'Current Week', 'Current Week-to-Date', 'Today', 'Current Hour', 'Yesterday', 'Recent 7 days', 'Recent 30 days', 'Recent 90 days', 'All Available Date', 'All Invalid Date', 'All' |
| 例子         | time_in_range('2024-05-20', 'Today')，返回：TRUE（若当前日期为 2024-05-20） |

## today

| 语法         | today()                   |
|--------------|---------------------------|
| 参数说明     | 无参数 |
| 返回值类型   | 时间                  |
| 描述         | 返回当前日期，不包含时、分、秒信息 |
| 例子         | today()，返回：当前系统日期（如 2024-05-20） |

## trunc_day

| 语法         | trunc_day(T)              |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间或者日期列截取到天。 |
| 例子         | trunc_day('2018-02-02 12:30:59')，返回：'2018-02-02' |

## trunc_hour

| 语法         | trunc_hour(T)             |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间列截取到小时，更细粒度全都置为0。 |
| 例子         | trunc_hour('2018-02-02 12:23:32')，返回：'2018-02-02 12:00:00' |

## trunc_minute

| 语法         | trunc_minute(T)           |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间列截取到分钟，更细粒度全都置为0。 |
| 例子         | trunc_minute('2018-02-02 12:23:32')，返回：'2018-02-02 12:23:00' |

## trunc_month

| 语法         | trunc_month(T)            |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间或者日期列截取到月，日期置为1日。 |
| 例子         | trunc_month('2018-02-02 12:23:32')，返回：'2018-02-01' |

## trunc_millisecond

| 语法         | trunc_millisecond(T)      |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间列截取到毫秒，更细粒度全都置为0。 |
| 例子         | trunc_millisecond('2018-02-02 12:23:32.123')，返回：'2018-02-02 12:23:32.123' |

## trunc_quarter

| 语法         | trunc_quarter(T)          |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间或者日期列截取到季度，月份置为季度中的第一个月，日期置为1日。 |
| 例子         | trunc_quarter('2018-05-02 12:23:32')，返回：'2018-04-01' |

## trunc_second

| 语法         | trunc_second(T)           |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间列截取到秒，更细粒度全都置为0。 |
| 例子         | trunc_second('2018-02-02 12:23:32.123')，返回：'2018-02-02 12:23:32.000' |

## trunc_week

| 语法         | trunc_week(T)             |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间或者日期列截取到周，月份和日期置为本周的第一天。 |
| 例子         | trunc_week('2018-02-02')，返回：'2018-01-29' |

## trunc_year

| 语法         | trunc_year(T)             |
|--------------|---------------------------|
| 参数说明     | 时间类型参数 |
| 返回值类型   | 时间                  |
| 描述         | 将时间或者日期列截取到年，月份和日期置为1月1日。 |
| 例子         | trunc_year('2018-02-02 12:23:32')，返回：'2018-01-01' |