> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> 日期和时间处理函数文档
# 日期和时间处理函数
本节中的大多数函数都接受可选的时区参数，例如 `Europe/Amsterdam`。在这种情况下，使用的时区将是指定的时区，而不是本地 (默认) 时区。
**示例**
```sql theme={null}
SELECT
toDateTime('2016-06-15 23:00:00') AS time,
toDate(time) AS date_local,
toDate(time, 'Asia/Yekaterinburg') AS date_yekat,
toString(time, 'US/Samoa') AS time_samoa
```
```text theme={null}
┌────────────────time─┬─date_local─┬─date_yekat─┬─time_samoa──────────┐
│ 2016-06-15 23:00:00 │ 2016-06-15 │ 2016-06-16 │ 2016-06-15 09:00:00 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘
```
为兼容 SQL 标准，以下函数 `NOW`、`CURRENT_TIMESTAMP`、`TODAY` 和 `CURRENT_DATE` 可在不加括号的情况下使用。
{/*AUTOGENERATED_START*/}
## UTCTimestamp
引入版本：v22.11.0
返回查询分析时刻的当前日期和时间。该函数是常量表达式。
此函数的结果与 `now('UTC')` 相同。添加它仅是为了支持 MySQL。推荐使用 [`now`](#now)。
**语法**
```sql theme={null}
UTCTimestamp()
```
**别名**: `UTC_timestamp`
**参数**
* 无。
**返回值**
返回查询分析时刻的当前日期和时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**获取当前 UTC 时间戳**
```sql title=Query theme={null}
SELECT UTCTimestamp()
```
```response title=Response theme={null}
┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘
```
## YYYYMMDDToDate
引入版本：v23.9.0
将包含年份、月份和日期数字的数值转换为 `Date`。
此函数与 [`toYYYYMMDD()`](/zh/reference/functions/regular-functions/date-time-functions#toYYYYMMDD) 的作用相反。
如果输入未编码出有效的 Date 值，则输出结果未定义。
**语法**
```sql theme={null}
YYYYMMDDToDate(YYYYMMDD)
```
**参数**
* `YYYYMMDD` — 包含年、月、日的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
根据给定参数返回一个 `Date` 值 [`Date`](/zh/reference/data-types/date)
**示例**
**示例**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate(20230911);
```
```response title=Response theme={null}
┌─toYYYYMMDD(20230911)─┐
│ 2023-09-11 │
└──────────────────────┘
```
## YYYYMMDDToDate32
引入版本：v23.9.0
将包含年、月、日的数值转换为 `Date32`。
此函数与 [`toYYYYMMDD()`](/zh/reference/functions/regular-functions/date-time-functions#toYYYYMMDD) 函数相反。
如果输入未编码为有效的 `Date32` 值，则输出结果未定义。
**语法**
```sql theme={null}
YYYYMMDDToDate32(YYYYMMDD)
```
**参数**
* `YYYYMMDD` — 包含年、月、日的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
返回由给定参数生成的 `Date32` 值 [`Date32`](/zh/reference/data-types/date32)
**示例**
**示例**
```sql title=Query theme={null}
SELECT YYYYMMDDToDate32(20000507);
```
```response title=Response theme={null}
┌─YYYYMMDDToDate32(20000507)─┐
│ 2000-05-07 │
└────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime
引入版本：v23.9.0
将包含年、月、日、时、分、秒的数字转换为 `DateTime`。
此函数与 [`toYYYYMMDDhhmmss()`](/zh/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss) 的作用相反。
如果输入未编码为有效的 `DateTime` 值，则输出结果未定义。
**语法**
```sql theme={null}
YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])
```
**参数**
* `YYYYMMDDhhmmss` — 包含年、月、日、时、分、秒的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `timezone` — 时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
根据给定参数返回 `DateTime` 值。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**示例**
```sql title=Query theme={null}
SELECT YYYYMMDDToDateTime(20230911131415);
```
```response title=Response theme={null}
┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│ 2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘
```
## YYYYMMDDhhmmssToDateTime64
引入版本：v23.9.0
将包含年、月、日、小时、分钟和秒的数字转换为 `DateTime64`。
此函数与 [`toYYYYMMDDhhmmss()`](/zh/reference/functions/regular-functions/date-time-functions#toYYYYMMDDhhmmss) 函数的作用相反。
如果输入未编码为有效的 `DateTime64` 值，则输出结果未定义。
**语法**
```sql theme={null}
YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])
```
**参数**
* `YYYYMMDDhhmmss` — 包含年、月、日、时、分、秒的数值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `precision` — 小数部分精度 (0-9) 。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
根据给定参数返回一个 `DateTime64` 值。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**示例**
```sql title=Query theme={null}
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│ 2023-09-11 13:14:15.000 │
└──────────────────────────┘
```
## addDate
引入版本：v23.9.0
将时间间隔加到给定的日期、日期时间，或以字符串编码的日期或日期时间上。
如果相加后的值超出该数据类型的取值范围，则结果未定义。
**语法**
```sql theme={null}
addDate(datetime, interval)
```
**参数**
* `datetime` — 要添加 `interval` 的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `interval` — 要添加的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**返回值**
返回将 `interval` 添加到 `datetime` 后得到的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为日期添加时间间隔**
```sql title=Query theme={null}
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─addDate(toDa⋯valYear(3))─┐
│ 2021-01-01 │
└──────────────────────────┘
```
## addDays
引入版本：v1.1.0
为日期、日期时间，或以字符串编码的日期或日期时间增加指定天数。
**语法**
```sql theme={null}
addDays(datetime, num)
```
**参数**
* `datetime` — 要在其基础上增加指定天数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要增加的天数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 天后的结果。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同的日期类型增加天数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addDays(date, 5) AS add_days_with_date,
addDays(date_time, 5) AS add_days_with_date_time,
addDays(date_time_string, 5) AS add_days_with_date_time_string
```
```response title=Response theme={null}
┌─add_days_with_date─┬─add_days_with_date_time─┬─add_days_with_date_time_string─┐
│ 2024-01-06 │ 2024-01-06 00:00:00 │ 2024-01-06 00:00:00.000 │
└────────────────────┴─────────────────────────┴────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯valDay(10))─┐
│ 1998-06-26 │
└──────────────────────────┘
```
## addHours
引入版本：v1.1.0
为日期、日期时间，或以字符串编码的日期或日期时间增加指定小时数。
**语法**
```sql theme={null}
addHours(datetime, num)
```
**参数**
* `datetime` — 要添加指定小时数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的小时数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 小时后的结果：[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**为不同日期类型添加小时**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addHours(date, 12) AS add_hours_with_date,
addHours(date_time, 12) AS add_hours_with_date_time,
addHours(date_time_string, 12) AS add_hours_with_date_time_string
```
```response title=Response theme={null}
┌─add_hours_with_date─┬─add_hours_with_date_time─┬─add_hours_with_date_time_string─┐
│ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00 │ 2024-01-01 12:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alHour(10))─┐
│ 1998-06-16 10:00:00 │
└──────────────────────────┘
```
## addInterval
引入版本：v22.11.0
将一个时间间隔加到另一个时间间隔或时间间隔元组中。
相同类型的时间间隔会合并成一个时间间隔。例如，如果传入 `toIntervalDay(1)` 和 `toIntervalDay(2)`，则结果将是 `(3)`，而不是 `(1,1)`。
**语法**
```sql theme={null}
addInterval(interval_1, interval_2)
```
**参数**
* `interval_1` — 第一个时间间隔或由多个时间间隔组成的 Tuple。[`Interval`](/zh/reference/data-types/int-uint) 或 [`Tuple(Interval)`](/zh/reference/data-types/tuple)
* `interval_2` — 要相加的第二个时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**返回值**
返回由时间间隔组成的 Tuple [`Tuple(Interval)`](/zh/reference/data-types/tuple)
**示例**
**时间间隔相加**
```sql title=Query theme={null}
SELECT addInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT addInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT addInterval(INTERVAL 2 DAY, INTERVAL 1 DAY)
```
```response title=Response theme={null}
┌─addInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,1) │
└───────────────────────────────────────────────────┘
┌─addInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,1) │
└────────────────────────────────────────────────────────────────────────┘
┌─addInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (3) │
└─────────────────────────────────────────────────┘
```
## addMicroseconds
引入版本：v22.6.0
向日期时间或字符串形式的日期时间添加指定的微秒数。
**语法**
```sql theme={null}
addMicroseconds(datetime, num)
```
**参数**
* `datetime` — 要添加指定微秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的微秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `date_time` 加上 `num` 微秒后的结果。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同的日期时间类型添加微秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMicroseconds(date_time, 1000000) AS add_microseconds_with_date_time,
addMicroseconds(date_time_string, 1000000) AS add_microseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_microseconds_with_date_time─┬─add_microseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000000 │ 2024-01-01 00:00:01.000000 │
└─────────────────────────────────┴────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘
```
## addMilliseconds
版本引入：v22.6.0
为日期时间或以字符串编码的日期时间添加指定的毫秒数。
**语法**
```sql theme={null}
addMilliseconds(datetime, num)
```
**参数**
* `datetime` — 要加上指定毫秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的毫秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回加上 `num` 毫秒后的 `datetime`。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同的日期时间类型添加毫秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMilliseconds(date_time, 1000) AS add_milliseconds_with_date_time,
addMilliseconds(date_time_string, 1000) AS add_milliseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_milliseconds_with_date_time─┬─add_milliseconds_with_date_time_string─┐
│ 2024-01-01 00:00:01.000 │ 2024-01-01 00:00:01.000 │
└─────────────────────────────────┴────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯second(10))─┐
│ 1998-06-16 00:00:00.010 │
└──────────────────────────┘
```
## addMinutes
引入版本：v1.1.0
将指定的分钟数加到日期、日期时间，或以字符串编码的日期或日期时间上。
**语法**
```sql theme={null}
addMinutes(datetime, num)
```
**参数**
* `datetime` — 要添加指定分钟数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的分钟数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 分钟后的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**为不同日期类型添加分钟**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMinutes(date, 20) AS add_minutes_with_date,
addMinutes(date_time, 20) AS add_minutes_with_date_time,
addMinutes(date_time_string, 20) AS add_minutes_with_date_time_string
```
```response title=Response theme={null}
┌─add_minutes_with_date─┬─add_minutes_with_date_time─┬─add_minutes_with_date_time_string─┐
│ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00 │ 2024-01-01 00:20:00.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯Minute(10))─┐
│ 1998-06-16 00:10:00 │
└──────────────────────────┘
```
## addMonths
引入版本：v1.1.0
为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的月份。
**语法**
```sql theme={null}
addMonths(datetime, num)
```
**参数**
* `datetime` — 要加上指定月数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的月数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 个月后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**向不同日期类型添加月份**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addMonths(date, 6) AS add_months_with_date,
addMonths(date_time, 6) AS add_months_with_date_time,
addMonths(date_time_string, 6) AS add_months_with_date_time_string
```
```response title=Response theme={null}
┌─add_months_with_date─┬─add_months_with_date_time─┬─add_months_with_date_time_string─┐
│ 2024-07-01 │ 2024-07-01 00:00:00 │ 2024-07-01 00:00:00.000 │
└──────────────────────┴───────────────────────────┴──────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯lMonth(10))─┐
│ 1999-04-16 │
└──────────────────────────┘
```
## addNanoseconds
引入版本：v22.6.0
为日期时间或以字符串编码的日期时间添加指定数量的纳秒。
**语法**
```sql theme={null}
addNanoseconds(datetime, num)
```
**参数**
* `datetime` — 要添加指定纳秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的纳秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 纳秒后的结果，类型为 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同的日期时间类型添加纳秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addNanoseconds(date_time, 1000) AS add_nanoseconds_with_date_time,
addNanoseconds(date_time_string, 1000) AS add_nanoseconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_nanoseconds_with_date_time─┬─add_nanoseconds_with_date_time_string─┐
│ 2024-01-01 00:00:00.000001000 │ 2024-01-01 00:00:00.000001000 │
└────────────────────────────────┴───────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
```
```response title=Response theme={null}
┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘
```
## addQuarters
引入版本：v20.1.0
为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的季度。
**语法**
```sql theme={null}
addQuarters(datetime, num)
```
**参数**
* `datetime` — 要添加指定季度数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的季度数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回在 `datetime` 基础上加上 `num` 个季度后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同的日期类型添加季度**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addQuarters(date, 1) AS add_quarters_with_date,
addQuarters(date_time, 1) AS add_quarters_with_date_time,
addQuarters(date_time_string, 1) AS add_quarters_with_date_time_string
```
```response title=Response theme={null}
┌─add_quarters_with_date─┬─add_quarters_with_date_time─┬─add_quarters_with_date_time_string─┐
│ 2024-04-01 │ 2024-04-01 00:00:00 │ 2024-04-01 00:00:00.000 │
└────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯uarter(10))─┐
│ 2000-12-16 │
└──────────────────────────┘
```
## addSeconds
首次引入于：v1.1.0
将指定的秒数加到日期、日期时间，或字符串编码的日期或日期时间上。
**语法**
```sql theme={null}
addSeconds(datetime, num)
```
**参数**
* `datetime` — 要加上指定秒数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 秒后的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**为不同日期类型添加秒数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addSeconds(date, 30) AS add_seconds_with_date,
addSeconds(date_time, 30) AS add_seconds_with_date_time,
addSeconds(date_time_string, 30) AS add_seconds_with_date_time_string
```
```response title=Response theme={null}
┌─add_seconds_with_date─┬─add_seconds_with_date_time─┬─add_seconds_with_date_time_string─┐
│ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30 │ 2024-01-01 00:00:30.000 │
└───────────────────────┴────────────────────────────┴───────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│ 1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘
```
## addTupleOfIntervals
引入版本：v22.11.0
将一个时间间隔 Tuple 依次添加到日期或日期时间中。
**语法**
```sql theme={null}
addTupleOfIntervals(datetime, intervals)
```
**参数**
* `datetime` — 要添加时间间隔的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `intervals` — 要添加到 `datetime` 的时间间隔 Tuple。[`Tuple(Interval)`](/zh/reference/data-types/tuple)
**返回值**
返回加上 `intervals` 后的 `date`。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**将时间间隔 Tuple 添加到日期**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│ 2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘
```
## addWeeks
引入版本：v1.1.0
为日期、日期时间或以字符串编码的日期/日期时间增加指定的周数。
**语法**
```sql theme={null}
addWeeks(datetime, num)
```
**参数**
* `datetime` — 要添加指定周数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的周数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 周后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同日期类型添加周数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addWeeks(date, 5) AS add_weeks_with_date,
addWeeks(date_time, 5) AS add_weeks_with_date_time,
addWeeks(date_time_string, 5) AS add_weeks_with_date_time_string
```
```response title=Response theme={null}
┌─add_weeks_with_date─┬─add_weeks_with_date_time─┬─add_weeks_with_date_time_string─┐
│ 2024-02-05 │ 2024-02-05 00:00:00 │ 2024-02-05 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alWeek(10))─┐
│ 1998-08-25 │
└──────────────────────────┘
```
## addYears
引入于：v1.1.0
为日期、日期时间或字符串编码的日期/日期时间增加指定的年数。
**语法**
```sql theme={null}
addYears(datetime, num)
```
**参数**
* `datetime` — 要添加指定年数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要添加的年数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 加上 `num` 年后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**为不同日期类型添加年份**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
addYears(date, 1) AS add_years_with_date,
addYears(date_time, 1) AS add_years_with_date_time,
addYears(date_time_string, 1) AS add_years_with_date_time_string
```
```response title=Response theme={null}
┌─add_years_with_date─┬─add_years_with_date_time─┬─add_years_with_date_time_string─┐
│ 2025-01-01 │ 2025-01-01 00:00:00 │ 2025-01-01 00:00:00.000 │
└─────────────────────┴──────────────────────────┴─────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─plus(CAST('1⋯alYear(10))─┐
│ 2008-06-16 │
└──────────────────────────┘
```
## age
引入版本：v23.1.0
返回 `startdate` 与 `enddate` 之间差值中对应单位的分量。
该差值按 1 纳秒精度计算。
例如，2021-12-29 与 2022-01-01 之间的差值，按 day 单位计算为 3 天，
按 month 单位计算为 0 个月，按 year 单位计算为 0 年。
有关 `age` 的替代方案，请参见函数 [`dateDiff`](#dateDiff)。
**语法**
```sql theme={null}
age('unit', startdate, enddate[, timezone])
```
**参数**
* `unit` — 结果的时间间隔类型。
| 单位 | 可能的值 |
| ----------- | ---------------------------------------- |
| nanosecond | `nanosecond`, `nanoseconds`, `ns` |
| microsecond | `microsecond`, `microseconds`, `us`, `u` |
| millisecond | `millisecond`, `milliseconds`, `ms` |
| second | `second`, `seconds`, `ss`, `s` |
| minute | `minute`, `minutes`, `mi`, `n` |
| hour | `hour`, `hours`, `hh`, `h` |
| day | `day`, `days`, `dd`, `d` |
| week | `week`, `weeks`, `wk`, `ww` |
| month | `month`, `months`, `mm`, `m` |
| quarter | `quarter`, `quarters`, `qq`, `q` |
| year | `year`, `years`, `yyyy`, `yy` |
* `startdate` — 相减时的第一个时间值 (减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `enddate` — 相减时的第二个时间值 (被减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。时区名称。如果指定，则同时应用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 各自的时区。如果两者不一致，则结果未定义。[`String`](/zh/reference/data-types/string)
**返回值**
返回以 unit 表示的 enddate 与 startdate 之差。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**按小时计算年龄**
```sql title=Query theme={null}
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
```
```response title=Response theme={null}
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│ 24 │
└───────────────────────────────────────────────────────────────────────────────────┘
```
**按不同单位计算年龄**
```sql title=Query theme={null}
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
age('day', s, e) AS day_age,
age('month', s, e) AS month_age,
age('year', s, e) AS year_age
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 0 │ 0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘
```
## changeDay
引入版本：v24.7.0
更改日期或日期时间中的日字段。
**语法**
```sql theme={null}
changeDay(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回与 `date_or_datetime` 类型相同、但日期部分已修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeDay('2024-01-31'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-15 00:00:00
```
## changeHour
首次引入于：v24.7.0
更改日期或日期时间中的小时部分。
**语法**
```sql theme={null}
changeHour(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要更改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回一个与 `date_or_datetime` 类型相同、但小时部分已修改的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
```
```response title=Response theme={null}
2024-01-01 05:00:00
```
## changeMinute
引入版本：v24.7.0
更改 `日期或日期时间` 的分钟部分。
**语法**
```sql theme={null}
changeMinute(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回一个与 `date_or_datetime` 类型相同、分钟部分已修改的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
```
```response title=Response theme={null}
2024-01-01 12:45:00
```
## changeMonth
引入版本：v24.7.0
更改日期或日期时间中的月份部分。
**语法**
```sql theme={null}
changeMonth(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回与 `date_or_datetime` 类型相同、月份部分已修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeMonth('2024-01-01'::DateTime, 12)
```
```response title=Response theme={null}
2024-12-01 00:00:00
```
## changeSecond
引入版本：v24.7.0
更改日期或日期时间的秒部分。
**语法**
```sql theme={null}
changeSecond(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回与 `date_or_datetime` 类型相同、但秒部分已被修改的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
```
```response title=Response theme={null}
2024-01-01 12:30:15
```
## changeYear
首次引入版本：v24.7.0
更改日期或日期时间中的年份部分。
**语法**
```sql theme={null}
changeYear(date_or_datetime, value)
```
**参数**
* `date_or_datetime` — 要修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `value` — 新值。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
返回一个与 `date_or_datetime` 类型相同、但年份部分已修改的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT changeYear('2024-01-01'::DateTime, 2023)
```
```response title=Response theme={null}
2023-01-01 00:00:00
```
## dateDiff
引入版本：v23.4.0
返回 `startdate` 与 `enddate` 之间跨过的指定 `unit` 边界数。
该差值按相对单位计算。例如，对于单位 day，2021-12-29 与 2022-01-01 之间相差 3 天
(参见 [`toRelativeDayNum`](#toRelativeDayNum)) ；对于单位 month，相差 1 个月 (参见 [`toRelativeMonthNum`](#toRelativeMonthNum)) ；对于单位 year，相差 1 年
(参见 [`toRelativeYearNum`](#toRelativeYearNum)) 。
如果指定单位为 `week`，则 `dateDiff` 假定每周从星期一开始。
请注意，这一行为与函数 `toWeek()` 不同，后者默认将星期日视为每周的开始。
如需 `dateDiff` 的替代方案，请参见函数 [`age`](#age)。
**语法**
```sql theme={null}
dateDiff(unit, startdate, enddate[, timezone])
```
**别名**: `timestampDiff`, `TIMESTAMP_DIFF`, `DATE_DIFF`, `date_diff`, `timestamp_diff`
**参数**
* `unit` — 结果所使用的时间间隔类型。
| 单位 | 可能的值 |
| ----------- | ---------------------------------------- |
| nanosecond | `nanosecond`, `nanoseconds`, `ns` |
| microsecond | `microsecond`, `microseconds`, `us`, `u` |
| millisecond | `millisecond`, `milliseconds`, `ms` |
| second | `second`, `seconds`, `ss`, `s` |
| minute | `minute`, `minutes`, `mi`, `n` |
| hour | `hour`, `hours`, `hh`, `h` |
| day | `day`, `days`, `dd`, `d` |
| week | `week`, `weeks`, `wk`, `ww` |
| month | `month`, `months`, `mm`, `m` |
| quarter | `quarter`, `quarters`, `qq`, `q` |
| year | `year`, `years`, `yyyy`, `yy` |
* `startdate` — 要相减的第一个时间值 (减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `enddate` — 要减去第一个时间值的第二个时间值 (被减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。时区名称。如果指定，则同时应用于 `startdate` 和 `enddate`。如果未指定，则使用 `startdate` 和 `enddate` 各自的时区。如果两者不一致，则结果未指定。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `enddate` 与 `startdate` 之间以 `unit` 表示的差值。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**按小时计算日期差值**
```sql title=Query theme={null}
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌─res─┐
│ 25 │
└─────┘
```
**按不同单位计算日期差**
```sql title=Query theme={null}
SELECT
toDate('2022-01-01') AS e,
toDate('2021-12-29') AS s,
dateDiff('day', s, e) AS day_diff,
dateDiff('month', s, e) AS month_diff,
dateDiff('year', s, e) AS year_diff
```
```response title=Response theme={null}
┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │ 3 │ 1 │ 1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘
```
## dateName
引入版本：v21.7.0
返回日期中指定的部分。
可选值：
* 'year'
* 'quarter'
* 'month'
* 'week'
* 'dayofyear'
* 'day'
* 'weekday'
* 'hour'
* 'minute'
* 'second'
**语法**
```sql theme={null}
dateName(date_part, date[, timezone])
```
**参数**
* `date_part` — 要提取的日期部分。[`String`](/zh/reference/data-types/string)
* `datetime` — 日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回指定的日期部分。[`String`](/zh/reference/data-types/string)
**示例**
**提取不同的日期部分**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
dateName('year', date_value),
dateName('month', date_value),
dateName('day', date_value)
```
```response title=Response theme={null}
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021 │ April │ 14 │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘
```
## dateTrunc
引入版本：v20.8.0
按指定的日期部分截断日期和时间值。
**语法**
```sql theme={null}
dateTrunc(unit, datetime[, timezone])
```
**别名**: `DATE_TRUNC`
**参数**
* `unit` —
用于截断结果的时间间隔类型。可能的值：`nanosecond` (仅限 DateTime64) 、`microsecond` (仅限 DateTime64) 、`millisecond` (仅限 DateTime64) 、`second`、`minute`、`hour`、`day`、`week`、`month`、`quarter`、`year`。
[`String`](/zh/reference/data-types/string)
* `datetime` — 日期和时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回的日期时间使用的时区名称。如未指定，函数将使用 `datetime` 参数的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回截断后的日期时间值。
| Unit Argument | `datetime` Argument | Return Type |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| Year, Quarter, Month, Week | `Date32` or `DateTime64` or `Date` or `DateTime` | [`Date32`](/zh/reference/data-types/date32) or [`Date`](/zh/reference/data-types/date) |
| Day, Hour, Minute, Second | `Date32`, `DateTime64`, `Date`, or `DateTime` | [`DateTime64`](/zh/reference/data-types/datetime64) or [`DateTime`](/zh/reference/data-types/datetime) |
| Millisecond, Microsecond, | Any | [`DateTime64`](/zh/reference/data-types/datetime64) |
| Nanosecond | | with scale 3, 6, or 9 |
**示例**
**不指定时区进行截断**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now());
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │ 2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
```
**使用指定时区截断**
```sql title=Query theme={null}
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
```
```response title=Response theme={null}
┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │ 2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘
```
## formatDateTime
引入版本：v1.1.0
根据给定的格式字符串对日期或日期时间进行格式化。`format` 是一个常量表达式，因此单个结果列不能使用多种格式。
`formatDateTime` 使用 MySQL 日期时间格式，参见 [mysql docs](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format)。
此函数的反向操作是 [`parseDateTime`](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTime)。
使用替换字段，你可以为结果字符串定义模式。
下表中的示例列展示了 `2018-01-02 22:33:44` 的格式化结果。
**替换字段：**
| 占位符 | 说明 | 示例 |
| --- | -------------------------------------- | ---------- |
| %a | 星期名称缩写 (Mon-Sun) | Mon |
| %b | 月份名称缩写 (Jan-Dec) | Jan |
| %c | 以整数表示的月份 (01-12) | 01 |
| %C | 年份除以 100 并截断为整数 (00-99) | 20 |
| %d | 一个月中的第几天，左侧补零 (01-31) | 02 |
| %D | 短格式 MM/DD/YY 日期，等同于 %m/%d/%y | 01/02/18 |
| %e | 一个月中的第几天，左侧补空格 (1-31) | 2 |
| %f | 秒的小数部分 | 123456 |
| %F | 短格式 YYYY-MM-DD 日期，等同于 %Y-%m-%d | 2018-01-02 |
| %g | 两位数年份格式，与 ISO 8601 对齐 | 18 |
| %G | 用于 ISO 周数的四位数年份格式 | 2018 |
| %h | 12 小时制小时 (01-12) | 09 |
| %H | 24 小时制小时 (00-23) | 22 |
| %i | 分钟 (00-59) | 33 |
| %I | 12 小时制小时 (01-12) | 10 |
| %j | 一年中的第几天 (001-366) | 002 |
| %k | 24 小时制小时 (00-23) | 14 |
| %l | 12 小时制小时 (01-12) | 09 |
| %m | 以整数表示的月份 (01-12) | 01 |
| %M | 完整月份名称 (January-December) | January |
| %n | 换行符 | |
| %p | AM 或 PM 标记 | PM |
| %Q | 季度 (1-4) | 1 |
| %r | 12 小时制 HH:MM AM/PM 时间，等同于 %h:%i %p | 10:30 PM |
| %R | 24 小时制 HH:MM 时间，等同于 %H:%i | 22:33 |
| %s | 秒 (00-59) | 44 |
| %S | 秒 (00-59) | 44 |
| %t | 水平制表符 | |
| %T | ISO 8601 时间格式 (HH:MM:SS) ，等同于 %H:%i:%S | 22:33:44 |
| %u | ISO 8601 星期数字表示，周一为 1 (1-7) | 2 |
| %V | ISO 8601 周数 (01-53) | 01 |
| %w | 以整数表示的星期几，周日为 0 (0-6) | 2 |
| %W | 完整星期名称 (Monday-Sunday) | Monday |
| %y | 年份后两位 (00-99) | 18 |
| %Y | 年份 | 2018 |
| %z | 相对于 UTC 的时间偏移，格式为 +HHMM 或 -HHMM | -0500 |
| %% | % 符号 | % |
* 在早于 v23.4 的 ClickHouse 版本中，如果格式化的值是 Date、Date32、DateTime (它们不包含秒的小数部分) 或 precision 为 0 的 DateTime64，`%f` 会输出单个零 (0) 。
* 在早于 v25.1 的 ClickHouse 版本中，`%f` 输出的位数会与 DateTime64 的 标度 指定的位数一致，而不是固定为 6 位。
* 在早于 v23.4 的 ClickHouse 版本中，`%M` 输出的是分钟 (00-59) ，而不是完整月份名称 (January-December) 。
**语法**
```sql theme={null}
formatDateTime(datetime, format[, timezone])
```
**别名**：`DATE_FORMAT`
**参数**
* `datetime` — 要格式化的日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `format` — 包含替换字段的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。格式化后时间使用的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
根据指定格式返回时间和日期值。[`String`](/zh/reference/data-types/string)
**示例**
**使用年份占位符格式化日期**
```sql title=Query theme={null}
SELECT formatDateTime(toDate('2010-01-04'), '%g')
```
```response title=Response theme={null}
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10 │
└────────────────────────────────────────────┘
```
**将 DateTime64 格式化为带有小数秒的格式**
```sql title=Query theme={null}
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
```
```response title=Response theme={null}
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560 │
└─────────────────────────────────────────────────────────────────────┘
```
**按时区格式化**
```sql title=Query theme={null}
SELECT
now() AS ts,
time_zone,
formatDateTime(ts, '%T', time_zone) AS str_tz_time
FROM system.time_zones
WHERE time_zone LIKE 'Europe%'
LIMIT 10
```
```response title=Response theme={null}
┌──────────────────ts─┬─time_zone─────────┬─str_tz_time─┐
│ 2023-09-08 19:13:40 │ Europe/Amsterdam │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Andorra │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Astrakhan │ 23:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Athens │ 22:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belfast │ 20:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Belgrade │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Berlin │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bratislava │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Brussels │ 21:13:40 │
│ 2023-09-08 19:13:40 │ Europe/Bucharest │ 22:13:40 │
└─────────────────────┴───────────────────┴─────────────┘
```
## formatDateTimeInJodaSyntax
引入于：v20.1.0
与 `formatDateTime` 类似，不同之处在于它使用 Joda 风格而不是 MySQL 风格来格式化日期时间。请参阅 [Joda Time 文档](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html)。
此函数的反向操作是 [`parseDateTimeInJodaSyntax`](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTimeInJodaSyntax)。
使用替换字段，可以为结果字符串定义模式。
**替换字段：**
| 占位符 | 描述 | 表示形式 | 示例 |
| --- | ---------------- | ---- | -------------------------- |
| G | 纪元 | 文本 | AD |
| C | 纪元的世纪 (>=0) | 数值 | 20 |
| Y | 纪元中的年份 (>=0) | 年 | 1996 |
| x | 周所在年份 (暂不支持) | 年 | 1996 |
| w | 周所在年份中的周数 (暂不支持) | 数值 | 27 |
| e | 星期中的第几天 | 数值 | 2 |
| E | 星期几 | 文本 | Tuesday; Tue |
| y | 年 | 年 | 1996 |
| D | 一年中的第几天 | 数值 | 189 |
| M | 一年中的月份 | 月 | July; Jul; 07 |
| d | 一个月中的第几天 | 数值 | 10 |
| a | 一天中的上/下半天 | 文本 | PM |
| K | 半天内的小时 (0\~11) | 数值 | 0 |
| h | 半天内的钟点小时 (1\~12) | 数值 | 12 |
| H | 一天中的小时 (0\~23) | 数值 | 0 |
| k | 一天中的钟点小时 (1\~24) | 数值 | 24 |
| m | 一小时中的分钟 | 数值 | 30 |
| s | 一分钟中的秒 | 数值 | 55 |
| S | 秒的小数部分 | 数值 | 978 |
| z | 时区 | 文本 | Eastern Standard Time; EST |
| Z | 时区偏移量 | 时区 | -0800; -0812 |
| ' | 文本转义符 | 定界符 | |
| '' | 单引号 | 字面量 | ' |
**语法**
```sql theme={null}
formatDateTimeInJodaSyntax(datetime, format[, timezone])
```
**参数**
* `datetime` — 要格式化的日期或日期时间值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `format` — 使用 Joda 语法替换字段的格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。格式化时间所用的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
根据指定格式返回日期和时间值。[`String`](/zh/reference/data-types/string)
**示例**
**使用 Joda 语法格式化日期时间**
```sql title=Query theme={null}
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
```
```response title=Response theme={null}
┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56 │
└─────────────────────────────────────────────────────────────────────────────────────────┘
```
## fromDaysSinceYearZero
引入版本：v23.11.0
对于给定的自 [0000 年 1 月 1 日](https://en.wikipedia.org/wiki/Year_zero)以来经过的天数，返回 [ISO 8601 定义的前推格里高利历](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar)中的对应日期。
该计算方式与 MySQL 的 `FROM_DAYS()` 函数相同。如果结果无法表示在 [Date](/zh/reference/data-types/date) 类型的取值范围内，则结果未定义。
**语法**
```sql theme={null}
fromDaysSinceYearZero(days)
```
**别名**: `FROM_DAYS`
**参数**
* `days` — 自零年开始经过的天数。[`UInt32`](/zh/reference/data-types/int-uint)
**返回值**
返回与自零年开始经过的天数对应的日期。[`Date`](/zh/reference/data-types/date)
**示例**
**将自零年开始经过的天数转换为日期**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromDaysSinceYearZero32
引入版本：v23.11.0
对于自 [0000 年 1 月 1 日](https://en.wikipedia.org/wiki/Year_zero) 起经过的给定天数，返回 [ISO 8601 定义的前推格里高利历](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar)中的对应日期。
其计算方式与 MySQL 的 `FROM_DAYS()` 函数相同。如果结果无法在 [`Date32`](/zh/reference/data-types/date32) 类型的取值范围内表示，则结果未定义。
**语法**
```sql theme={null}
fromDaysSinceYearZero32(days)
```
**参数**
* `days` — 自零年起累计经过的天数。[`UInt32`](/zh/reference/data-types/int-uint)
**返回值**
返回与自零年起累计经过的天数对应的日期。[`Date32`](/zh/reference/data-types/date32)
**示例**
**将自零年起累计经过的天数转换为日期**
```sql title=Query theme={null}
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
```
```response title=Response theme={null}
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘
```
## fromModifiedJulianDay
引入版本：v21.1.0
将 [修正儒略日](https://en.wikipedia.org/wiki/Julian_day#Variants) 数值转换为文本格式的 [前推格里高利历](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar) 日期 `YYYY-MM-DD`。此函数支持的日数范围为 `-678941` 到 `2973483` (分别表示 0000-01-01 和 9999-12-31) 。如果日数超出支持范围，则会引发异常。
**语法**
```sql theme={null}
fromModifiedJulianDay(day)
```
**参数**
* `day` — 修正儒略日编号。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
以文本形式返回日期。 [`String`](/zh/reference/data-types/string)
**示例**
**将修正儒略日转换为日期**
```sql title=Query theme={null}
SELECT fromModifiedJulianDay(58849)
```
```response title=Response theme={null}
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01 │
└──────────────────────────────┘
```
## fromModifiedJulianDayOrNull
引入版本：v21.1.0
与 [`fromModifiedJulianDay()`](#fromModifiedJulianDay) 类似，但它不会抛出异常，而是返回 `NULL`。
**语法**
```sql theme={null}
fromModifiedJulianDayOrNull(day)
```
**参数**
* `day` — 修正儒略日编号。[`(U)Int*`](/zh/reference/data-types/int-uint)
**返回值**
如果 `day` 参数有效，则以文本形式返回日期；否则返回 `null`。[`Nullable(String)`](/zh/reference/data-types/nullable)
**示例**
**将修正儒略日转换为日期，并处理 `null` 值**
```sql title=Query theme={null}
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- 无效参数，返回 NULL
```
```response title=Response theme={null}
┌─fromModified⋯Null(58849)─┐
│ 2020-01-01 │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## fromUTCTimestamp
引入版本：v22.1.0
将日期或日期时间值从 UTC 时区转换为指定时区中的日期或日期时间值。此函数主要是为了兼容 Apache Spark 及类似框架而提供。
**语法**
```sql theme={null}
fromUTCTimestamp(datetime, time_zone)
```
**别名**：`from_utc_timestamp`
**参数**
* `datetime` — 日期或日期时间常量值，或表达式。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `time_zone` — String 类型的常量值，或表示时区的表达式。[`String`](/zh/reference/data-types/string)
**返回值**
返回指定时区的 DateTime/DateTime64。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**将 UTC 时区转换为指定时区**
```sql title=Query theme={null}
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│ 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘
```
## fromUnixTimestamp
引入版本：v20.8.0
此函数将 Unix timestamp 转换为日历日期和一天中的时间。
它有两种调用方式：
* 当给定一个类型为 [`Integer`](/zh/reference/data-types/int-uint) 的单个参数时，返回类型为 [`DateTime`](/zh/reference/data-types/datetime) 的值，即其行为类似于 [`toDateTime`](/zh/reference/functions/regular-functions/type-conversion-functions#toDateTime)。
* 当给定两个或三个参数时，第一个参数为 [`Integer`](/zh/reference/data-types/int-uint)、[`Date`](/zh/reference/data-types/date)、[`Date32`](/zh/reference/data-types/date32)、[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 类型的值，第二个参数为常量格式字符串，第三个参数为可选的常量时区字符串，此函数返回类型为 [`String`](/zh/reference/data-types/string) 的值，即其行为类似于 [`formatDateTime`](#formatDateTime)。
在这种情况下，使用 [MySQL 的日期时间格式](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format)。
**语法**
```sql theme={null}
fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])
```
**别名**: `FROM_UNIXTIME`
**参数**
* `timestamp` — Unix 时间戳或日期/日期时间值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `format` — 可选。用于输出格式化的常量格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。常量时区字符串。[`String`](/zh/reference/data-types/string)
**返回值**
传入一个参数时，返回该时间戳对应的 `DateTime`；传入两个或三个参数时，返回 `String`。[`DateTime`](/zh/reference/data-types/datetime) 或 [`String`](/zh/reference/data-types/string)
**示例**
**将 Unix 时间戳转换为 DateTime**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(423543535)
```
```response title=Response theme={null}
┌─fromUnixTimestamp(423543535)─┐
│ 1983-06-04 10:58:55 │
└──────────────────────────────┘
```
**按格式转换 Unix 时间戳**
```sql title=Query theme={null}
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘
```
## fromUnixTimestampInJodaSyntax
引入版本：v23.1.0
此函数将 Unix 时间戳转换为日历日期和一天中的时间。
它有两种调用方式：
当给定一个类型为 [`Integer`](/zh/reference/data-types/int-uint) 的单个参数时，返回类型为 [`DateTime`](/zh/reference/data-types/datetime) 的值，即其行为类似于 [`toDateTime`](/zh/reference/functions/regular-functions/type-conversion-functions#toDateTime)。
当给定两个或三个参数，且第一个参数是类型为 [`Integer`](/zh/reference/data-types/int-uint)、[`Date`](/zh/reference/data-types/date)、[`Date32`](/zh/reference/data-types/date32)、[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 的值，第二个参数是常量格式字符串，第三个参数是可选的常量时区字符串时，该函数返回类型为 [`String`](/zh/reference/data-types/string) 的值，即其行为类似于 [`formatDateTimeInJodaSyntax`](#formatDateTimeInJodaSyntax)。在这种情况下，使用 [Joda 日期时间格式样式](https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html)。
**语法**
```sql theme={null}
fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])
```
**参数**
* `timestamp` — Unix 时间戳或日期时间值。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `format` — 可选。使用 Joda 语法进行输出格式化的常量格式字符串。[`String`](/zh/reference/data-types/string)
* `timezone` — 可选。常量时区字符串。[`String`](/zh/reference/data-types/string)
**返回值**
传入一个参数时，返回日期时间值；传入两个或三个参数时，返回 String。} [`DateTime`](/zh/reference/data-types/datetime) 或 [`String`](/zh/reference/data-types/string)
**示例**
**使用 Joda 格式转换 Unix 时间戳**
```sql title=Query theme={null}
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
```
```response title=Response theme={null}
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘
```
## makeDate
版本引入：v22.6.0
根据以下任一输入创建 `Date`：
* 年、月、日
* 年和一年中的第几天
**语法**
```sql theme={null}
makeDate(year, month, day)
makeDate(year, day_of_year)
```
**参数**
* `year` — 年份。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `month` — 月份 (1-12) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day` — 月中的第几天 (1-31) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day_of_year` — 一年中的第几天 (1-365) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
返回一个根据给定参数构造的 `Date` 值 [`Date`](/zh/reference/data-types/date)
**示例**
**根据年、月、日构造日期**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**根据年份和年内第几天生成日期**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDate32
引入版本：v22.6.0
通过以下任一方式创建 `Date32`：
* 年、月、日
* 年和一年中的第几天
**语法**
```sql theme={null}
makeDate32(year, month, day)
makeDate32(year, day_of_year)
```
**参数**
* `year` — 年份编号。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `month` — 月份编号 (1-12) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day` — 一个月中的日期 (1-31) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day_of_year` — 一年中的第几天 (1-365) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
**返回值**
返回根据提供的参数构造的 `Date32` 值 [`Date32`](/zh/reference/data-types/date32)
**示例**
**由年、月、日构造 Date32**
```sql title=Query theme={null}
SELECT makeDate(2023, 2, 28) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-28 │
└────────────┘
```
**根据年份和一年中的第几天生成 Date32**
```sql title=Query theme={null}
SELECT makeDate(2023, 42) AS date;
```
```response title=Response theme={null}
┌───────date─┐
│ 2023-02-11 │
└────────────┘
```
## makeDateTime
引入版本：v22.6.0
根据年、月、日、时、分和秒创建 `DateTime`，并可选指定 timezone。
**语法**
```sql theme={null}
makeDateTime(year, month, day, hour, minute, second[, timezone])
```
**参数**
* `year` — 年份 (数值) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `month` — 月份 (1-12) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day` — 月中的日期 (1-31) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `hour` — 小时 (0-23) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `minute` — 分钟 (0-59) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `second` — 秒 (0-59) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `timezone` — 时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回根据提供的参数构造的 `DateTime` 值 [`DateTime`](/zh/reference/data-types/datetime)
**示例**
**根据 year、month、day、hour、minute、second 构造 DateTime**
```sql title=Query theme={null}
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
```
```response title=Response theme={null}
┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘
```
## makeDateTime64
引入版本：v22.6.0
根据 year、month、day、hour、minute、second 创建 `DateTime64`，并可选指定 fraction、precision 和 timezone。
**语法**
```sql theme={null}
makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])
```
**参数**
* `year` — 年份。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `month` — 月份 (1-12) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `day` — 一个月中的第几天 (1-31) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `hour` — 小时 (0-23) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `minute` — 分钟 (0-59) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `second` — 秒 (0-59) 。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `fraction` — 秒的小数部分。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal`](/zh/reference/data-types/decimal)
* `precision` — 小数部分的精度 (0-9) 。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回根据给定参数构造的 `DateTime64` 值 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**通过 year、month、day、hour、minute、second 构造 DateTime64**
```sql title=Query theme={null}
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
```
```response title=Response theme={null}
┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│ 2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘
```
## monthName
首次引入于：v22.1.0
返回日期或日期时间值对应的月份名称字符串。
**语法**
```sql theme={null}
monthName(datetime)
```
**参数**
* `datetime` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回月份名称。[`String`](/zh/reference/data-types/string)
**示例**
**从日期中获取月份名称**
```sql title=Query theme={null}
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
```
```response title=Response theme={null}
┌─monthName(date_value)─┐
│ April │
└───────────────────────┘
```
## now
引入版本：v1.1.0
返回查询分析时的当前日期和时间。该函数是一个常量表达式。
**语法**
```sql theme={null}
now([timezone])
```
**别名**: `current_timestamp`
**参数**
* `timezone` — 可选。返回值所用的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回当前日期和时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**不带时区的查询**
```sql title=Query theme={null}
SELECT now()
```
```response title=Response theme={null}
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
```
**指定时区的查询**
```sql title=Query theme={null}
SELECT now('Asia/Istanbul')
```
```response title=Response theme={null}
┌─now('Asia/Istanbul')─┐
│ 2020-10-17 10:42:23 │
└──────────────────────┘
```
**不使用括号的 SQL 标准语法**
```sql title=Query theme={null}
SELECT NOW, CURRENT_TIMESTAMP
```
```response title=Response theme={null}
┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘
```
## now64
引入版本：v20.1.0
返回查询分析时刻的当前日期和时间，具有子秒级精度。该函数是一个常量表达式。
**语法**
```sql theme={null}
now64([scale[, timezone]])
```
**参数**
* `scale` — 可选。时间粒度 (precision) 为 10^-precision 秒。有效范围：\[0 : 9]。通常使用 3 (默认，毫秒) 、6 (微秒) 或 9 (纳秒) 。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。用于返回值的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回带有子秒级精度的当前日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用默认精度和自定义精度的查询**
```sql title=Query theme={null}
SELECT now64(), now64(9, 'Asia/Istanbul')
```
```response title=Response theme={null}
┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘
```
## nowInBlock
自 v22.8.0 引入
返回处理每个数据块时的当前日期和时间。与函数 [`now`](#now) 不同，它不是常量表达式，因此对于运行时间较长的查询，不同块中的返回值会不同。
在运行时间较长的 `INSERT SELECT` 查询中，使用此函数生成当前时间是合理的。
**语法**
```sql theme={null}
nowInBlock([timezone])
```
**参数**
* `timezone` — 可选。返回值所用的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回处理每个数据块时的当前日期和时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**与 now() 函数的区别**
```sql title=Query theme={null}
SELECT
now(),
nowInBlock(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌───────────────now()─┬────────nowInBlock()─┬─sleep(1)─┐
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:19 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:20 │ 0 │
│ 2022-08-21 19:41:19 │ 2022-08-21 19:41:21 │ 0 │
└─────────────────────┴─────────────────────┴──────────┘
```
## nowInBlock64
引入版本：v25.8.0
返回处理每个数据块时的当前日期和时间，精确到毫秒。与函数 [now64](#now64) 不同，它不是常量表达式，因此对于长时间运行的查询，不同块返回的值会有所不同。
在长时间运行的 INSERT SELECT 查询中，使用此函数生成当前时间很有意义。
**语法**
```sql theme={null}
nowInBlock64([scale[, timezone]])
```
**参数**
* `scale` — 可选。时间粒度 (precision) ：10^-precision 秒。有效范围：\[0 : 9]。通常使用 3 (默认，毫秒) 、6 (微秒) 或 9 (纳秒) 。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。返回值的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回处理每个数据块时刻的当前日期和时间，具有子秒级精度。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**与 now64() 函数的区别**
```sql title=Query theme={null}
SELECT
now64(),
nowInBlock64(),
sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
```
```response title=Response theme={null}
┌─────────────────now64()─┬──────────nowInBlock64()─┬─sleep(1)─┐
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:29.534 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:30.535 │ 0 │
│ 2025-07-29 17:07:29.526 │ 2025-07-29 17:07:31.535 │ 0 │
└─────────────────────────┴─────────────────────────┴──────────┘
```
## serverTimezone
引入版本：v23.6.0
返回服务器的时区，即 [`timezone`](/zh/reference/settings/server-settings/settings#timezone) 设置的值。
如果该函数是在分布式表的上下文中执行的，则会生成一个普通列，其值对应各个分片。否则，会生成一个常量值。
**语法**
```sql theme={null}
serverTimezone()
```
**别名**：`serverTimeZone`
**参数**
* 无。
**返回值**
返回服务器时区，类型为 [`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT serverTimeZone()
```
```response title=Response theme={null}
┌─serverTimeZone()─┐
│ UTC │
└──────────────────┘
```
## subDate
引入版本：v23.9.0
从给定的日期、日期时间，或以字符串编码的日期或日期时间中减去时间间隔。
如果相减后的值超出该数据类型的取值范围，则结果未定义。
**语法**
```sql theme={null}
subDate(datetime, interval)
```
**参数**
* `datetime` — 要从中减去 `interval` 的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `interval` — 要减去的时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**返回值**
返回从 `datetime` 中减去 `interval` 后得到的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从日期中减去时间间隔**
```sql title=Query theme={null}
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
```
```response title=Response theme={null}
┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│ 2015-01-01 │
└──────────────────────────────────────────────────┘
```
## subtractDays
引入版本：v1.1.0
从日期、日期时间，或字符串形式的日期或日期时间中减去指定天数。
**语法**
```sql theme={null}
subtractDays(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定天数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的天数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 天后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去天数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractDays(date, 31) AS subtract_days_with_date,
subtractDays(date_time, 31) AS subtract_days_with_date_time,
subtractDays(date_time_string, 31) AS subtract_days_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_days_with_date─┬─subtract_days_with_date_time─┬─subtract_days_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└─────────────────────────┴──────────────────────────────┴─────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
```
```response title=Response theme={null}
┌─minus(CAST('⋯valDay(10))─┐
│ 1998-06-06 │
└──────────────────────────┘
```
## subtractHours
引入版本：v1.1.0
从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的小时数。
**语法**
```sql theme={null}
subtractHours(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定小时数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的小时数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 小时后的结果。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**对不同日期类型减去小时数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractHours(date, 12) AS subtract_hours_with_date,
subtractHours(date_time, 12) AS subtract_hours_with_date_time,
subtractHours(date_time_string, 12) AS subtract_hours_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_hours_with_date─┬─subtract_hours_with_date_time─┬─subtract_hours_with_date_time_string─┐
│ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00 │ 2023-12-31 12:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alHour(10))─┐
│ 1998-06-15 14:00:00 │
└──────────────────────────┘
```
## subtractInterval
首次引入版本：v22.11.0
将一个取负的时间间隔加到另一个时间间隔或由多个时间间隔组成的元组上。
注意：相同类型的时间间隔会合并为单个时间间隔。例如，如果传入 `toIntervalDay(2)` 和 `toIntervalDay(1)`，
那么结果将是 `(1)`，而不是 `(2,1)`。
**语法**
```sql theme={null}
subtractInterval(interval_1, interval_2)
```
**参数**
* `interval_1` — 第一个时间间隔，或由时间间隔组成的 Tuple。[`Interval`](/zh/reference/data-types/int-uint) 或 [`Tuple(Interval)`](/zh/reference/data-types/tuple)
* `interval_2` — 将被取反的第二个时间间隔。[`Interval`](/zh/reference/data-types/int-uint)
**返回值**
返回由时间间隔组成的元组 [`Tuple(T)`](/zh/reference/data-types/tuple)
**示例**
**时间间隔相减**
```sql title=Query theme={null}
SELECT subtractInterval(INTERVAL 1 DAY, INTERVAL 1 MONTH);
SELECT subtractInterval((INTERVAL 1 DAY, INTERVAL 1 YEAR), INTERVAL 1 MONTH);
SELECT subtractInterval(INTERVAL 2 DAY, INTERVAL 1 DAY);
```
```response title=Response theme={null}
┌─subtractInterval(toIntervalDay(1), toIntervalMonth(1))─┐
│ (1,-1) │
└────────────────────────────────────────────────────────┘
┌─subtractInterval((toIntervalDay(1), toIntervalYear(1)), toIntervalMonth(1))─┐
│ (1,1,-1) │
└─────────────────────────────────────────────────────────────────────────────┘
┌─subtractInterval(toIntervalDay(2), toIntervalDay(1))─┐
│ (1) │
└──────────────────────────────────────────────────────┘
```
## subtractMicroseconds
引入版本：v22.6.0
从日期时间或字符串编码的日期时间中减去指定数量的微秒。
**语法**
```sql theme={null}
subtractMicroseconds(datetime, num)
```
**参数**
* `datetime` — 要减去指定微秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的微秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 微秒后的结果：[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**对不同的日期时间类型减去微秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMicroseconds(date_time, 1000000) AS subtract_microseconds_with_date_time,
subtractMicroseconds(date_time_string, 1000000) AS subtract_microseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_microseconds_with_date_time─┬─subtract_microseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000000 │ 2023-12-31 23:59:59.000000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘
```
## subtractMilliseconds
引入版本：v22.6.0
从日期时间或字符串形式编码的日期时间中减去指定毫秒数。
**语法**
```sql theme={null}
subtractMilliseconds(datetime, num)
```
**参数**
* `datetime` — 要减去指定毫秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的毫秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 毫秒后的结果。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同的日期时间类型中减去毫秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMilliseconds(date_time, 1000) AS subtract_milliseconds_with_date_time,
subtractMilliseconds(date_time_string, 1000) AS subtract_milliseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_milliseconds_with_date_time─┬─subtract_milliseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.000 │ 2023-12-31 23:59:59.000 │
└──────────────────────────────────────┴─────────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
```
```response title=Response theme={null}
┌─minus(CAST('⋯second(10))─┐
│ 1998-06-15 23:59:59.990 │
└──────────────────────────┘
```
## subtractMinutes
引入版本：v1.1.0
从日期、日期时间或以字符串编码的日期/日期时间中减去指定的分钟数。
**语法**
```sql theme={null}
subtractMinutes(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定分钟数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的分钟数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 分钟后的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去分钟**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMinutes(date, 30) AS subtract_minutes_with_date,
subtractMinutes(date_time, 30) AS subtract_minutes_with_date_time,
subtractMinutes(date_time_string, 30) AS subtract_minutes_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_minutes_with_date─┬─subtract_minutes_with_date_time─┬─subtract_minutes_with_date_time_string─┐
│ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00 │ 2023-12-31 23:30:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Minute(10))─┐
│ 1998-06-15 23:50:00 │
└──────────────────────────┘
```
## subtractMonths
引入版本：v1.1.0
从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的月数。
**语法**
```sql theme={null}
subtractMonths(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定月数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的月数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 个月后的结果。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去月份**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractMonths(date, 1) AS subtract_months_with_date,
subtractMonths(date_time, 1) AS subtract_months_with_date_time,
subtractMonths(date_time_string, 1) AS subtract_months_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_months_with_date─┬─subtract_months_with_date_time─┬─subtract_months_with_date_time_string─┐
│ 2023-12-01 │ 2023-12-01 00:00:00 │ 2023-12-01 00:00:00.000 │
└───────────────────────────┴────────────────────────────────┴───────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
```
```response title=Response theme={null}
┌─minus(CAST('⋯lMonth(10))─┐
│ 1997-08-16 │
└──────────────────────────┘
```
## subtractNanoseconds
自 v20.1.0 起引入
从日期时间或以字符串编码的日期时间中减去指定纳秒数。
**语法**
```sql theme={null}
subtractNanoseconds(datetime, num)
```
**参数**
* `datetime` — 要减去指定纳秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的纳秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 纳秒后的结果。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同的日期时间类型中减去纳秒**
```sql title=Query theme={null}
WITH
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractNanoseconds(date_time, 1000) AS subtract_nanoseconds_with_date_time,
subtractNanoseconds(date_time_string, 1000) AS subtract_nanoseconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_nanoseconds_with_date_time─┬─subtract_nanoseconds_with_date_time_string─┐
│ 2023-12-31 23:59:59.999999000 │ 2023-12-31 23:59:59.999999000 │
└─────────────────────────────────────┴────────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
```
```response title=Response theme={null}
┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘
```
## subtractQuarters
引入版本：v20.1.0
从日期、日期时间或以字符串编码的日期或日期时间中减去指定数量的季度。
**语法**
```sql theme={null}
subtractQuarters(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定季度数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的季度数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 个季度后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去季度**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractQuarters(date, 1) AS subtract_quarters_with_date,
subtractQuarters(date_time, 1) AS subtract_quarters_with_date_time,
subtractQuarters(date_time_string, 1) AS subtract_quarters_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_quarters_with_date─┬─subtract_quarters_with_date_time─┬─subtract_quarters_with_date_time_string─┐
│ 2023-10-01 │ 2023-10-01 00:00:00 │ 2023-10-01 00:00:00.000 │
└─────────────────────────────┴──────────────────────────────────┴─────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
```
```response title=Response theme={null}
┌─minus(CAST('1⋯Quarter(10))─┐
│ 1996-09-16 │
└───────────────────────────┘
```
## subtractSeconds
引入版本：v1.1.0
从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的秒数。
**语法**
```sql theme={null}
subtractSeconds(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定秒数的日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的秒数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 秒后的结果：[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64(3)`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去秒数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractSeconds(date, 60) AS subtract_seconds_with_date,
subtractSeconds(date_time, 60) AS subtract_seconds_with_date_time,
subtractSeconds(date_time_string, 60) AS subtract_seconds_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_seconds_with_date─┬─subtract_seconds_with_date_time─┬─subtract_seconds_with_date_time_string─┐
│ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00 │ 2023-12-31 23:59:00.000 │
└────────────────────────────┴─────────────────────────────────┴────────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
```
```response title=Response theme={null}
┌─minus(CAST('⋯Second(10))─┐
│ 1998-06-15 23:59:50 │
└──────────────────────────┘
```
## subtractTupleOfIntervals
引入版本：v22.11.0
从日期或日期时间中依次减去一个由时间间隔组成的元组。
**语法**
```sql theme={null}
subtractTupleOfIntervals(datetime, intervals)
```
**参数**
* `datetime` — 要从中减去时间间隔的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `intervals` — 要从 `datetime` 中减去的时间间隔 Tuple。[`Tuple(Interval)`](/zh/reference/data-types/tuple)
**返回值**
返回减去 `intervals` 后的 `date`。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从日期中减去时间间隔 Tuple**
```sql title=Query theme={null}
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
```
```response title=Response theme={null}
┌─subtractTupl⋯alYear(1)))─┐
│ 2016-12-31 │
└──────────────────────────┘
```
## subtractWeeks
引入版本：v1.1.0
从日期、日期时间，或以字符串编码的日期/日期时间中减去指定的周数。
**语法**
```sql theme={null}
subtractWeeks(datetime, num)
```
**参数**
* `datetime` — 要从中减去指定周数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的周数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 周后的结果。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去周数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractWeeks(date, 1) AS subtract_weeks_with_date,
subtractWeeks(date_time, 1) AS subtract_weeks_with_date_time,
subtractWeeks(date_time_string, 1) AS subtract_weeks_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_weeks_with_date─┬─subtract_weeks_with_date_time─┬─subtract_weeks_with_date_time_string─┐
│ 2023-12-25 │ 2023-12-25 00:00:00 │ 2023-12-25 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alWeek(10))─┐
│ 1998-04-07 │
└──────────────────────────┘
```
## subtractYears
引入版本：v1.1.0
从日期、日期时间或以字符串形式编码的日期或日期时间中减去指定的年数。
**语法**
```sql theme={null}
subtractYears(datetime, num)
```
**参数**
* `datetime` — 从中减去指定年数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `num` — 要减去的年数。[`(U)Int*`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float)
**返回值**
返回 `datetime` 减去 `num` 年后的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**从不同日期类型中减去年数**
```sql title=Query theme={null}
WITH
toDate('2024-01-01') AS date,
toDateTime('2024-01-01 00:00:00') AS date_time,
'2024-01-01 00:00:00' AS date_time_string
SELECT
subtractYears(date, 1) AS subtract_years_with_date,
subtractYears(date_time, 1) AS subtract_years_with_date_time,
subtractYears(date_time_string, 1) AS subtract_years_with_date_time_string
```
```response title=Response theme={null}
┌─subtract_years_with_date─┬─subtract_years_with_date_time─┬─subtract_years_with_date_time_string─┐
│ 2023-01-01 │ 2023-01-01 00:00:00 │ 2023-01-01 00:00:00.000 │
└──────────────────────────┴───────────────────────────────┴──────────────────────────────────────┘
```
**使用另一种 INTERVAL 语法**
```sql title=Query theme={null}
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
```
```response title=Response theme={null}
┌─minus(CAST('⋯alYear(10))─┐
│ 1988-06-16 │
└──────────────────────────┘
```
## timeDiff
Introduced in: v23.4.0
返回两个日期或日期时间值之间以秒为单位的差值。
差值按 `enddate` - `startdate` 计算。
该函数等同于 `dateDiff('second', startdate, enddate)`。
如需计算其他单位 (小时、天、月等) 的时间差，请改用 [`dateDiff`](#dateDiff) 函数。
**Syntax**
```sql theme={null}
timeDiff(startdate, enddate)
```
**参数**
* `startdate` — 第一个被相减的时间值 (减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `enddate` — 第二个时间值，即从中减去 `startdate` 的值 (被减数) 。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回 `enddate` 与 `startdate` 之间的差值，以秒表示。[`Int64`](/zh/reference/data-types/int-uint)
**示例**
**计算以秒为单位的时间差**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
```
```response title=Response theme={null}
┌───res─┐
│ 90000 │
└───────┘
```
**计算时间差并换算为小时**
```sql title=Query theme={null}
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
```
```response title=Response theme={null}
┌─hours─┐
│ 25 │
└───────┘
```
**相当于按秒计算的 dateDiff**
```sql title=Query theme={null}
SELECT
timeDiff(toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS time_diff_result,
dateDiff('second', toDateTime('2021-12-29'), toDateTime('2022-01-01')) AS date_diff_result
```
```response title=Response theme={null}
┌─time_diff_result─┬─date_diff_result─┐
│ 259200 │ 259200 │
└──────────────────┴──────────────────┘
```
## timeSlot
Introduced in: v1.1.0
将时间向下舍入到半小时时间间隔的起始时间点。
尽管此函数可以接受扩展类型 `Date32` 和 `DateTime64` 的值作为参数，
但如果传入超出正常范围的时间 (`Date` 为 1970 年至 2149 年 / `DateTime` 为 2106 年) ，则会产生错误结果。
**Syntax**
```sql theme={null}
timeSlot(time[, time_zone])
```
**参数**
* `time` — 要向下取整到半小时时间间隔起始点的时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `time_zone` — 可选。String 类型的常量值，或表示时区的表达式。[`String`](/zh/reference/data-types/string)
**返回值**
返回向下取整到半小时时间间隔起始点的时间。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**将时间向下取整到半小时时间间隔**
```sql title=Query theme={null}
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
```
```response title=Response theme={null}
┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│ 2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘
```
## timeSlots
引入版本：v1.1.0
对于从 `StartTime` 开始、持续 `Duration` 秒的时间间隔，它会返回一个时间点数组，其中包含该区间内按 `Size` 秒向下取整后的各个时间点。`Size` 是可选参数，默认值为 1800 (30 分钟) 。
例如，在对应的会话中搜索页面浏览量时，就需要用到它。
对于 `DateTime64`，返回值的标度可以与 `StartTime` 的标度不同。将采用所有给定参数中的最高标度。
**语法**
```sql theme={null}
timeSlots(StartTime, Duration[, Size])
```
**参数**
* `StartTime` — 时间区间的起始时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `Duration` — 时间区间的持续时间，以秒为单位。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `Size` — 可选。时间槽的大小，以秒为单位。默认值为 1800 (30 分钟) 。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回一个 DateTime/DateTime64 数组 (返回类型与 `StartTime` 的类型一致) 。对于 DateTime64，返回值的标度可能与 `StartTime` 的标度不同——将采用所有给定参数中的最高标度。[`Array(DateTime)`](/zh/reference/data-types/array) 或 [`Array(DateTime64)`](/zh/reference/data-types/array)
**示例**
**为一个时间区间生成时间槽**
```sql title=Query theme={null}
SELECT timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600));
SELECT timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299);
SELECT timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))
```
```response title=Response theme={null}
┌─timeSlots(toDateTime('2012-01-01 12:20:00'), toUInt32(600))─┐
│ ['2012-01-01 12:00:00','2012-01-01 12:30:00'] │
└─────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime('1980-12-12 21:01:02', 'UTC'), toUInt32(600), 299)─┐
│ ['1980-12-12 20:56:13','1980-12-12 21:01:12','1980-12-12 21:06:11'] │
└─────────────────────────────────────────────────────────────────────────┘
┌─timeSlots(toDateTime64('1980-12-12 21:01:02.1234', 4, 'UTC'), toDecimal64(600.1, 1), toDecimal64(299, 0))─┐
│ ['1980-12-12 20:56:13.0000','1980-12-12 21:01:12.0000','1980-12-12 21:06:11.0000'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```
## timestamp
引入版本：v23.9.0
将第一个参数 `expr` 转换为 [`DateTime64(6)`](/zh/reference/data-types/datetime64) 类型。
如果提供了第二个参数 `expr_time`，则会将指定时间加到转换后的值上。
**语法**
```sql theme={null}
timestamp(expr[, expr_time])
```
**参数**
* `expr` — 日期或日期时间。[`String`](/zh/reference/data-types/string)
* `expr_time` — 可选。要添加到转换后值的时间。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `expr` 转换后的值，或加上时间后的 `expr` [`DateTime64(6)`](/zh/reference/data-types/datetime64)
**示例**
**将日期字符串转换为 DateTime64(6)**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
```
**为日期字符串添加时间**
```sql title=Query theme={null}
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
```
```response title=Response theme={null}
┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘
```
## timezone
引入版本：v21.4.0
返回当前会话的时区名称，或者将时区偏移量或时区名称转换为规范的时区名称。
**语法**
```sql theme={null}
timezone()
```
**别名**: `timeZone`
**参数**
* 无。
**返回值**
返回规范的时区名称，返回类型为 [`String`](/zh/reference/data-types/string)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT timezone()
```
```response title=Response theme={null}
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘
```
## timezoneOf
首次引入于：v21.4.0
返回 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 值的时区名称。
**语法**
```sql theme={null}
timezoneOf(datetime)
```
**别名**: `timeZoneOf`
**参数**
* `datetime` — 类型为 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 的值
* `timezone` — 可选。要将 `datetime` 值转换为的时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回 `datetime` 的时区名称。[`String`](/zh/reference/data-types/string)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT timezoneOf(now());
```
```response title=Response theme={null}
┌─timezoneOf(now())─┐
│ Europe/Amsterdam │
└───────────────────┘
```
## timezoneOffset
Introduced in: v21.6.0
返回相对于 [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) 的时区偏移量，单位为秒。
该函数会将指定日期和时间对应的夏令时以及历史时区变更考虑在内。
**Syntax**
```sql theme={null}
timezoneOffset(datetime)
```
**别名**: `timeZoneOffset`
**参数**
* `datetime` — 需要获取其时区偏移量的 `DateTime` 值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回相对于 UTC 的偏移量，单位为秒 [`Int32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDateTime('2021-04-21 10:20:30', 'America/New_York') AS Time,
toTypeName(Time) AS Type,
timezoneOffset(Time) AS Offset_in_seconds,
(Offset_in_seconds / 3600) AS Offset_in_hours;
```
```response title=Response theme={null}
┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │ -14400 │ -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘
```
## toDayOfMonth
引入版本：v1.1.0
返回 `Date` 或 `DateTime` 所在月份中的日期 (1-31) 。
**语法**
```sql theme={null}
toDayOfMonth(datetime)
```
**别名**：`DAY`, `DAYOFMONTH`
**参数**
* `datetime` — 要从中获取一个月中第几天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期/时间在当月中的第几天，类型为 [`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 21 │
└─────────────────────────────────────────────────┘
```
## toDayOfWeek
引入版本：v1.1.0
返回 `Date` 或 `DateTime` 值是星期几的数字。
`toDayOfWeek()` 的双参数形式允许你指定一周从星期一还是星期日开始，
以及返回值范围是 0 到 6 还是 1 到 7。
| 模式 | 每周第一天 | 范围 |
| -- | ----- | ------------------------------- |
| 0 | 星期一 | 1-7：星期一 = 1，星期二 = 2，...，星期日 = 7 |
| 1 | 星期一 | 0-6：星期一 = 0，星期二 = 1，...，星期日 = 6 |
| 2 | 星期日 | 0-6：星期日 = 0，星期一 = 1，...，星期六 = 6 |
| 3 | 星期日 | 1-7：星期日 = 1，星期一 = 2，...，星期六 = 7 |
**语法**
```sql theme={null}
toDayOfWeek(datetime[, mode[, timezone]])
```
**别名**: `DAYOFWEEK`
**参数**
* `datetime` — 用于获取星期几的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `mode` — 可选。指定周模式 (0-3) 的整数。省略时默认为 0。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。转换时使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回给定 `Date` 或 `DateTime` 对应的星期几。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
-- 以下日期为 2023 年 4 月 21 日，是星期五：
SELECT
toDayOfWeek(toDateTime('2023-04-21')),
toDayOfWeek(toDateTime('2023-04-21'), 1)
```
```response title=Response theme={null}
┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│ 5 │ 4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘
```
## toDayOfYear
引入版本：v18.4.0
返回 `Date` 或 `DateTime` 值在一年中是第几天 (1-366) 。
**语法**
```sql theme={null}
toDayOfYear(datetime)
```
**别名**: `DAYOFYEAR`
**参数**
* `datetime` — 用于获取一年中第几天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定 Date 或 DateTime 是一年中的第几天。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 111 │
└────────────────────────────────────────────────┘
```
## toDaysInMonth
引入版本：v26.3.0
返回 `Date` 或 `DateTime` 所在月份的天数。
返回值范围为 28 到 31。
**语法**
```sql theme={null}
toDaysInMonth(datetime)
```
**参数**
* `datetime` — 日期或日期时间，用于获取其所在月份的天数。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期/时间所在月份的天数。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─toDaysInMonth(toDate('2023-02-01'))─┬─toDaysInMonth(toDate('2024-02-01'))─┬─toDaysInMonth(toDate('2023-01-01'))─┐
│ 28 │ 29 │ 31 │
└─────────────────────────────────────┴─────────────────────────────────────┴─────────────────────────────────────┘
```
## toDaysSinceYearZero
引入版本：v23.9.0
对于给定日期，返回自 [0000 年 1 月 1 日](https://en.wikipedia.org/wiki/Year_zero)起，按照 [ISO 8601 定义的前推公历](https://en.wikipedia.org/wiki/Gregorian_calendar#Proleptic_Gregorian_calendar) 计算所经过的天数。
该计算方式与 MySQL 的 [`TO_DAYS`](https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_to-days) 函数相同。
**语法**
```sql theme={null}
toDaysSinceYearZero(date[, time_zone])
```
**别名**: `TO_DAYS`
**参数**
* `date` — 要计算自零年起经过天数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `time_zone` — 时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回自 `0000-01-01` 以来经过的天数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**计算自零年起的天数**
```sql title=Query theme={null}
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
```
```response title=Response theme={null}
┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│ 713569 │
└────────────────────────────────────────────┘
```
## toHour
引入版本：v1.1.0
返回 `DateTime` 或 `DateTime64` 值的小时部分 (0-23) 。
**语法**
```sql theme={null}
toHour(datetime)
```
**别名**: `HOUR`
**参数**
* `datetime` — 要提取小时的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回 `datetime` 的小时值 (0-23) 。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│ 10 │
└───────────────────────────────────────────┘
```
## toISOWeek
引入版本：v20.1.0
返回某个日期或日期时间的 ISO 周数。
这是一个兼容性函数，等同于 `toWeek(date, 3)`。
ISO 周从星期一开始，一年中的第一周包含 1 月 4 日。
根据 ISO 8601，周数范围为 1 到 53。
请注意，接近年初或年末的日期可能会返回上一年或下一年的周数。例如，
2025 年 12 月 29 日返回第 1 周，因为它属于包含 2026 年 1 月 4 日的第一周。
**语法**
```sql theme={null}
toISOWeek(datetime[, timezone])
```
**参数**
* `datetime` — 用于获取 ISO 周数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据 ISO 8601 标准返回 ISO 周数。返回 1 到 53 之间的数值。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**获取 ISO 周数**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │ 52 │
└────────────┴─────────┘
```
**ISO 周可能属于不同年份**
```sql title=Query theme={null}
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
```
```response title=Response theme={null}
┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │ 1 │ 2025 │
└────────────┴─────────┴──────┘
```
## toISOYear
引入版本：v18.4.0
将日期或日期时间转换为 ISO 年编号。
**语法**
```sql theme={null}
toISOYear(datetime)
```
**参数**
* `datetime` — 日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回将输入值转换后的 ISO 年编号。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**从日期值中获取 ISO 年**
```sql title=Query theme={null}
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
```
```response title=Response theme={null}
┌─week1─┬─week2─┐
│ 40 │ 40 │
└───────┴───────┘
```
## toLastDayOfMonth
引入版本：v1.1.0
将日期或日期时间向上取整到当月的最后一天。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toLastDayOfMonth(value)
```
**别名**: `LAST_DAY`
**参数**
* `value` — 要向上取整到当月最后一天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期或日期时间所在月份最后一天对应的日期。[`Date`](/zh/reference/data-types/date)
**示例**
**向上取整到当月最后一天**
```sql title=Query theme={null}
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-30 │
└─────────────────────────────────────────────────────┘
```
## toLastDayOfWeek
Introduced in: v23.5.0
将日期或日期时间向上取整到最近的星期六或星期日。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**语法**
```sql theme={null}
toLastDayOfWeek(datetime[, mode[, timezone]])
```
**参数**
* `datetime` — 要转换的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `mode` — 按 `toWeek()` 函数中的说明确定一周的第一天。默认值为 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 可选。转换时使用的时区。如果未指定，则使用 server 的时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据 `mode`，返回给定日期当天或之后最近的星期六或星期日对应的日期。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32)
**示例**
**向上取整到最近的星期六或星期日**
```sql title=Query theme={null}
SELECT
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')), /* 星期五 */
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* 星期五 */
toLastDayOfWeek(toDate('2023-04-23')), /* 星期日 */
toLastDayOfWeek(toDate('2023-04-23'), 1) /* 星期日 */
FORMAT Vertical
```
```response title=Response theme={null}
行 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')): 2023-04-23
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-22
toLastDayOfWeek(toDate('2023-04-23')): 2023-04-23
toLastDayOfWeek(toDate('2023-04-23'), 1): 2023-04-23
```
## toMillisecond
引入版本：v24.2.0
返回 `DateTime` 或 `DateTime64` 值中的毫秒部分 (0-999) 。
**语法**
```sql theme={null}
toMillisecond(datetime)
```
**别名**：`MILLISECOND`
**参数**
* `datetime` — 要提取毫秒部分的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回 `datetime` 所在分钟内的毫秒值 (0 - 59) 。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
```
```response title=Response theme={null}
┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│ 456 │
└────────────────────────────────────────────────────────────┘
```
## toMinute
引入版本：v1.1.0
返回 `Date` 或 `DateTime` 值的分钟部分 (0-59) 。
**语法**
```sql theme={null}
toMinute(datetime)
```
**别名**: `MINUTE`
**参数**
* `datetime` — 要提取分钟的日期时间值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回 `datetime` 的分钟值 (0 - 59) 。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│ 20 │
└─────────────────────────────────────────────┘
```
## toModifiedJulianDay
引入版本：v21.1.0
将文本格式 `YYYY-MM-DD` 的[逆推格里高利历](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar)日期转换为 `Int32` 类型的[修正儒略日](https://en.wikipedia.org/wiki/Julian_day#Variants)数值。此函数支持 `0000-01-01` 到 `9999-12-31` 范围内的日期。如果参数无法解析为日期，或日期无效，则会引发异常。
**语法**
```sql theme={null}
toModifiedJulianDay(date)
```
**参数**
* `date` — String 格式的日期。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
返回修正儒略日数值。[`Int32`](/zh/reference/data-types/int-uint)
**示例**
**将日期转换为修正儒略日**
```sql title=Query theme={null}
SELECT toModifiedJulianDay('2020-01-01')
```
```response title=Response theme={null}
┌─toModifiedJulianDay('2020-01-01')─┐
│ 58849 │
└───────────────────────────────────┘
```
## toModifiedJulianDayOrNull
Introduced in：v21.1.0
与 [`toModifiedJulianDay()`](#toModifiedJulianDay) 类似，但它不会抛出异常，而是返回 `NULL`。
**Syntax**
```sql theme={null}
toModifiedJulianDayOrNull(date)
```
**参数**
* `date` — 文本形式的日期。[`String`](/zh/reference/data-types/string) 或 [`FixedString`](/zh/reference/data-types/fixedstring)
**返回值**
对于有效的 `date`，返回修正儒略日数；否则返回 `null`。[`Nullable(Int32)`](/zh/reference/data-types/nullable)
**示例**
**将日期转换为修正儒略日，并处理 `null` 值**
```sql title=Query theme={null}
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- 无效日期，返回 NULL
```
```response title=Response theme={null}
┌─toModifiedJu⋯020-01-01')─┐
│ 58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────┘
```
## toMonday
引入版本：v1.1.0
将日期或日期时间向下取整到同一周的周一。返回该日期。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toMonday(value)
```
**参数**
* `value` — 要向下舍入到所在周周一的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期或日期时间所在周的周一对应日期。[`Date`](/zh/reference/data-types/date)
**示例**
**向下舍入到所在周的周一**
```sql title=Query theme={null}
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- 星期五
toMonday(toDate('2023-04-24')); -- 已经是星期一
```
```response title=Response theme={null}
┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│ 2023-04-17 │ 2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘
```
## toMonth
首次引入版本：v1.1.0
返回 `Date` 或 `DateTime` 值中的月份部分 (1-12) 。
**语法**
```sql theme={null}
toMonth(datetime)
```
**别名**: `MONTH`
**参数**
* `datetime` — 用于提取月份的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期/时间中的月份。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 4 │
└────────────────────────────────────────────┘
```
## toMonthNumSinceEpoch
引入版本：v25.3.0
返回自 1970 年起经过的月数
**语法**
```sql theme={null}
toMonthNumSinceEpoch(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
正整数
**示例**
**示例**
```sql title=Query theme={null}
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
657
```
## toQuarter
引入版本：v1.1.0
返回给定 `Date` 或 `DateTime` 值所在年份中的季度 (1-4) 。
**语法**
```sql theme={null}
toQuarter(datetime)
```
**别名**: `QUARTER`
**参数**
* `datetime` — 用于获取所在年份季度的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期/时间所在年份的季度。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2 │
└──────────────────────────────────────────────┘
```
## toRelativeDayNum
引入版本：v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的天数。
确切的时间点属于实现细节，因此不应单独使用此函数。
该函数的主要用途是计算两个日期或日期时间之间相差的天数，例如 `toRelativeDayNum(dt1) - toRelativeDayNum(dt2)`。
**语法**
```sql theme={null}
toRelativeDayNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回自过去某个固定参考点起的天数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对天数**
```sql title=Query theme={null}
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
```
```response title=Response theme={null}
┌─minus(toRela⋯3-01-01')))─┐
│ 90 │
└──────────────────────────┘
```
## toRelativeHourNum
引入版本：v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的小时数。
具体的时间点属于实现细节，因此不应单独使用此函数。
此函数的主要用途是计算两个日期或日期时间之间相差的小时数，例如 `toRelativeHourNum(dt1) - toRelativeHourNum(dt2)`。
**语法**
```sql theme={null}
toRelativeHourNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回自过去某个固定参考点起经过的小时数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对小时数**
```sql title=Query theme={null}
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
```
```response title=Response theme={null}
┌─hours_difference─┐
│ 12 │
└──────────────────┘
```
## toRelativeMinuteNum
自以下版本引入：v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的分钟数。
确切的时间点属于实现细节，因此不应单独使用此函数。
该函数的主要用途是计算两个日期或日期时间之间相差的分钟数，例如：`toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)`。
**语法**
```sql theme={null}
toRelativeMinuteNum(date)
```
**参数**
* `date` — 日期或带时间的日期。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回距过去某个固定参考点的分钟数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对分钟数**
```sql title=Query theme={null}
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
```
```response title=Response theme={null}
┌─minutes_difference─┐
│ 30 │
└────────────────────┘
```
## toRelativeMonthNum
引入版本：v1.1.0
将日期或日期时间转换为自过去某个固定时间点以来经过的月数。
确切的时间点属于实现细节，因此此函数不适合单独使用。
该函数的主要用途是计算两个日期或日期时间之间相差的月数，例如 `toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)`。
**语法**
```sql theme={null}
toRelativeMonthNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回从过去某个固定参考点起算的月份数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对月份序号**
```sql title=Query theme={null}
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
```
```response title=Response theme={null}
┌─months_difference─┐
│ 3 │
└───────────────────┘
```
## toRelativeQuarterNum
引入版本：v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的季度数。
确切的时间点属于实现细节，因此不适合单独使用此函数。
此函数的主要用途是计算两个日期或日期时间之间相差的季度数，例如：`toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)`。
**语法**
```sql theme={null}
toRelativeQuarterNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回从过去某个固定参考点起算的季度数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对季度编号**
```sql title=Query theme={null}
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
```
```response title=Response theme={null}
┌─quarters_difference─┐
│ 1 │
└─────────────────────┘
```
## toRelativeSecondNum
Introduced in: v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的秒数。
该确切时间点属于实现细节，因此此函数不适合单独使用。
此函数的主要用途是计算两个日期或日期时间之间相差的秒数，例如 `toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)`。
**Syntax**
```sql theme={null}
toRelativeSecondNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回自过去某个固定参考点起经过的秒数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对秒数**
```sql title=Query theme={null}
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
```
```response title=Response theme={null}
┌─seconds_difference─┐
│ 60 │
└────────────────────┘
```
## toRelativeWeekNum
引入版本：v1.1.0
将 date 或 date with time 转换为自过去某个固定时间点起经过的周数。
该确切时间点属于实现细节，因此此函数不适合单独使用。
此函数的主要用途是计算两个日期或日期时间之间相差的周数，例如：`toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)`。
**语法**
```sql theme={null}
toRelativeWeekNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回自过去某个固定参考点以来的周数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取相对周数**
```sql title=Query theme={null}
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
```
```response title=Response theme={null}
┌─weeks_difference─┐
│ 1 │
└──────────────────┘
```
## toRelativeYearNum
引入版本：v1.1.0
将日期或日期时间转换为自过去某个固定时间点起经过的年数。
确切的时间点属于实现细节，因此不建议单独使用此函数。
此函数的主要用途是计算两个日期或日期时间之间相差的年数，例如 `toRelativeYearNum(dt1) - toRelativeYearNum(dt2)`。
**语法**
```sql theme={null}
toRelativeYearNum(date)
```
**参数**
* `date` — 日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回距过去某个固定参考点的年份数。[`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**获取相对年份数**
```sql title=Query theme={null}
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
```
```response title=Response theme={null}
┌─minus(toRela⋯ateTime')))─┐
│ 10 │
└──────────────────────────┘
```
## toSecond
引入版本：v1.1.0
返回 `DateTime` 或 `DateTime64` 值中的秒部分 (0-59) 。
**语法**
```sql theme={null}
toSecond(datetime)
```
**别名**：`SECOND`
**参数**
* `datetime` — 要提取秒数的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回 `datetime` 在当前分钟中的秒数 (0 - 59) 。[`UInt8`](/zh/reference/data-types/int-uint)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│ 30 │
└─────────────────────────────────────────────┘
```
## toStartOfDay
引入版本：v1.1.0
将日期时间向下取整到当天起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**语法**
```sql theme={null}
toStartOfDay(datetime)
```
**参数**
* `datetime` — 要向下取整的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
**返回值**
返回向下取整到当天开始时刻的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**向下取整到当天开始时刻**
```sql title=Query theme={null}
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘
```
## toStartOfFifteenMinutes
引入版本：v1.1.0
将日期时间向下取整到所在十五分钟时间间隔的起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toStartOfFifteenMinutes(datetime)
```
**参数**
* `datetime` — 要取整的日期或日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回取整到最近 15 分钟时间间隔起点的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**示例**
```sql title=Query theme={null}
SELECT
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
行 1:
──────
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:15:00
toStartOfFifteenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:15:00
```
## toStartOfFiveMinutes
Introduced in：v22.6.0
将日期时间向下取整到最近的五分钟时间间隔的起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**Syntax**
```sql theme={null}
toStartOfFiveMinutes(datetime)
```
**别名**: `toStartOfFiveMinute`
**参数**
* `datetime` — 要取整的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回向下取整到最近 5 分钟起始时刻的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**示例**
```sql title=Query theme={null}
SELECT
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
行 1:
──────
toStartOfFiveMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:15:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfFiveMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00
```
## toStartOfHour
引入版本：v1.1.0
将日期时间向下取整到该小时的起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toStartOfHour(datetime)
```
**参数**
* `datetime` — 要取整的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回向下舍入到整点的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**向下舍入到整点**
```sql title=Query theme={null}
SELECT
toStartOfHour(toDateTime('2023-04-21 10:20:30'));
```
```response title=Response theme={null}
┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime │
└─────────────────────┴─────────────────┘
```
## toStartOfISOYear
Introduced in: v1.1.0
将日期或日期时间向下取整到 ISO 年的第一天，该日期可能与普通年份的第一天不同。参见 [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date)。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**Syntax**
```sql theme={null}
toStartOfISOYear(value)
```
**参数**
* `value` — 要向下取整到 ISO 年第一天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期或日期时间所在 ISO 年的第一天。[`Date`](/zh/reference/data-types/date)
**示例**
**向下取整到 ISO 年的第一天**
```sql title=Query theme={null}
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-02 │
└─────────────────────────────────────────────────────┘
```
## toStartOfInterval
引入于：v20.1.0
此函数通过 `toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone])` 语法，对其他 `toStartOf*()` 函数进行了泛化。
例如，
* `toStartOfInterval(t, INTERVAL 1 YEAR)` 返回的结果与 `toStartOfYear(t)` 相同，
* `toStartOfInterval(t, INTERVAL 1 MONTH)` 返回的结果与 `toStartOfMonth(t)` 相同，
* `toStartOfInterval(t, INTERVAL 1 DAY)` 返回的结果与 `toStartOfDay(t)` 相同，
* `toStartOfInterval(t, INTERVAL 15 MINUTE)` 返回的结果与 `toStartOfFifteenMinutes(t)` 相同。
计算是相对于以下特定时间点进行的：
| 时间间隔 | 起始点 |
| ------------------------------------------------ | ------------------- |
| YEAR | 第 0 年 |
| QUARTER | 1900 年第 1 季度 |
| MONTH | 1900 年 1 月 |
| WEEK | 1970 年第 1 周 (01-05) |
| DAY | 1970-01-01 |
| HOUR | (\*) |
| MINUTE | 1970-01-01 00:00:00 |
| SECOND | 1970-01-01 00:00:00 |
| MILLISECOND | 1970-01-01 00:00:00 |
| MICROSECOND | 1970-01-01 00:00:00 |
| NANOSECOND | 1970-01-01 00:00:00 |
| (\*) 小时间隔比较特殊：计算始终以当天的 00:00:00 (午夜) 为基准进行。因此，只有 | |
| 1 到 23 之间的小时值才有意义。 | |
如果指定了 unit `WEEK`，`toStartOfInterval` 会假定每周从星期一开始。请注意，这一行为与函数 `toStartOfWeek` 不同，后者默认每周从星期日开始。
第二种重载分别模拟了 TimescaleDB 的 `time_bucket()` 函数和 PostgreSQL 的 `date_bin()` 函数。
**语法**
```sql theme={null}
toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])
```
**别名**: `time_bucket`, `date_bin`
**参数**
* `value` — 要向下取整的日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `x` — 时间间隔长度的数值。 - `unit` — 时间间隔单位：YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MILLISECOND、MICROSECOND、NANOSECOND。 - `time_zone` — 可选。字符串形式的时区名称。 - `origin` — 可选。计算所用的原点 (仅第二种重载) 。
**返回值**
返回包含输入值的时间间隔起点。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**基本时间间隔取整**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
```
```response title=Response theme={null}
┌─toStartOfInt⋯alMonth(1))─┐
│ 2023-01-01 │
└──────────────────────────┘
```
**使用起点**
```sql title=Query theme={null}
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
```
```response title=Response theme={null}
┌─toStartOfInt⋯14:35:30'))─┐
│ 2023-01-01 14:44:30 │
└──────────────────────────┘
```
## toStartOfMicrosecond
引入版本：v22.6.0
将日期时间向下取整到微秒开始时刻。
**语法**
```sql theme={null}
toStartOfMicrosecond(datetime[, timezone])
```
**参数**
* `datetime` — 日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回值使用的时区。若未指定，则函数使用 `value` 参数的时区。[`String`](/zh/reference/data-types/string)
**返回值**
带有亚微秒部分的输入值 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**不带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
```
**指定时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘
```
## toStartOfMillisecond
引入版本：v22.6.0
将日期时间向下取整到毫秒的开始时刻。
**语法**
```sql theme={null}
toStartOfMillisecond(datetime[, timezone])
```
**参数**
* `datetime` — 日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回值的时区。若未指定，函数将使用 `value` 参数的时区。[`String`](/zh/reference/data-types/string)
**返回值**
带有亚毫秒精度的输入值。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**不带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
```
```response title=Response theme={null}
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
```
**指定时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘
```
## toStartOfMinute
引入版本：v1.1.0
将日期时间向下取整到该分钟的起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toStartOfMinute(datetime)
```
**参数**
* `datetime` — 要进行取整的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回向下取整到该分钟开始时刻的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**向下取整到该分钟开始时刻**
```sql title=Query theme={null}
SELECT
toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfMinute(toDateTime('2023-04-21 10:20:30')): 2023-04-21 10:20:00
toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8)): 2023-04-21 10:20:00
```
## toStartOfMonth
引入版本：v1.1.0
将日期或日期时间向下取整到该月的第一天。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**语法**
```sql theme={null}
toStartOfMonth(value)
```
**参数**
* `value` — 要向下取整到当月第一天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期或日期时间所在月份的第一天。[`Date`](/zh/reference/data-types/date)
**示例**
**向下取整到当月第一天**
```sql title=Query theme={null}
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└───────────────────────────────────────────────────┘
```
## toStartOfNanosecond
引入版本：v22.6.0
将日期时间向下取整到纳秒的起始时刻。
**语法**
```sql theme={null}
toStartOfNanosecond(datetime[, timezone])
```
**参数**
* `datetime` — 日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回值的时区。如果未指定，则该函数使用 `value` 参数的时区。[`String`](/zh/reference/data-types/string)
**返回值**
带纳秒的输入值。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**不带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
```
```response title=Response theme={null}
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
```
**带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘
```
## toStartOfQuarter
Introduced in: v1.1.0
将日期或日期时间向下取整到所在季度的第一天。季度的第一天可能是 1 月 1 日、4 月 1 日、7 月 1 日或 10 月 1 日。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**语法**
```sql theme={null}
toStartOfQuarter(value)
```
**参数**
* `value` — 要向下取整到所在季度第一天的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期或日期时间所在季度的第一天。[`Date`](/zh/reference/data-types/date)
**示例**
**向下取整到所在季度的第一天**
```sql title=Query theme={null}
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-04-01 │
└─────────────────────────────────────────────────────┘
```
## toStartOfSecond
引入版本：v20.5.0
将日期时间向下取整到秒的起始时刻。
**语法**
```sql theme={null}
toStartOfSecond(datetime[, timezone])
```
**参数**
* `datetime` — 要截去子秒部分的日期和时间。[`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回值使用的时区。若未指定，函数将使用参数 `value` 的时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回去除子秒部分后的输入值。[`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**不带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
```
```response title=Response theme={null}
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
```
**带时区的查询**
```sql title=Query theme={null}
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
```
```response title=Response theme={null}
┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│ 2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘
```
## toStartOfTenMinutes
引入版本：v20.1.0
将日期时间向下取整到最近一个十分钟时间间隔的起始时刻。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 进行配置。
**语法**
```sql theme={null}
toStartOfTenMinutes(datetime)
```
**参数**
* `datetime` — 日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回舍入到最近 10 分钟时间间隔起始时刻的日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**示例**
```sql title=Query theme={null}
SELECT
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')),
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')),
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00'))
FORMAT Vertical
```
```response title=Response theme={null}
行 1:
──────
toStartOfTenMinutes(toDateTime('2023-04-21 10:17:00')): 2023-04-21 10:10:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:20:00')): 2023-04-21 10:20:00
toStartOfTenMinutes(toDateTime('2023-04-21 10:23:00')): 2023-04-21 10:20:00
```
## toStartOfWeek
引入版本：v20.1.0
将日期或日期时间向下取整到最近的星期日或星期一。
可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置返回类型。
**语法**
```sql theme={null}
toStartOfWeek(datetime[, mode[, timezone]])
```
**参数**
* `datetime` — 要转换的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `mode` — 按 `toWeek()` 函数中的说明确定每周的第一天。默认值为 `0`。[`UInt8`](/zh/reference/data-types/int-uint)
* `timezone` — 转换时使用的时区。如果未指定，则使用服务器的时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据 `mode`，返回给定日期当天或之前最近的星期日或星期一对应的日期。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32)
**示例**
**向下取整到最近的星期日或星期一**
```sql title=Query theme={null}
SELECT
toStartOfWeek(toDateTime('2023-04-21 10:20:30')), /* 星期五 */
toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* 星期五 */
toStartOfWeek(toDate('2023-04-24')), /* 星期一 */
toStartOfWeek(toDate('2023-04-24'), 1) /* 星期一 */
FORMAT Vertical
```
```response title=Response theme={null}
Row 1:
──────
toStartOfWeek(toDateTime('2023-04-21 10:20:30')): 2023-04-17
toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-17
toStartOfWeek(toDate('2023-04-24')): 2023-04-24
toStartOfWeek(toDate('2023-04-24'), 1): 2023-04-24
```
## toStartOfYear
引入版本：v1.1.0
将日期或日期时间向下取整到当年的第一天。返回值为 `Date` 对象。
返回类型可通过设置 [`enable_extended_results_for_datetime_functions`](/zh/reference/settings/session-settings#enable_extended_results_for_datetime_functions) 来配置。
**语法**
```sql theme={null}
toStartOfYear(value)
```
**参数**
* `value` — 要向下取整的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定日期/时间所在年份的第一天。[`Date`](/zh/reference/data-types/date)
**示例**
**向下取整到该年的第一天**
```sql title=Query theme={null}
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023-01-01 │
└──────────────────────────────────────────────────┘
```
## toTimeWithFixedDate
Introduced in: v1.1.0
提取日期或日期时间中的时间部分。
返回结果是相对于某个固定时间点的偏移量，目前该时间点为 `1970-01-02`，
但这一确切时间点属于实现细节，未来可能会变更。
因此，`toTime` 不应单独使用。
该函数的主要用途是计算两个日期或日期时间之间的时间差，例如 `toTime(dt1) - toTime(dt2)`。
**Syntax**
```sql theme={null}
toTimeWithFixedDate(date[, timezone])
```
**参数**
* `date` — 要转换为时间的日期值。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。返回值使用的时区。[`String`](/zh/reference/data-types/string)
**返回值**
以相对于某个固定时间点的偏移量形式，返回日期或日期时间值中的时间部分 (当前固定时间点为 1970-01-02) 。[`DateTime`](/zh/reference/data-types/datetime)
**示例**
**计算两个日期之间的时间差**
```sql title=Query theme={null}
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
```
```response title=Response theme={null}
┌─result─┬─toTypeName(result)─┐
│ 3600 │ Int32 │
└────────┴────────────────────┘
```
## toTimezone
自 v1.1.0 引入
将 `DateTime` 或 `DateTime64` 转换为指定的时区。
数据的内部值 (Unix 秒数) 不会改变。
只有该值的时区属性和字符串表示形式会发生变化。
**语法**
```sql theme={null}
toTimezone(datetime, timezone)
```
**别名**: `toTimeZone`
**参数**
* `date` — 要转换的值。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 目标时区名称。[`String`](/zh/reference/data-types/string)
**返回值**
返回与输入相同的时间戳，但时区为指定时区。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toDateTime('2019-01-01 00:00:00', 'UTC') AS time_utc,
toTypeName(time_utc) AS type_utc,
toInt32(time_utc) AS int32utc,
toTimezone(time_utc, 'Asia/Yekaterinburg') AS time_yekat,
toTypeName(time_yekat) AS type_yekat,
toInt32(time_yekat) AS int32yekat,
toTimezone(time_utc, 'US/Samoa') AS time_samoa,
toTypeName(time_samoa) AS type_samoa,
toInt32(time_samoa) AS int32samoa
FORMAT Vertical;
```
```response title=Response theme={null}
行 1:
──────
time_utc: 2019-01-01 00:00:00
type_utc: DateTime('UTC')
int32utc: 1546300800
time_yekat: 2019-01-01 05:00:00
type_yekat: DateTime('Asia/Yekaterinburg')
int32yekat: 1546300800
time_samoa: 2018-12-31 13:00:00
type_samoa: DateTime('US/Samoa')
int32samoa: 1546300800
```
## toUTCTimestamp
引入版本：v23.8.0
将日期或日期时间值从某个时区转换为 UTC 时区的时间戳。此函数主要用于兼容 Apache Spark 及类似框架。
**语法**
```sql theme={null}
toUTCTimestamp(datetime, time_zone)
```
**别名**: `to_utc_timestamp`
**参数**
* `datetime` — 日期或日期时间类型的常量值或表达式。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `time_zone` — 表示时区的 String 类型常量值或表达式。[`String`](/zh/reference/data-types/string)
**返回值**
返回 UTC 时区的日期或日期时间。[`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**示例**
**转换为 UTC 时区**
```sql title=Query theme={null}
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
```
```response title=Response theme={null}
┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│ 2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘
```
## toUnixTimestamp
引入版本：v1.1.0
将 `String`、`Date` 或 `DateTime` 转换为 `UInt32` 类型的 Unix 时间戳 (自 `1970-01-01 00:00:00 UTC` 起的秒数) 。
**语法**
```sql theme={null}
toUnixTimestamp(date[, timezone])
```
**参数**
* `date` — 要转换的值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`String`](/zh/reference/data-types/string)
* `timezone` — 可选。转换时使用的时区。如果未指定，则使用服务器时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回 Unix 时间戳。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT
'2017-11-05 08:07:47' AS dt_str,
toUnixTimestamp(dt_str) AS from_str,
toUnixTimestamp(dt_str, 'Asia/Tokyo') AS from_str_tokyo,
toUnixTimestamp(toDateTime(dt_str)) AS from_datetime,
toUnixTimestamp(toDateTime64(dt_str, 0)) AS from_datetime64,
toUnixTimestamp(toDate(dt_str)) AS from_date,
toUnixTimestamp(toDate32(dt_str)) AS from_date32
FORMAT Vertical;
```
```response title=Response theme={null}
行 1:
──────
dt_str: 2017-11-05 08:07:47
from_str: 1509869267
from_str_tokyo: 1509836867
from_datetime: 1509869267
from_datetime64: 1509869267
from_date: 1509840000
from_date32: 1509840000
```
## toWeek
引入版本：v20.1.0
此函数返回 Date 或 DateTime 的周数。`toWeek()` 的双参数形式允许你指定一周是从星期日还是星期一开始，以及返回值范围是 `0` 到 `53`，还是 `1` 到 `53`。
[`toISOWeek()`](#toWeek) 是一个兼容性函数，等价于 `toWeek(date,3)`。
下表说明了 mode 参数的工作方式。
| Mode | 一周的第一天 | 范围 | 第 1 周是指第一个…… |
| ---- | ------ | ---- | ------------- |
| 0 | 星期日 | 0-53 | 在本年内包含一个星期日 |
| 1 | 星期一 | 0-53 | 在本年内包含 4 天或以上 |
| 2 | 星期日 | 1-53 | 在本年内包含一个星期日 |
| 3 | 星期一 | 1-53 | 在本年内包含 4 天或以上 |
| 4 | 星期日 | 0-53 | 在本年内包含 4 天或以上 |
| 5 | 星期一 | 0-53 | 在本年内包含一个星期一 |
| 6 | 星期日 | 1-53 | 在本年内包含 4 天或以上 |
| 7 | 星期一 | 1-53 | 在本年内包含一个星期一 |
| 8 | 星期日 | 1-53 | 包含 1 月 1 日 |
| 9 | 星期一 | 1-53 | 包含 1 月 1 日 |
对于含义为 "在本年内包含 4 天或以上" 的 mode 值，周数按 ISO 8601:1988 编号：
* 如果包含 1 月 1 日的那一周在新的一年中有 4 天或以上，则该周为第 1 周。
* 否则，该周属于上一年的最后一周，而下一周为第 1 周。
对于含义为 "包含 1 月 1 日" 的 mode 值，包含 1 月 1 日的那一周就是第 1 周。
无论该周在新的一年中包含多少天，都不影响这一点，即使只包含一天也是如此。
也就是说，如果 12 月的最后一周包含下一年的 1 月 1 日，那么它将被视为下一年的第 1 周。
第一个参数也可以指定为 [`String`](/zh/reference/data-types/string)，格式需受 [`parseDateTime64BestEffort()`](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort) 支持。支持字符串参数仅是为了兼容 MySQL，因为某些第三方工具依赖这种行为。由于未来对字符串参数的支持可能会取决于新的 MySQL 兼容性设置，而且字符串解析通常较慢，因此建议不要使用这种方式。
**语法**
```sql theme={null}
toWeek(datetime[, mode[, time_zone]])
```
**别名**: `week`
**参数**
* `datetime` — 要获取其周数的日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
* `mode` — 可选。取值范围为 `0` 到 `9`，用于确定每周的第一天以及周数的取值范围。默认值为 `0`。 - `time_zone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
根据指定的模式返回周数。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取不同模式下的周数**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
```
```response title=Response theme={null}
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │ 52 │ 52 │ 1 │
└────────────┴───────┴───────┴───────┘
```
## toYYYYMM
引入版本：v1.1.0
将日期或日期时间转换为包含年份和月份数字 (YYYY \* 100 + MM) 的 `UInt32` 数值。
接受第二个可选的时区参数；如果提供，该时区必须是字符串常量。
此函数与函数 `YYYYMMDDToDate()` 相反。
**语法**
```sql theme={null}
toYYYYMM(datetime[, timezone])
```
**参数**
* `datetime` — 要转换的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。用于转换的时区。如果提供，时区必须为字符串常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 `UInt32` 数值，其中包含年份和月份 (YYYY \* 100 + MM) 。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**将当前日期转换为 YYYYMM 格式**
```sql title=Query theme={null}
SELECT toYYYYMM(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMM(now(), 'US/Eastern')─┐
│ 202303 │
└───────────────────────────────┘
```
## toYYYYMMDD
引入版本：v1.1.0
将日期或日期时间转换为一个包含年、月、日数字 (YYYY \* 10000 + MM \* 100 + DD) 的 `UInt32` 数值。接受第二个可选的时区参数；如果提供，该时区必须是字符串常量。
**语法**
```sql theme={null}
toYYYYMMDD(datetime[, timezone])
```
**参数**
* `datetime` — 要转换的日期或日期时间值。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。转换时使用的时区。如提供，该时区必须是字符串常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 `UInt32` 数值，包含年、月、日 (YYYY \* 10000 + MM \* 100 + DD) 。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**将当前日期转换为 YYYYMMDD 格式**
```sql title=Query theme={null}
SELECT toYYYYMMDD(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│ 20230302 │
└─────────────────────────────────┘
```
## toYYYYMMDDhhmmss
引入版本：v1.1.0
将日期或日期时间转换为 `UInt64` 数值，其中包含年份、月份、日期以及时分秒 (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss) 。
接受第二个可选的时区参数。如果提供，该时区必须是字符串常量。
**语法**
```sql theme={null}
toYYYYMMDDhhmmss(datetime[, timezone])
```
**参数**
* `datetime` — 要转换的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
* `timezone` — 可选。转换时使用的时区。若提供，则时区必须为字符串常量。[`String`](/zh/reference/data-types/string)
**返回值**
返回一个 `UInt64` 数值，包含年、月、日、小时、分钟和秒 (YYYY \* 10000000000 + MM \* 100000000 + DD \* 1000000 + hh \* 10000 + mm \* 100 + ss) 。[`UInt64`](/zh/reference/data-types/int-uint)
**示例**
**将当前日期时间转换为 YYYYMMDDhhmmss 格式**
```sql title=Query theme={null}
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
```
```response title=Response theme={null}
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│ 20230302112209 │
└───────────────────────────────────────┘
```
## toYear
引入版本：v1.1.0
返回 `Date` 或 `DateTime` 值的年份部分 (公元) 。
**语法**
```sql theme={null}
toYear(datetime)
```
**别名**: `YEAR`
**参数**
* `datetime` — 用于提取年份的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`Date32`](/zh/reference/data-types/date32) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
返回给定 Date 或 DateTime 的年份，类型为 [`UInt16`](/zh/reference/data-types/int-uint)
**示例**
**使用示例**
```sql title=Query theme={null}
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
```
```response title=Response theme={null}
┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│ 2023 │
└───────────────────────────────────────────┘
```
## toYearNumSinceEpoch
引入版本：v25.3.0
返回自 1970 年以来经过的年数
**语法**
```sql theme={null}
toYearNumSinceEpoch(date)
```
**参数**
* `date` — 要转换的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64)
**返回值**
正整数
**示例**
**示例**
```sql title=Query theme={null}
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
```
```response title=Response theme={null}
54
```
## toYearWeek
引入版本：v20.1.0
返回日期对应的年份和周数。对于一年中的第一周和最后一周，结果中的年份可能与日期参数中的年份不同。
`mode` 参数的作用方式与 [`toWeek()`](/zh/reference/functions/regular-functions/date-time-functions#toWeek) 的 `mode` 参数相同。
警告：`toYearWeek()` 返回的周数可能与 `toWeek()` 的返回结果不同。`toWeek()` 始终返回给定年份上下文中的周数；而当 `toWeek()` 返回 `0` 时，`toYearWeek()` 会返回对应上一年最后一周的值。请参见下面示例中的 `prev_yearWeek`。
第一个参数也可以指定为 [`String`](/zh/reference/data-types/string)，格式需为 [`parseDateTime64BestEffort()`](/zh/reference/functions/regular-functions/type-conversion-functions#parseDateTime64BestEffort) 支持的格式。支持字符串参数仅仅是为了兼容某些第三方工具所要求的 MySQL 行为。由于未来对字符串参数的支持可能会依赖新的 MySQL 兼容性设置，且字符串解析通常较慢，因此建议不要使用这种方式。
**语法**
```sql theme={null}
toYearWeek(datetime[, mode[, timezone]])
```
**别名**: `yearweek`
**参数**
* `datetime` — 要获取其年份和周数的日期或日期时间。[`Date`](/zh/reference/data-types/date) 或 [`DateTime`](/zh/reference/data-types/datetime)
* `mode` — 可选。取值范围为 `0` 到 `9`，用于确定每周的第一天以及周数的范围。默认值为 `0`。- `timezone` — 可选。时区。[`String`](/zh/reference/data-types/string)
**返回值**
返回年份和周数组合而成的整数值。[`UInt32`](/zh/reference/data-types/int-uint)
**示例**
**获取不同模式下的年份-周数组合**
```sql title=Query theme={null}
SELECT toDate('2016-12-27') AS date, toYearWeek(date) AS yearWeek0, toYearWeek(date,1) AS yearWeek1, toYearWeek(date,9) AS yearWeek9, toYearWeek(toDate('2022-01-01')) AS prev_yearWeek
```
```response title=Response theme={null}
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │ 201652 │ 201652 │ 201701 │ 202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘
```
## today
于 v1.1.0 中引入
返回查询分析时刻的当前日期。等同于 `toDate(now())`。
**语法**
```sql theme={null}
today()
```
**别名**：`curdate`, `current_date`
**参数**
* 无。
**返回值**
返回当前日期 [`Date`](/zh/reference/data-types/date)
**示例**
**用法示例**
```sql title=Query theme={null}
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ today ┃ curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │ 2025-03-03 │
└────────────┴────────────┴──────────────┘
```
**不使用括号的 SQL 标准语法**
```sql title=Query theme={null}
SELECT TODAY, CURDATE,CURRENT_DATE
```
```response title=Response theme={null}
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ TODAY ┃ CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │ 2025-03-04 │
└────────────┴────────────┴──────────────┘
```
## yesterday
引入版本：v1.1.0
不接受任何参数，并返回查询分析过程中某一时刻的昨天日期。
**语法**
```sql theme={null}
yesterday()
```
**参数**
* 无。
**返回值**
返回昨天的日期。[`Date`](/zh/reference/data-types/date)
**示例**
**获取昨天的日期**
```sql title=Query theme={null}
SELECT yesterday();
SELECT today() - 1;
```
```response title=Response theme={null}
┌─yesterday()─┐
│ 2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│ 2025-06-09 │
└───────────────────┘
```