用于处理日期和时间的函数

本节中的大多数函数支持一个可选的时区参数，例如 Europe/Amsterdam。在这种情况下，将使用指定的时区，而不是本地（默认）时区。

示例

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

┌────────────────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 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘

UTCTimestamp

引入版本：v22.11

返回在查询分析时刻的当前日期和时间。该函数是一个常量表达式。

此函数返回的结果与 now('UTC') 相同。它仅为兼容 MySQL 而新增。now 是更推荐的用法。

语法

UTCTimestamp()

别名: UTC_timestamp

参数

• 无。

返回值

返回在查询解析时刻的当前日期和时间。DateTime

示例

获取当前 UTC 时间戳

SELECT UTCTimestamp()

┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘

YYYYMMDDToDate

引入版本：v23.9

将一个包含年、月和日数字的数值转换为 Date。 该函数是函数 toYYYYMMDD() 的反函数。 如果输入不表示一个有效的 Date 值，则输出未定义。

语法

YYYYMMDDToDate(YYYYMMDD)

参数

• YYYYMMDD — 包含年、月和日的数值。(U)Int* 或 Float* 或 Decimal

返回值

根据提供的参数返回一个 Date 类型的值 Date

示例

示例

SELECT YYYYMMDDToDate(20230911);

┌─toYYYYMMDD(20230911)─┐
│           2023-09-11 │
└──────────────────────┘

YYYYMMDDToDate32

引入自：v23.9

将包含年份、月份和日期数字的数值转换为 Date32。 此函数与函数 toYYYYMMDD() 相反。 如果输入不表示一个有效的 Date32 值，则输出是未定义的。

语法

YYYYMMDDToDate32(YYYYMMDD)

参数

• YYYYMMDD — 包含年、月、日的数字。(U)Int* 或 Float* 或 Decimal

返回值

根据提供的参数返回一个 Date32 值 Date32

示例

示例

SELECT YYYYMMDDToDate32(20000507);

┌─YYYYMMDDToDate32(20000507)─┐
│                 2000-05-07 │
└────────────────────────────┘

YYYYMMDDhhmmssToDateTime

自 v23.9 起引入

将包含年、月、日、时、分、秒的数字转换为 DateTime。 此函数与函数 toYYYYMMDDhhmmss() 的作用相反。 如果输入未表示有效的 DateTime 值，则输出是未定义的。

语法

YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])

参数

• YYYYMMDDhhmmss — 包含年份、月份、日、小时、分钟和秒的数字。(U)Int* 或 Float* 或 Decimal
• timezone — 时区名称。String

返回值

根据提供的参数返回 DateTime 类型的值。DateTime

示例

示例

SELECT YYYYMMDDToDateTime(20230911131415);

┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│                           2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘

YYYYMMDDhhmmssToDateTime64

引入于：v23.9

将一个包含年、月、日、时、分、秒的数字转换为 DateTime64。 此函数与函数 toYYYYMMDDhhmmss() 相反。 如果输入不表示有效的 DateTime64 值，则输出结果未定义。

语法

YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])

参数

• YYYYMMDDhhmmss — 包含年、月、日、时、分和秒的数字。(U)Int* 或 Float* 或 Decimal
• precision — 小数部分的精度 (0-9)。UInt8
• timezone — 时区名称。String

返回值

根据提供的参数返回一个 DateTime64 值。DateTime64

示例

示例

SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');

┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│  2023-09-11 13:14:15.000 │
└──────────────────────────┘

addDate

首次引入于：v23.9

将时间间隔添加到指定的日期、日期时间，或它们的字符串编码形式。 如果相加结果超出了该数据类型的取值范围，则结果是未定义的。

语法

addDate(datetime, interval)

参数

• datetime — 要在其基础上添加 interval 的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• interval — 要添加的时间区间。Interval

返回值

返回通过将 interval 加到 datetime 后得到的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64

示例

向日期添加时间区间

SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─addDate(toDa⋯valYear(3))─┐
│               2021-01-01 │
└──────────────────────────┘

addDays

引入自：v1.1 版本

将指定的天数加到日期、日期时间，或字符串编码的日期或日期时间值上。

语法

addDays(datetime, num)

参数

• datetime — 要添加指定天数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要添加的天数值。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 天后的结果。Date 或 Date32 或 DateTime 或 DateTime64

示例

向不同日期类型添加天数

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)

┌─plus(CAST('1⋯valDay(10))─┐
│               1998-06-26 │
└──────────────────────────┘

addHours

引入于：v1.1

将指定的小时数添加到日期、日期时间，或以字符串编码的日期或日期时间。

语法

addHours(datetime, num)

参数

• datetime — 需要增加指定小时数的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要增加的小时数。(U)Int* 或 Float*

返回值

返回在 datetime 上增加 num 小时后的结果，类型为 DateTime 或 DateTime64(3)

示例

向不同日期类型增加小时数

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)

┌─plus(CAST('1⋯alHour(10))─┐
│      1998-06-16 10:00:00 │
└──────────────────────────┘

addInterval

自 v22.11 引入

将一个区间添加到另一个区间或区间元组中。

注意

相同类型的区间会被合并为一个区间。例如，如果传入 toIntervalDay(1) 和 toIntervalDay(2)，则结果为 (3) 而不是 (1,1)。

语法

addInterval(interval_1, interval_2)

参数

• interval_1 — 第一个时间间隔或时间间隔元组。Interval 或 Tuple(Interval)
• interval_2 — 要相加的第二个时间间隔。Interval

返回值

返回时间间隔元组 Tuple(Interval)

示例

时间间隔相加

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)

┌─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 起引入

将指定数量的微秒添加到日期时间值或其字符串编码的日期时间值上。

语法

addMicroseconds(datetime, num)

参数

• datetime — 要增加指定微秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要添加的微秒数。(U)Int* 或 Float*

返回值

返回 date_time 加上 num 微秒后的值，类型为 DateTime64

示例

为不同日期时间类型增加微秒

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

┌─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 语法

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘

addMilliseconds

引入版本：v22.6

将指定数量的毫秒加到带时间的日期，或字符串编码的带时间日期上。

语法

addMilliseconds(datetime, num)

参数

• datetime — 需要增加指定毫秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要增加的毫秒数。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 毫秒后的结果，类型为 DateTime64

示例

为不同的日期时间类型添加毫秒

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

┌─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 语法

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─plus(CAST('1⋯second(10))─┐
│  1998-06-16 00:00:00.010 │
└──────────────────────────┘

addMinutes

引入自：v1.1

为日期、日期时间或其字符串编码形式增加指定的分钟数。

语法

addMinutes(datetime, num)

参数

• datetime — 要添加指定分钟数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要添加的分钟数。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 分钟后的值，类型为 DateTime 或 DateTime64(3)

示例

为不同日期类型添加分钟数

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)

┌─plus(CAST('1⋯Minute(10))─┐
│      1998-06-16 00:10:00 │
└──────────────────────────┘

addMonths

引入于：v1.1

向日期、日期时间或其字符串编码形式添加指定数量的月份。

语法

addMonths(datetime, num)

参数

• datetime — 要增加指定月数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要增加的月份数。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 个月后的值。Date 或 Date32 或 DateTime 或 DateTime64

示例

为不同日期类型增加月份

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)

┌─plus(CAST('1⋯lMonth(10))─┐
│               1999-04-16 │
└──────────────────────────┘

addNanoseconds

自 v22.6 引入

为日期时间值或字符串编码的日期时间值增加指定数量的纳秒。

语法

addNanoseconds(datetime, num)

参数

• datetime — 要在其上添加指定纳秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要添加的纳秒数。(U)Int* 或 Float*

返回值

返回在 datetime 上加上 num 个纳秒后的结果，类型为 DateTime64

示例

为不同的日期时间类型添加纳秒

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

┌─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 语法

SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)

┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘

addQuarters

引入于：v20.1

将指定数量的季度加到日期、日期时间，或以字符串形式表示的日期或日期时间上。

语法

addQuarters(datetime, num)

参数

• datetime — 要在其上添加指定数量季度的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要添加的季度数。(U)Int* 或 Float*

返回值

返回在 datetime 上加上 num 个季度后的结果，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

为不同日期类型添加季度

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)

┌─plus(CAST('1⋯uarter(10))─┐
│               2000-12-16 │
└──────────────────────────┘

addSeconds

自 v1.1 起引入

将指定的秒数加到日期、日期时间，或其字符串表示的日期或日期时间上。

语法

addSeconds(datetime, num)

参数

• datetime — 要增加指定秒数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 需要增加的秒数。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 秒后的结果，为 DateTime 或 DateTime64(3)

示例

对不同日期类型增加秒数

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)

┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│                             1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘

addTupleOfIntervals

引入版本：v22.11

依次向日期或日期时间添加一个间隔元组。

语法

addTupleOfIntervals(datetime, intervals)

参数

• datetime — 要向其添加时间区间的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• intervals — 要添加到 datetime 的时间区间元组。Tuple(Interval)

返回值

返回在 date 上添加了 intervals 后的结果，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

为日期添加一组时间区间元组

WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))

┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│                                                                           2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘

addWeeks

引入版本：v1.1

为日期、日期时间或其字符串形式添加指定数量的周。

语法

addWeeks(datetime, num)

参数

• datetime — 需要添加指定周数的日期或日期时间。可为 Date、Date32、DateTime、DateTime64 或 String
• num — 要添加的周数。(U)Int* 或 Float*

返回值

返回在 datetime 基础上加上 num 周后的值，类型为 Date、Date32、DateTime 或 DateTime64

示例

为不同日期类型添加周数

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)

┌─plus(CAST('1⋯alWeek(10))─┐
│               1998-08-25 │
└──────────────────────────┘

addYears

自 v1.1 引入

将指定的年数添加到日期、日期时间，或字符串形式的日期或日期时间。

语法

addYears(datetime, num)

参数

• datetime — 要向其添加指定年数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要添加的年数。(U)Int* 或 Float*

返回值

返回 datetime 加上 num 年后的值，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

为不同日期类型增加年份

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

┌─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 语法

SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)

┌─plus(CAST('1⋯alYear(10))─┐
│               2008-06-16 │
└──────────────────────────┘

age

引入版本：v23.1

返回 startdate 和 enddate 差值在指定单位下的数值分量。 该差值以 1 纳秒为精度进行计算。

例如，2021-12-29 和 2022-01-01 之间的差值，对于天这一单位是 3 天， 对于月这一单位是 0 个月，对于年这一单位是 0 年。

如需 age 的替代函数，请参见 dateDiff。

语法

age('unit', startdate, enddate[, timezone])

参数

• unit — 结果所使用的时间间隔类型。

Unit	Possible values
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 或 Date32 或 DateTime 或 DateTime64
• enddate — 要从中减去的第二个时间值（被减数）。Date 或 Date32 或 DateTime 或 DateTime64
• timezone — 可选。时区名称。如果指定，则同时应用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 各自的时区。如果二者时区不同，则结果未定义。String

返回值

返回 enddate 与 startdate 之间以 unit 表示的差值。Int32

示例

按小时计算年龄

SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))

┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│                                                                                24 │
└───────────────────────────────────────────────────────────────────────────────────┘

按不同单位计算年龄

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

┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │       3 │         0 │        0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘

changeDay

引入版本：v24.7

修改日期或日期时间的“日”部分。

语法

changeDay(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新的数值。(U)Int*

返回值

返回与 date_or_datetime 类型相同、但已修改日期中“日”部分的值。Date 或 Date32 或 DateTime 或 DateTime64

示例

使用示例

SELECT changeDay('2024-01-31'::DateTime, 15)

2024-01-15 00:00:00

changeHour

自 v24.7 起引入

更改日期或日期时间的小时部分。

语法

changeHour(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回与 date_or_datetime 类型相同的值，其小时部分已被修改。DateTime 或 DateTime64

示例

使用示例

SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)

2024-01-01 05:00:00

changeMinute

引入版本：v24.7

更改 date or date time 值的分钟部分。

语法

changeMinute(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回与 date_or_datetime 类型相同、但分钟部分已修改的值。DateTime 或 DateTime64

示例

用法示例

SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)

2024-01-01 12:45:00

changeMonth

引入版本：v24.7

更改日期或日期时间值的月份部分。

语法

changeMonth(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回与 date_or_datetime 类型相同且月份组件已修改的值。Date 或 Date32 或 DateTime 或 DateTime64

示例

用法示例

SELECT changeMonth('2024-01-01'::DateTime, 12)

2024-12-01 00:00:00

changeSecond

自 v24.7 引入

更改日期或日期时间的秒部分。

语法

changeSecond(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新的秒值。(U)Int*

返回值

返回与 date_or_datetime 类型相同的值，但其中的秒数部分已被修改，即 DateTime 或 DateTime64。

示例

用法示例

SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)

2024-01-01 12:30:15

changeYear

自 v24.7 起引入

更改日期或日期时间的年份部分。

语法

changeYear(date_or_datetime, value)

参数

• date_or_datetime — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新的年份值。(U)Int*

返回值

返回与 date_or_datetime 类型相同的值，但年份部分已被修改。Date 或 Date32 或 DateTime 或 DateTime64

示例

使用示例

SELECT changeYear('2024-01-01'::DateTime, 2023)

2023-01-01 00:00:00

dateDiff

引入版本：v23.4

返回从 startdate 到 enddate 之间跨越的指定 unit 边界的数量。 差值是按相对单位计算的。例如，2021-12-29 和 2022-01-01 之间，对于单位 day（参见 toRelativeDayNum）差值为 3 天， 对于单位 month（参见 toRelativeMonthNum）差值为 1 个月，对于单位 year（参见 toRelativeYearNum）差值为 1 年。

如果指定的单位为 week，则 dateDiff 假定一周从星期一开始计算。 注意，这与函数 toWeek() 的行为不同，后者默认从星期日开始一周。

作为 dateDiff 的替代方案，请参见函数 age。

语法

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 或 Date32 或 DateTime 或 DateTime64
• enddate — 用于相减的第二个时间值（被减数）。Date 或 Date32 或 DateTime 或 DateTime64
• timezone — 可选。时区名称。如果指定，则同时应用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 自身的时区。如果二者时区不同，则结果未指定。String

返回值

返回 enddate 与 startdate 之间以 unit 为单位表示的差值。Int64

示例

按小时计算日期差

SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌─res─┐
│  25 │
└─────┘

以不同单位计算日期差

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

┌──────────e─┬──────────s─┬─day_diff─┬─month_diff─┬─year_diff─┐
│ 2022-01-01 │ 2021-12-29 │        3 │          1 │         1 │
└────────────┴────────────┴──────────┴────────────┴───────────┘

dateName

自 v21.7 起引入

返回日期的指定部分。

可选值：

• 'year'
• 'quarter'
• 'month'
• 'week'
• 'dayofyear'
• 'day'
• 'weekday'
• 'hour'
• 'minute'
• 'second'

语法

dateName(date_part, date[, timezone])

参数

• date_part — 要提取的日期部分。String
• datetime — 日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• timezone — 可选。时区。String

返回值

返回指定的日期部分。String

示例

提取不同的日期部分

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT
    dateName('year', date_value),
    dateName('month', date_value),
    dateName('day', date_value)

┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ April                         │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

dateTrunc

自 v20.8 起引入

将日期和时间值截断到指定的日期部分。

语法

dateTrunc(unit, datetime[, timezone])

别名: DATE_TRUNC

参数

• unit — 用于截断结果的时间单位类型。unit 参数不区分大小写。

  单位	兼容性
  nanosecond	仅与 DateTime64 类型兼容
  microsecond	仅与 DateTime64 类型兼容
  millisecond	仅与 DateTime64 类型兼容
  second
  minute
  hour
  day
  week
  month
  quarter
  year
  String

• datetime — 日期和时间。Date 或 Date32 或 DateTime 或 DateTime64
• timezone — 可选。返回的 datetime 值的时区名称。如果未指定，函数会使用 datetime 参数的时区。String

返回值

返回截断后的日期和时间值。

Unit 参数	datetime 参数	返回类型
Year, Quarter, Month, Week	Date32 or DateTime64 or Date or DateTime	Date32 或 Date
Day, Hour, Minute, Second	Date32, DateTime64, Date, or DateTime	DateTime64 或 DateTime
Millisecond, Microsecond,	Any	DateTime64
Nanosecond		精度为 3、6 或 9

示例

不包含时区的截断

SELECT now(), dateTrunc('hour', now());

┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │       2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘

按指定时区进行截断

SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');

┌───────────────now()─┬─dateTrunc('hour', now(), 'Asia/Istanbul')──┐
│ 2020-09-28 10:46:26 │                        2020-09-28 13:00:00 │
└─────────────────────┴────────────────────────────────────────────┘

formatDateTime

引入版本：v1.1

根据给定的格式字符串格式化日期或带时间的日期。format 是常量表达式，因此你不能为单个结果列使用多种格式。

formatDateTime 使用 MySQL datetime 格式样式，请参阅 mysql docs。

该函数的反向操作是 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
%%	一个 % 符号	%

• 在 ClickHouse v23.4 之前的版本中，如果被格式化的值是 Date、Date32 或 DateTime（不包含秒的小数部分），或精度为 0 的 DateTime64，则 %f 会打印单个零（0）。
• 在 ClickHouse v25.1 之前的版本中，%f 打印的位数与 DateTime64 的 scale 一致，而不是固定的 6 位。
• 在 ClickHouse v23.4 之前的版本中，%M 打印的是分钟（00-59），而不是完整的月份名称（January-December）。

语法

formatDateTime(datetime, format[, timezone])

别名：DATE_FORMAT

参数

• datetime — 要格式化的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• format — 包含替换字段的格式字符串。String
• timezone — 可选。用于格式化时间的时区名称。String

返回值

根据指定格式返回日期和时间值。String

示例

使用年份占位符格式化日期

SELECT formatDateTime(toDate('2010-01-04'), '%g')

┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10                                         │
└────────────────────────────────────────────┘

格式化包含小数秒的 DateTime64

SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')

┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560                                                             │
└─────────────────────────────────────────────────────────────────────┘

带时区的格式化

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

┌──────────────────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

与 formatDateTime 类似，但它使用 Joda 风格而不是 MySQL 风格来格式化日期时间。参见 Joda Time 文档。

此函数的反向操作为 parseDateTimeInJodaSyntax。

通过使用替换字段，可以为结果字符串定义格式模式。

替换字段：

Placeholder	描述	呈现形式	示例
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
'	文本转义符	分隔符
''	单引号	字面量	'

语法

formatDateTimeInJodaSyntax(datetime, format[, timezone])

参数

• datetime — 要格式化的日期或日期时间。DateTime 或 Date 或 Date32 或 DateTime64
• format — 带有 Joda 风格占位符的格式字符串。String
• timezone — 可选。用于格式化时间的时区名称。String

返回值

根据指定格式返回日期和时间值。String

示例

使用 Joda 语法格式化日期时间

SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')

┌─formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')─┐
│ 2010-01-04 12:34:56                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────────┘

fromDaysSinceYearZero

引入版本：v23.11

对于给定的自公元 0000 年 1 月 1 日起经过的天数，返回在ISO 8601 定义的前推公历中的对应日期。

其计算方式与 MySQL 的 FROM_DAYS() FUNCTION 相同。如果结果无法在 Date 类型的取值范围内表示，则结果未定义。

语法

fromDaysSinceYearZero(days)

别名: FROM_DAYS

参数

• days — 自公元 0 年以来经过的天数。UInt32

返回值

返回自公元 0 年以来经过指定天数所对应的日期。Date

示例

将自公元 0 年以来经过的天数转换为日期

SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromDaysSinceYearZero32

引入于：v23.11

对于给定的自公元 0000 年 1 月 1 日起经过的天数，返回在ISO 8601 定义的前推公历中的对应日期。 计算方式与 MySQL 中的 FROM_DAYS() 函数相同。如果结果无法在 Date32 类型的取值范围内表示，则结果未定义。

语法

fromDaysSinceYearZero32(days)

参数

• days — 自公元 0 年起经过的天数。UInt32

返回值

返回与自公元 0 年起经过的指定天数相对应的日期。Date32

示例

将自公元 0 年起的天数转换为日期

SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2

┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

fromModifiedJulianDay

引入于：v21.1

将一个 修正儒略日 数值转换为文本形式为 YYYY-MM-DD 的 前推格里高利历 日期。该函数支持的日数范围为从 -678941 到 2973483（分别表示 0000-01-01 和 9999-12-31）。如果日数超出支持范围，将抛出异常。

语法

fromModifiedJulianDay(day)

参数

• day — 修正儒略日（Modified Julian Day）编号。(U)Int*

返回值

以文本形式返回日期。String

示例

将修正儒略日转换为日期

SELECT fromModifiedJulianDay(58849)

┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01                   │
└──────────────────────────────┘

fromModifiedJulianDayOrNull

自 v21.1 引入

与 fromModifiedJulianDay() 类似，但不会抛出异常，而是返回 NULL。

语法

fromModifiedJulianDayOrNull(day)

参数

• day — 修正儒略日（Modified Julian Day）编号。(U)Int*

返回值

对于有效的 day 参数，返回字符串形式的日期，否则返回 null。Nullable(String)

示例

将修正儒略日转换为日期并处理 null 值

SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- 无效参数，返回 NULL

┌─fromModified⋯Null(58849)─┐
│ 2020-01-01               │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ                     │
└──────────────────────────┘

fromUTCTimestamp

引入版本：v22.1

将 UTC 时区的日期或带时间的日期值转换为指定时区的日期或带时间的日期值。此函数主要用于与 Apache Spark 及类似框架保持兼容。

语法

fromUTCTimestamp(datetime, time_zone)

别名: from_utc_timestamp

参数

• datetime — 一个日期或带时间的常量值，或一个表达式。DateTime 或 DateTime64
• time_zone — 表示时区的 String 类型的常量值或表达式。String

返回值

返回指定时区的 DateTime/DateTime64 值。DateTime 或 DateTime64

示例

将 UTC 时间转换为指定时区的时间

SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')

┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│                                                 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘

fromUnixTimestamp

自 v20.8 起引入

此函数将 Unix 时间戳转换为日历日期和一天中的时间。

可以通过两种方式调用：

• 当传入一个类型为 Integer 的单个参数时，返回类型为 DateTime 的值，即行为类似于 toDateTime。
• 当传入两个或三个参数时，其中第一个参数是类型为 Integer、Date、Date32、DateTime 或 DateTime64 的值，第二个参数是常量格式字符串，第三个参数是可选的常量时区字符串，函数返回类型为 String 的值，即行为类似于 formatDateTime。 在这种情况下，使用 MySQL 的 datetime 格式样式。

语法

fromUnixTimestamp(timestamp)
fromUnixTimestamp(timestamp[, format[, timezone]])

别名: FROM_UNIXTIME

参数

• timestamp — Unix 时间戳或日期 / 日期时间值。(U)Int* 或 Date 或 Date32 或 DateTime 或 DateTime64
• format — 可选。用于输出格式化的常量格式字符串。String
• timezone — 可选。表示时区的常量字符串。String

返回值

以一个参数调用时，返回该时间戳对应的 DateTime；以两个或三个参数调用时，返回 String。DateTime 或 String

示例

将 Unix 时间戳转换为 DateTime

SELECT fromUnixTimestamp(423543535)

┌─fromUnixTimestamp(423543535)─┐
│          1983-06-04 10:58:55 │
└──────────────────────────────┘

按指定格式转换 Unix 时间戳

SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘

fromUnixTimestampInJodaSyntax

引入版本：v23.1

此函数将 Unix 时间戳转换为日历日期和一天中的时间。

可以以两种方式调用：

当传入单个 Integer 类型的参数时，它返回 DateTime 类型的值，即行为与 toDateTime 相同。

当传入两个或三个参数时，其中第一个参数是 Integer、Date、Date32、DateTime 或 DateTime64 类型的值，第二个参数是常量格式字符串，第三个参数是可选的常量时区字符串，函数返回 String 类型的值，即行为与 formatDateTimeInJodaSyntax 相同。在这种情况下，使用 Joda 日期时间格式样式。

语法

fromUnixTimestampInJodaSyntax(timestamp)
fromUnixTimestampInJodaSyntax(timestamp, format[, timezone])

参数

• timestamp — Unix 时间戳或日期/时间值。(U)Int* 或 Date 或 Date32 或 DateTime 或 DateTime64
• format — 可选。使用 Joda 语法进行输出格式化的常量格式字符串。String
• timezone — 可选。常量时区字符串。String

返回值

使用一个参数调用时返回带时间的日期，使用两个或三个参数调用时返回字符串。DateTime 或 String

示例

使用 Joda 格式转换 Unix 时间戳

SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime

┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

makeDate

引入版本：v22.6

通过以下任一方式创建一个 Date 值：

• 年、月和日
• 年以及一年中的第几天

语法

makeDate(年, 月, 日)
makeDate(年, 年积日)

参数

• year — 年份。(U)Int* 或 Float* 或 Decimal
• month — 月份 (1-12)。(U)Int* 或 Float* 或 Decimal
• day — 月份中的日 (1-31)。(U)Int* 或 Float* 或 Decimal
• day_of_year — 一年中的第几天 (1-365)。(U)Int* 或 Float* 或 Decimal

返回值

返回根据给定参数构造的 Date 值 Date

示例

根据年、月、日构造 Date

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

根据年份和一年中的第几天计算日期

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDate32

自 v22.6 起引入

通过以下任一方式创建一个 Date32：

• 年、月和日
• 年和一年中的第几天

语法

makeDate32(year, month, day)
makeDate32(year, day_of_year)

参数

• year — 年份。(U)Int* 或 Float* 或 Decimal
• month — 月份（1-12）。(U)Int* 或 Float* 或 Decimal
• day — 月份中的日（1-31）。(U)Int* 或 Float* 或 Decimal
• day_of_year — 一年中的第几天（1-365）。(U)Int* 或 Float* 或 Decimal

返回值

返回由提供的参数构造的 Date32 值 Date32

示例

根据 year、month、day 构造 Date32

SELECT makeDate(2023, 2, 28) AS date;

┌───────date─┐
│ 2023-02-28 │
└────────────┘

根据年份和一年中的第几天生成 Date32

SELECT makeDate(2023, 42) AS date;

┌───────date─┐
│ 2023-02-11 │
└────────────┘

makeDateTime

引入自：v22.6

根据年份、月份、日、小时、分钟和秒创建一个 DateTime，并可选指定时区。

语法

makeDateTime(year, month, day, hour, minute, second[, timezone])

参数

• year — 年份。(U)Int* 或 Float* 或 Decimal
• month — 月份 (1-12)。(U)Int* 或 Float* 或 Decimal
• day — 日期 (1-31)。(U)Int* 或 Float* 或 Decimal
• hour — 小时 (0-23)。(U)Int* 或 Float* 或 Decimal
• minute — 分钟 (0-59)。(U)Int* 或 Float* 或 Decimal
• second — 秒 (0-59)。(U)Int* 或 Float* 或 Decimal
• timezone — 时区名称。String

返回值

返回一个由提供的参数构造的 DateTime 值 DateTime

示例

根据 year、month、day、hour、minute、second 构造 DateTime

SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;

┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘

makeDateTime64

自 v22.6 起引入

根据 year、month、day、hour、minute、second，以及可选的 fraction、precision 和 timezone 创建一个 DateTime64。

语法

makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])

参数

• year — 年份。(U)Int* 或 Float* 或 Decimal
• month — 月份 (1-12)。(U)Int* 或 Float* 或 Decimal
• day — 日期 (1-31)。(U)Int* 或 Float* 或 Decimal
• hour — 小时 (0-23)。(U)Int* 或 Float* 或 Decimal
• minute — 分钟 (0-59)。(U)Int* 或 Float* 或 Decimal
• second — 秒 (0-59)。(U)Int* 或 Float* 或 Decimal
• fraction — 秒的小数部分。(U)Int* 或 Float* 或 Decimal
• precision — 小数部分的精度 (0-9)。UInt8
• timezone — 时区名称。String

返回值

返回由提供的参数构造的 DateTime64 值。DateTime64

示例

根据 year、month、day、hour、minute、second 构造 DateTime64

SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);

┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│                       2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘

monthName

引入版本：v22.1

从日期或日期时间值中返回月份名称（字符串）。

语法

monthName(datetime)

参数

• datetime — 日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回月份名称。String

示例

从日期获取月份名称

WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)

┌─monthName(date_value)─┐
│ April                 │
└───────────────────────┘

now

自 v1.1 引入

在查询解析阶段返回当前的日期和时间。该函数是一个常量表达式。

语法

now([timezone])

别名: current_timestamp

参数

• timezone — 可选。返回值使用的时区名称。String

返回值

返回当前的日期和时间。DateTime

示例

不带时区的查询

SELECT now()

┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘

按指定时区进行查询

SELECT now('Asia/Istanbul')

┌─now('Asia/Istanbul')─┐
│  2020-10-17 10:42:23 │
└──────────────────────┘

now64

引入版本：v20.1

在查询解析阶段返回当前日期和时间，具有子秒级精度。该函数是一个常量表达式。

语法

now64([scale[, timezone]])

参数

• scale — 可选。时间刻度（精度）：10^-precision 秒。有效范围：[0 : 9]。常用取值为 3（默认，毫秒）、6（微秒）、9（纳秒）。UInt8
• timezone — 可选。返回值的时区名称。String

返回值

返回具有子秒级精度的当前日期和时间。DateTime64

示例

使用默认和自定义精度的查询

SELECT now64(), now64(9, 'Asia/Istanbul')

┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘

nowInBlock

自 v22.8 引入

返回在处理每个数据块时的当前日期和时间。与函数 now 相比，它不是常量表达式，对于长时间运行的查询，在不同数据块中返回的值会不同。

在长时间运行的 INSERT SELECT 查询中使用此函数生成当前时间是合理的。

语法

nowInBlock([timezone])

参数

• timezone — 可选。返回值使用的时区名称。String

返回值

返回在处理每个数据块时的当前日期和时间。DateTime

示例

与 now() 函数的区别

SELECT
    now(),
    nowInBlock(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌───────────────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

以毫秒为单位返回在处理每个数据块时的当前日期和时间。与函数 now64 相比，它不是常量表达式，对于长时间运行的查询，在不同数据块中返回的值会有所不同。

在长时间运行的 INSERT SELECT 查询中，使用此函数来生成当前时间是合理的。

语法

nowInBlock([scale[, timezone]])

参数

• scale — 可选。刻度（精度）：10^-scale 秒。有效范围：[0 : 9]。通常使用的值为：3（默认，毫秒）、6（微秒）、9（纳秒）。UInt8
• timezone — 可选。返回值所使用的时区名称。String

返回值

返回在处理每个数据块时的当前日期和时间，精确到子秒级。DateTime64

示例

与 now64() 函数的区别

SELECT
    now64(),
    nowInBlock64(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock

┌─────────────────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

返回服务器的时区，即 timezone 设置的值。 如果在分布式表的上下文中执行该函数，则会生成一个普通列，其值对应于各个分片。否则，会生成一个常量值。

语法

serverTimeZone()

别名：serverTimeZone

参数

• 无。

返回值

以 String 形式返回服务器时区。

示例

使用示例

SELECT serverTimeZone()

┌─serverTimeZone()─┐
│ UTC              │
└──────────────────┘

subDate

引入于：v23.9

从给定的日期、日期时间或其字符串表示中减去一个时间间隔。 如果减法结果超出了该数据类型的取值范围，则结果是未定义的。

语法

subDate(datetime, interval)

参数

• datetime — 要从中减去 interval 的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• interval — 要减去的时间间隔值。Interval

返回值

返回通过从 datetime 中减去 interval 得到的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64

示例

从日期中减去时间间隔

SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)

┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2015-01-01 │
└──────────────────────────────────────────────────┘

subtractDays

引入于：v1.1

从日期、日期时间或其字符串表示中减去指定的天数。

语法

subtractDays(datetime, num)

参数

• datetime — 要从中减去指定天数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的天数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 天后的结果，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

从不同日期类型减去天数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)

┌─minus(CAST('⋯valDay(10))─┐
│               1998-06-06 │
└──────────────────────────┘

subtractHours

引入于：v1.1

从日期、日期时间值或其字符串表示中减去指定数量的小时。

语法

subtractHours(datetime, num)

参数

• datetime — 要从中减去指定小时数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的小时数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 小时后的值，为 DateTime 或 DateTime64(3)

示例

对不同日期类型减去小时数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)

┌─minus(CAST('⋯alHour(10))─┐
│      1998-06-15 14:00:00 │
└──────────────────────────┘

subtractInterval

自 v22.11 引入

将取相反数的时间间隔加到另一个时间间隔或时间间隔元组上。

注意：相同类型的时间间隔会被合并为一个时间间隔。例如，如果传入 toIntervalDay(2) 和 toIntervalDay(1)，则结果为 (1) 而不是 (2,1)。

语法

subtractInterval(interval_1, interval_2)

参数

• interval_1 — 第一个时间间隔或时间间隔元组。Interval 或 Tuple(Interval)
• interval_2 — 将被取负的第二个时间间隔。Interval

返回值

返回由时间间隔组成的元组 Tuple(T)

示例

时间间隔相减

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);

┌─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 起引入

从日期时间值或其字符串形式中减去指定的微秒数。

语法

subtractMicroseconds(datetime, num)

参数

• datetime — 要从中减去指定微秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要减去的微秒数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 微秒后的值，类型为 DateTime64

示例

从不同日期时间类型减去微秒

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

┌─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 语法

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)

┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘

subtractMilliseconds

引入于：v22.6

从带时间的日期或其字符串形式中减去指定数量的毫秒。

语法

subtractMilliseconds(datetime, num)

参数

• datetime — 要从中减去指定毫秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要减去的毫秒数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 毫秒后的结果，类型为 DateTime64

示例

从不同的日期时间类型中减去毫秒数

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

┌─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 语法

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)

┌─minus(CAST('⋯second(10))─┐
│  1998-06-15 23:59:59.990 │
└──────────────────────────┘

subtractMinutes

自 v1.1 起引入

从日期、日期时间，或其字符串编码形式中减去指定的分钟数。

语法

subtractMinutes(datetime, num)

参数

• datetime — 要从中减去指定分钟数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的分钟数。(U)Int* 或 Float*

返回值

返回从 datetime 中减去 num 分钟后的结果，类型为 DateTime 或 DateTime64(3)

示例

对不同日期类型减去分钟数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)

┌─minus(CAST('⋯Minute(10))─┐
│      1998-06-15 23:50:00 │
└──────────────────────────┘

subtractMonths

引入于：v1.1

从日期、日期时间或字符串表示的日期/日期时间中减去指定数量的月份。

语法

subtractMonths(datetime, num)

参数

• datetime — 要从中减去指定月数的日期或日期时间值。类型为 Date、Date32、DateTime、DateTime64 或 String
• num — 要减去的月数。类型为 (U)Int* 或 Float*

返回值

返回 datetime 减去 num 个月后的结果。类型为 Date、Date32、DateTime、DateTime64

示例

对不同日期类型减去月份

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)

┌─minus(CAST('⋯lMonth(10))─┐
│               1997-08-16 │
└──────────────────────────┘

subtractNanoseconds

自 v20.1 起引入

从带时间的日期值或其字符串表示中减去指定数量的纳秒。

语法

subtractNanoseconds(datetime, num)

参数

• datetime — 要从中减去指定纳秒数的日期时间值。DateTime 或 DateTime64 或 String
• num — 要减去的纳秒数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 纳秒后的结果，类型为 DateTime64

示例

从不同日期时间类型减去纳秒

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

┌─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 语法

SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)

┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘

subtractQuarters

引入版本：v20.1

从日期、日期时间或其字符串形式中减去指定数量的季度。

语法

subtractQuarters(datetime, num)

参数

• datetime — 要从中减去指定季度数的日期或日期时间值。类型为 Date、Date32、DateTime、DateTime64 或 String
• num — 要减去的季度数。类型为 (U)Int* 或 Float*

返回值

返回 datetime 减去 num 个季度后的结果，类型为 Date、Date32、DateTime 或 DateTime64

示例

对不同日期类型减去季度数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)

┌─minus(CAST('1⋯Quarter(10))─┐
│                1996-09-16 │
└───────────────────────────┘

subtractSeconds

引入于：v1.1

从日期、日期时间或字符串编码的日期/日期时间中减去指定的秒数。

语法

subtractSeconds(datetime, num)

参数

• datetime — 要从中减去指定秒数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的秒数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 秒后的结果，类型为 DateTime 或 DateTime64(3)

示例

从不同日期类型减去秒数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)

┌─minus(CAST('⋯Second(10))─┐
│      1998-06-15 23:59:50 │
└──────────────────────────┘

subtractTupleOfIntervals

引入版本：v22.11

从日期或日期时间值中依次减去一个时间间隔元组。

语法

subtractTupleOfIntervals(datetime, intervals)

参数

• datetime — 要从中减去时间间隔的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• intervals — 要从 datetime 中减去的时间间隔元组。Tuple(Interval)

返回值

返回减去 intervals 之后的 date 值，可为 Date 或 Date32 或 DateTime 或 DateTime64

示例

从日期中减去时间间隔元组

WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))

┌─subtractTupl⋯alYear(1)))─┐
│               2016-12-31 │
└──────────────────────────┘

subtractWeeks

引入版本：v1.1

从日期、日期时间或其字符串形式中减去指定周数。

语法

subtractWeeks(datetime, num)

参数

• datetime — 要从中减去指定周数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的周数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 周后的结果，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

对不同日期类型减去指定周数

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

┌─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 语法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)

┌─minus(CAST('⋯alWeek(10))─┐
│               1998-04-07 │
└──────────────────────────┘

subtractYears

引入于：v1.1

从日期、日期时间或其字符串表示中减去指定数量的年份。

语法

subtractYears(datetime, num)

参数

• datetime — 要从中减去指定年数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的年数。(U)Int* 或 Float*

返回值

返回 datetime 减去 num 年后的结果，类型为 Date 或 Date32 或 DateTime 或 DateTime64

示例

对不同日期类型减去年数

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

┌─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 语法的替代写法

SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)

┌─minus(CAST('⋯alYear(10))─┐
│               1988-06-16 │
└──────────────────────────┘

timeDiff

自 v23.4 起引入

返回两个日期或日期时间值之间的差值（以秒为单位）。 差值的计算方式为 enddate - startdate。

此函数等价于 dateDiff('second', startdate, enddate)。

若要按其他单位（小时、天、月等）计算时间差，请改用 dateDiff 函数。

语法

timeDiff(startdate, enddate)

参数

• startdate — 要减去的第一个时间值（减数）。Date 或 Date32 或 DateTime 或 DateTime64
• enddate — 被减去的第二个时间值（被减数）。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回 enddate 与 startdate 之间的差值（以秒为单位）。Int64

示例

以秒计算时间差

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res

┌───res─┐
│ 90000 │
└───────┘

计算时间差并换算为小时

SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours

┌─hours─┐
│    25 │
└───────┘

等同于以秒为单位的 dateDiff 函数

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

┌─time_diff_result─┬─date_diff_result─┐
│           259200 │           259200 │
└──────────────────┴──────────────────┘

timeSlot

引入版本：v1.1

将时间取整到以半小时为长度的时间区间起始时刻。

注意

尽管该函数可以接受扩展类型 Date32 和 DateTime64 作为参数， 但如果传入超出正常范围的时间（Date 的年份范围为 1970 到 2149 / DateTime 的年份到 2106），将会产生错误的结果。

语法

timeSlot(time[, time_zone])

参数

• time — 要舍入的时间，将被舍入到以半小时为长度的时间区间的起始时刻。DateTime 或 Date32 或 DateTime64
• time_zone — 可选。表示时区的 String 类型常量值或表达式。String

返回值

返回舍入到以半小时为长度的时间区间起始时刻的时间值。DateTime

示例

将时间舍入到半小时区间

SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))

┌─timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))─┐
│                                2000-01-02 03:00:00 │
└────────────────────────────────────────────────────┘

timeSlots

引入版本：v1.1

对于一个从 StartTime 开始并持续 Duration 秒的时间区间，该函数返回一个时间点数组，这些时间点是将该区间内的时刻向下取整到以秒为单位的 Size 所得到的各个点。Size 是一个可选参数，默认值为 1800（30 分钟）。

例如，在搜索对应会话中的页面浏览（pageviews）时会用到它。

对于 DateTime64，返回值的精度（scale）可能与 StartTime 的精度不同，将采用所有传入参数中最高的精度。

语法

timeSlots(StartTime, Duration[, Size])

参数

• StartTime — 区间的起始时间。DateTime 或 DateTime64
• Duration — 区间的时长（以秒为单位）。UInt32 或 DateTime64
• Size — 可选。时间片段的大小（以秒为单位），默认值为 1800（30 分钟）。UInt32 或 DateTime64

返回值

返回一个 DateTime/DateTime64 数组（返回类型与 StartTime 的类型一致）。对于 DateTime64，返回值的小数位精度可以不同于 StartTime 的小数位精度 —— 会取所有传入参数中最高的精度。Array(DateTime) 或 Array(DateTime64)

示例

为一个时间区间生成时间片段

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))

┌─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 版本引入

将第一个参数 expr 转换为 DateTime64(6) 类型。 如果提供了第二个参数 expr_time，则会将指定时间加到转换后的值上。

语法

timestamp(expr[, expr_time])

参数

• expr — 日期或日期时间值。String
• expr_time — 可选。要叠加到转换结果上的时间值。String

返回值

返回 expr 转换后的值，或在 expr 上叠加时间后的值，类型为 DateTime64(6)

示例

将日期字符串转换为 DateTime64(6)

SELECT timestamp('2023-12-31') AS ts;

┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘

在日期字符串中添加时间

SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;

┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘

timezone

自 v21.4 引入

返回当前会话的时区名称，或将时区偏移量或名称转换为规范的时区名称。

语法

timezone()

别名：timeZone

参数

• 无。

返回值

返回规范时区名称，类型为 String

示例

用法示例

SELECT timezone()

┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘

timezoneOf

自 v21.4 起引入

返回 DateTime 或 DateTime64 值所在的时区名称。

语法

timeZoneOf(datetime)

别名: timeZoneOf

参数

• datetime — 类型为 DateTime 或 DateTime64 的值。
• timezone — 可选。要将 datetime 值转换到的目标时区名称。String

返回值

返回 datetime 的时区名称，类型为 String

示例

用法示例

SELECT timezoneOf(now());

┌─timezoneOf(now())─┐
│ Europe/Amsterdam  │
└───────────────────┘

timezoneOffset

引入版本：v21.6

返回相对于 UTC 的时区偏移量，单位为秒。 在指定日期和时间下，该函数会考虑夏令时以及历史时区变更。

语法

timeZoneOffset(datetime)

别名：timeZoneOffset

参数

• datetime — 要获取其时区偏移量的 DateTime 值。DateTime 或 DateTime64

返回值

返回相对于 UTC 的偏移量（以秒为单位），类型为 Int32

示例

用法示例

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;

┌────────────────Time─┬─Type─────────────────────────┬─Offset_in_seconds─┬─Offset_in_hours─┐
│ 2021-04-21 10:20:30 │ DateTime('America/New_York') │            -14400 │              -4 │
└─────────────────────┴──────────────────────────────┴───────────────────┴─────────────────┘

toDayOfMonth

引入版本：v1.1

返回 Date 或 DateTime 值所在月份中的“日”（1-31）。

语法

toDayOfMonth(datetime)

别名: DAY, DAYOFMONTH

参数

• datetime — 要从中获取所在月份中的第几天的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间在其所在月份中的第几天 UInt8

示例

用法示例

SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                              21 │
└─────────────────────────────────────────────────┘

toDayOfWeek

引入于：v1.1

返回 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

语法

toDayOfWeek(datetime[, mode[, timezone]])

别名: DAYOFWEEK

参数

• datetime — 要获取其星期几的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64
• mode — 可选。指定周模式的整数（0-3）。如果省略，默认为 0。UInt8
• timezone — 可选。用于转换的时区。String

返回值

返回给定 Date 或 DateTime 所对应的星期几，返回类型为 UInt8

示例

使用示例

-- 以下日期为 2023 年 4 月 21 日，当天是星期五：
SELECT
    toDayOfWeek(toDateTime('2023-04-21')),
    toDayOfWeek(toDateTime('2023-04-21'), 1)

┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│                                     5 │                                        4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘

toDayOfYear

自 v18.4 起可用

返回 Date 或 DateTime 值在其所在年份中的第几天（1-366）。

语法

toDayOfYear(datetime)

别名：DAYOFYEAR

参数

• datetime — 要获取其在一年中是第几天的日期或日期时间值。类型为 Date、Date32、DateTime 或 DateTime64

返回值

返回给定 Date 或 DateTime 在一年中的天数序号，类型为 UInt16

示例

用法示例

SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                            111 │
└────────────────────────────────────────────────┘

toDaysSinceYearZero

引入版本：v23.9

对于给定日期，返回自公元 0000 年 1 月 1 日以来已经过去的天数，按照 ISO 8601 定义的前推格里高利历（proleptic Gregorian calendar）进行计算。

该计算方式与 MySQL 的 TO_DAYS 函数相同。

语法

toDaysSinceYearZero(date[, time_zone])

别名: TO_DAYS

参数

• date — 用于计算自日期 0000-01-01 起已过去天数的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
• time_zone — 时区。String

返回值

返回自日期 0000-01-01 起已过去的天数。UInt32

示例

计算自年份 0 起的天数

SELECT toDaysSinceYearZero(toDate('2023-09-08'))

┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│                                     713569 │
└────────────────────────────────────────────┘

toHour

自 v1.1 版本引入

返回 DateTime 或 DateTime64 值中的小时部分（0-23）。

语法

toHour(datetime)

别名: HOUR

参数

• datetime — 要从中获取小时数的日期时间值。DateTime 或 DateTime64

返回值

返回 datetime 的小时数（0-23）。UInt8

示例

用法示例

SELECT toHour(toDateTime('2023-04-21 10:20:30'))

┌─toHour(toDateTime('2023-04-21 10:20:30'))─┐
│                                        10 │
└───────────────────────────────────────────┘

toISOWeek

引入版本：v20.1

返回日期或带时间的日期对应的 ISO 周编号。

这是一个兼容性函数，与 toWeek(date, 3) 等价。 ISO 周从星期一开始计算，一年中的第一周是包含 1 月 4 日的那一周。 根据 ISO 8601 标准，周编号的范围是 1 到 53。

请注意，某些接近年初或年末的日期可能会返回前一年或下一年的周编号。例如， 2025 年 12 月 29 日会返回第 1 周，因为它属于包含 2026 年 1 月 4 日的第一周。

语法

toISOWeek(datetime[, timezone])

参数

• datetime — 要获取 ISO 周编号的日期或带时间的日期。Date 或 DateTime 或 Date32 或 DateTime64
• timezone — 可选。时区。String

返回值

返回符合 ISO 8601 标准的 ISO 周编号。返回 1 到 53 之间的数字。UInt8

示例

获取 ISO 周编号

SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek

┌───────date─┬─isoWeek─┐
│ 2016-12-27 │      52 │
└────────────┴─────────┘

ISO 周所属的年份可能不同

SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year

┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │       1 │ 2025 │
└────────────┴─────────┴──────┘

toISOYear

引入于：v18.4

将日期或日期时间转换为 ISO 年份。

语法

toISOYear(datetime)

参数

• datetime — 日期或日期时间类型的值。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回将输入值转换得到的 ISO 年份编号。UInt16

示例

从日期值获取 ISO 年份

SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2

┌─week1─┬─week2─┐
│    40 │    40 │
└───────┴───────┘

toLastDayOfMonth

自 v1.1 引入

将日期或日期时间向上取整到所在月份的最后一天。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toLastDayOfMonth(value)

别名：LAST_DAY

参数

• value — 要向上取整到所在月份最后一天的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或带时间的日期所在月份最后一天的日期。Date

示例

向上取整到所在月份的最后一天

SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-30 │
└─────────────────────────────────────────────────────┘

toLastDayOfWeek

引入版本：v23.5

将日期或日期时间向上取整到最近的周六或周日。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toLastDayOfWeek(datetime[, mode[, timezone]])

参数

• datetime — 要转换的日期或带时间的日期。Date 或 DateTime 或 Date32 或 DateTime64
• mode — 按 toWeek() 函数中的说明确定一周的第一天。默认值为 0。UInt8
• timezone — 可选。用于转换的时区。如果未指定，则使用服务器的时区。String

返回值

根据 mode 的取值，返回给定日期当天或之后距离最近的一个周六或周日的日期。Date 或 Date32 或 DateTime 或 DateTime64

示例

向上取整到最近的周六或周日

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

行 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 起引入

返回 DateTime 或 DateTime64 值的毫秒部分（0-999）。

语法

toMillisecond(datetime)

别名：MILLISECOND

参数

• datetime — 要从中提取毫秒值的日期时间。DateTime 或 DateTime64

返回值

返回 datetime 所在分钟中的毫秒（0 - 59）。UInt16

示例

使用示例

SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));

┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│                                                        456 │
└────────────────────────────────────────────────────────────┘

toMinute

引入于：v1.1

返回 Date 或 DateTime 值的分钟部分（0-59）。

语法

toMinute(datetime)

别名: MINUTE

参数

• datetime — 要从中获取分钟的日期时间。DateTime 或 DateTime64

返回值

返回 datetime 中小时的分钟数（0 - 59）。UInt8

示例

用法示例

SELECT toMinute(toDateTime('2023-04-21 10:20:30'))

┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│                                          20 │
└─────────────────────────────────────────────┘

toModifiedJulianDay

引入于：v21.1

将以文本形式 YYYY-MM-DD 表示的前推格里高利历日期转换为 Int32 类型的修正儒略日数值。该函数支持的日期范围为 0000-01-01 到 9999-12-31。如果参数无法解析为日期，或者日期无效，则会抛出异常。

语法

toModifiedJulianDay(date)

参数

• date — 以字符串形式表示的日期。String 或 FixedString

返回值

返回修正儒略日编号。Int32

示例

将日期转换为修正儒略日编号

SELECT toModifiedJulianDay('2020-01-01')

┌─toModifiedJulianDay('2020-01-01')─┐
│                             58849 │
└───────────────────────────────────┘

toModifiedJulianDayOrNull

自 v21.1 引入

与 toModifiedJulianDay() 类似，但不会抛出异常，而是返回 NULL。

语法

toModifiedJulianDayOrNull(date)

参数

• date — 文本形式的日期。String 或 FixedString

返回值

对于有效的 date，返回对应的修正儒略日编号，否则返回 null。Nullable(Int32)

示例

将日期转换为修正儒略日并处理 null 值

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- 无效日期，返回 NULL

┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

toMonday

引入于：v1.1

将日期或带时间的日期向下取整到同一周的周一。返回日期。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toMonday(value)

参数

• value — 要向下取整到所在周星期一的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或带时间日期所在周的星期一这一天的日期值。Date

示例

向下取整到所在周的星期一

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- 星期五
toMonday(toDate('2023-04-24'));              -- 已经是星期一

┌─toMonday(toDateTime('2023-04-21 10:20:30'))─┬─toMonday(toDate('2023-04-24'))─┐
│                                  2023-04-17 │                     2023-04-24 │
└─────────────────────────────────────────────┴────────────────────────────────┘

toMonth

引入于：v1.1

返回 Date 或 DateTime 值的月份部分（1-12）。

语法

toMonth(datetime)

别名：MONTH

参数

• datetime — 要获取月份的日期或日期时间。类型为 Date、Date32、DateTime 或 DateTime64

返回值

返回给定日期/时间对应的月份，类型为 UInt8

示例

用法示例

SELECT toMonth(toDateTime('2023-04-21 10:20:30'))

┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          4 │
└────────────────────────────────────────────┘

toMonthNumSinceEpoch

引入版本：v25.3

返回自 1970 年以来已过去的月份数

语法

toMonthNumSinceEpoch(date)

参数

• date — 日期或日期时间值。Date 或 DateTime 或 DateTime64

返回值

正整数

示例

示例

SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))

657

toQuarter

自 v1.1 起提供

对给定的 Date 或 DateTime 值，返回其对应的季度（1-4）。

语法

toQuarter(datetime)

别名：QUARTER

参数

• datetime — 要获取其所属季度的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间在一年中的季度 UInt8

示例

用法示例

SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                            2 │
└──────────────────────────────────────────────┘

toRelativeDayNum

引入版本：v1.1

将日期或日期时间转换为自某个固定过去时间点以来经过的天数。 该时间点的确切值属于实现细节，因此不建议将此函数单独使用。 该函数的主要用途是计算两个日期或日期时间之间相差的天数，例如：toRelativeDayNum(dt1) - toRelativeDayNum(dt2)。

语法

toRelativeDayNum(date)

参数

• date — 日期或日期时间值。Date 或 DateTime 或 DateTime64

返回值

返回自过去某个固定参考时间点以来的天数。UInt32

示例

获取相对天数序号

SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))

┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

toRelativeHourNum

引入版本：v1.1

将日期或带时间的日期转换为自过去某个固定时间点以来经过的小时数。 该具体时间点属于实现细节，因此不建议单独使用此函数。 该函数的主要用途是计算两个日期或带时间的日期之间的小时差，例如：toRelativeHourNum(dt1) - toRelativeHourNum(dt2)。

语法

toRelativeHourNum(date)

参数

• date — 日期或带时间的日期。Date 或 DateTime 或 DateTime64

返回值

返回距离过去某个固定参考点的小时数。UInt32

示例

获取相对小时数

SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference

┌─hours_difference─┐
│               12 │
└──────────────────┘

toRelativeMinuteNum

引入于：v1.1

将日期或日期时间值转换为自某个过去的固定时间点以来经过的分钟数。 该时间点的确切值属于实现细节，因此不应将此函数单独使用。 该函数的主要用途是计算两个日期或日期时间值之间相差的分钟数，例如：toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)。

语法

toRelativeMinuteNum(date)

参数

• date — 日期或带时间的日期。Date 或 DateTime 或 DateTime64

返回值

返回自过去某个固定参考时间点以来经过的分钟数。UInt32

示例

获取相对分钟编号

SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference

┌─minutes_difference─┐
│                 30 │
└────────────────────┘

toRelativeMonthNum

引入版本：v1.1

将日期或带时间的日期转换为自过去某个固定时间点以来经过的月份数。 该具体时间点属于实现细节，因此不建议单独使用此函数。 该函数的主要用途是计算两个日期或带时间的日期之间相差的月份数，例如：toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)。

语法

toRelativeMonthNum(date)

参数

• date — 日期或带时间的日期。Date 或 DateTime 或 DateTime64

返回值

返回自过去某个固定参考点起算的月份数。UInt32

示例

获取相对月份序号

SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference

┌─months_difference─┐
│                 3 │
└───────────────────┘

toRelativeQuarterNum

引入版本：v1.1

将日期或日期时间转换为自某个固定过去时间点以来已经过去的季度数。 该具体时间点属于实现细节，因此不建议单独使用此函数。 该函数的主要用途是计算两个日期或日期时间之间相差的季度数，例如：toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)。

语法

toRelativeQuarterNum(date)

参数

• date — 日期或包含时间的日期值。Date 或 DateTime 或 DateTime64

返回值

返回自过去某个固定参考点起计算的季度数。UInt32

示例

获取相对季度序号

SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference

┌─quarters_difference─┐
│                   1 │
└─────────────────────┘

toRelativeSecondNum

引入于：v1.1

将日期或日期时间转换为自某个固定的历史时间点以来经过的秒数。 该具体时间点属于实现细节，因此不建议将此函数单独使用。 此函数的主要用途是计算两个日期或日期时间之间的秒数差，例如：toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)。

语法

toRelativeSecondNum(date)

参数

• date — 日期或带时间的日期。Date 或 DateTime 或 DateTime64

返回值

返回自过去固定参考点以来的秒数。UInt32

示例

获取相对秒数

SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference

┌─seconds_difference─┐
│                 60 │
└────────────────────┘

toRelativeWeekNum

引入版本：v1.1

将日期或带时间的日期转换为自某个固定的过去时间点起所经过的周数。 这个具体时间点属于实现细节，因此不建议单独使用此函数。 该函数的主要用途是计算两个日期或带时间的日期之间相差的周数，例如：toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)。

语法

toRelativeWeekNum(date)

参数

• date — 日期或日期时间值。Date 或 DateTime 或 DateTime64

返回值

返回从过去某个固定参考点开始计算的周数。UInt32

示例

获取相对周数

SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference

┌─weeks_difference─┐
│                1 │
└──────────────────┘

toRelativeYearNum

引入自：v1.1

将日期或日期时间转换为自过去某个固定时间点以来经过的年份数。 该固定时间点属于实现细节，因此不建议单独使用该函数。 该函数主要用于计算两个日期或日期时间之间相差的年份数，例如：toRelativeYearNum(dt1) - toRelativeYearNum(dt2)。

语法

toRelativeYearNum(date)

参数

• date — 日期或带时间的日期。Date 或 DateTime 或 DateTime64

返回值

返回自某个固定历史参考点以来的年份数。UInt16

示例

获取相对年份数值

SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)

┌─minus(toRela⋯ateTime')))─┐
│                       10 │
└──────────────────────────┘

toSecond

引入于：v1.1

返回 DateTime 或 DateTime64 值中的秒部分（0-59）。

语法

toSecond(datetime)

别名: SECOND

参数

• datetime — 要从中获取秒数的日期时间值。DateTime 或 DateTime64

返回值

返回 datetime 所在分钟中的秒数（0 - 59）。UInt8

示例

用法示例

SELECT toSecond(toDateTime('2023-04-21 10:20:30'))

┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│                                          30 │
└─────────────────────────────────────────────┘

toStartOfDay

自 v1.1 引入

将带时间的日期向下取整到当天的开始时间。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfDay(datetime)

参数

• datetime — 要舍入的日期或日期时间。Date 或 DateTime

返回值

返回向下取整到当天起始时刻的日期时间值。Date 或 DateTime 或 Date32 或 DateTime64

示例

向下取整到当天起始时刻

SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│                             2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘

toStartOfFifteenMinutes

引入版本：v1.1

将日期时间向下取整到所在十五分钟时间区间的起始时刻。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfFifteenMinutes(datetime)

参数

• datetime — 要进行取整的日期或带时间的日期。DateTime 或 DateTime64

返回值

返回将时间向最近的十五分钟区间起始时刻取整后的日期时间值，类型为 DateTime 或 DateTime64

示例

示例

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

行 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

自 v22.6 引入

将日期时间值向下取整到距离其最近的五分钟区间的起始时刻。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfFiveMinutes(datetime)

别名: toStartOfFiveMinute

参数

• datetime — 需要进行取整的日期时间。DateTime 或 DateTime64

返回值

返回已取整到最近的 5 分钟区间起始时刻的日期时间值，DateTime 或 DateTime64

示例

示例

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

行 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 版本引入

将日期时间向下取整到所在小时的起始时刻。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfHour(datetime)

参数

• datetime — 要取整的日期时间值。DateTime 或 DateTime64

返回值

返回向下取整到整点开始时刻的日期时间值。DateTime 或 DateTime64

示例

向下取整到整点开始时刻

SELECT
    toStartOfHour(toDateTime('2023-04-21 10:20:30'));

┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime        │
└─────────────────────┴─────────────────┘

toStartOfISOYear

自 v1.1 引入

将日期或日期时间向下取整到 ISO 年的第一天，该日期可能与公历年的第一天不同。参见 ISO week date。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfISOYear(value)

参数

• value — 需要向下取整到对应 ISO 年的第一天的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或带时间的日期所属 ISO 年的第一天。Date

示例

向下取整到 ISO 年的第一天

SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-01-02 │
└─────────────────────────────────────────────────────┘

toStartOfInterval

引入版本：v20.1

此函数通过 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) 相同。

计算是相对于特定时间点进行的：

Interval	Start
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（午夜）进行。

如果指定的单位为 WEEK，toStartOfInterval 假定星期从周一开始。请注意，此行为不同于函数 toStartOfWeek，后者默认从周日开始计周。

第二个重载形式同时模拟了 TimescaleDB 的 time_bucket() 函数以及 PostgreSQL 的 date_bin() 函数。

语法

toStartOfInterval(value, INTERVAL x unit[, time_zone])
toStartOfInterval(value, INTERVAL x unit[, origin[, time_zone]])

别名: time_bucket, date_bin

参数

• value — 要向下取整的日期或日期时间值。Date 或 DateTime 或 DateTime64
• x — 间隔长度数值。
  • unit — 间隔单位：YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND、MILLISECOND、MICROSECOND、NANOSECOND。
  • time_zone — 可选。时区名称，字符串类型。
  • origin — 可选。用于计算的起始时间点（仅适用于第二个重载）。

返回值

返回包含输入值的时间间隔的起始时间。DateTime

示例

基本间隔取整

SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)

┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘

使用原点

SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))

┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

toStartOfMicrosecond

引入版本：v22.6

将日期时间值向下取整到所在微秒的起始时刻。

语法

toStartOfMicrosecond(datetime[, timezone])

参数

• datetime — 日期和时间。DateTime64
• timezone — 可选。返回值所使用的时区。如果未指定，函数会使用 value 参数的时区。String

返回值

带有亚微秒精度的输入值 DateTime64

示例

未指定时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);

┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘

带时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');

┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

toStartOfMillisecond

自 v22.6 起引入

将日期时间值向下取整到所在毫秒的起始时刻。

语法

toStartOfMillisecond(datetime[, timezone])

参数

• datetime — 日期和时间。DateTime64
• timezone — 可选。返回值所使用的时区。如果未指定，函数会使用 value 参数的时区。String

返回值

带有亚毫秒精度的输入值。DateTime64

示例

不带时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);

┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘

带时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');

┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

toStartOfMinute

自 v1.1 引入

将日期时间值向下取整到该分钟的起始时刻。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfMinute(datetime)

参数

• datetime — 要进行取整的日期时间。DateTime 或 DateTime64

返回值

返回将日期时间向下取整到该分钟起始时刻的结果。DateTime 或 DateTime64

示例

向下取整到该分钟的起始时刻

SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical

行 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

将日期或日期时间向下取整为其所在月份的第一天。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfMonth(value)

参数

• value — 要向下取整到所在月份第一天的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或日期时间值所在月份的第一天。Date

示例

向下取整到所在月份的第一天

SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                        2023-04-01 │
└───────────────────────────────────────────────────┘

toStartOfNanosecond

自 v22.6 引入

将日期时间向下取整到纳秒的起始时刻。

语法

toStartOfNanosecond(datetime[, timezone])

参数

• datetime — 日期和时间。DateTime64
• timezone — 可选。返回值使用的时区。如果未指定，函数会使用 value 参数的时区。String

返回值

具有纳秒精度的输入值。DateTime64

示例

未指定时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);

┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘

使用时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');

┌─toStartOfNanosecond(dt64, 'Asia/Istanbul')─┐
│              2020-01-01 12:20:30.999999999 │
└────────────────────────────────────────────┘

toStartOfQuarter

自 v1.1 起引入

将日期或带时间的日期向下取整到其所在季度的第一天。季度的第一天为 1 月 1 日、4 月 1 日、7 月 1 日或 10 月 1 日。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfQuarter(value)

参数

• value — 要向下舍入到其所在季度第一天的日期或带时间的日期值。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或带时间的日期值所在季度的第一天。Date

示例

向下舍入到该季度的第一天

SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-01 │
└─────────────────────────────────────────────────────┘

toStartOfSecond

首次引入：v20.5

将日期时间值向下取整到该秒的起始时刻。

语法

toStartOfSecond(datetime[, timezone])

参数

• datetime — 要截断其子秒部分的日期时间值。DateTime64
• timezone — 可选。返回值所使用的时区。如果未指定，函数将使用 value 参数的时区。String

返回值

返回移除子秒部分后的输入值。DateTime64

示例

不带时区的查询

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);

┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘

包含时区信息的查询

WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');

┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

toStartOfTenMinutes

引入版本：v20.1

将带时间的日期向下舍入到最近的 10 分钟区间的起始时间点。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfTenMinutes(datetime)

参数

• datetime — 带时间的日期时间值。DateTime 或 DateTime64

返回值

返回向最近的 10 分钟区间起始时刻取整的日期时间值，类型为 DateTime 或 DateTime64

示例

示例

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

行 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

将日期或日期时间向下取整到所在周的最近一个星期日或星期一。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfWeek(datetime[, mode[, timezone]])

参数

• datetime — 要转换的日期或带时间的日期。Date 或 DateTime 或 Date32 或 DateTime64
• mode — 按照 toWeek() 函数中的说明确定一周的第一天。默认值为 0。UInt8
• timezone — 用于转换的时区。如果未指定，则使用服务器的时区。String

返回值

根据 mode 的取值，返回距离给定日期最近且不晚于该日期的周日或周一的日期值。Date 或 Date32 或 DateTime 或 DateTime64

示例

向下舍入到最近的周日或周一

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

行 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

将日期或带时间的日期向下舍入到所在年份的第一天。以 Date 对象的形式返回该日期。

注意

可以通过设置 enable_extended_results_for_datetime_functions 来配置返回类型。

语法

toStartOfYear(value)

参数

• value — 要向下取整的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间所在年份的第一天，类型为 Date

示例

向下取整到该年第一天

SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))

┌─toStartOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                       2023-01-01 │
└──────────────────────────────────────────────────┘

toTimeWithFixedDate

引入版本：v1.1

提取日期或日期时间值中的时间部分。 返回结果是相对于一个固定时间点的偏移量，目前为 1970-01-02， 但这一具体时间点属于实现细节，将来可能会发生变化。

因此不应单独使用 toTime。 该函数的主要用途是计算两个日期或日期时间值之间的时间差，例如 toTime(dt1) - toTime(dt2)。

语法

toTime(date[, timezone])

参数

• date — 要转换为时间值的日期。Date、DateTime 或 DateTime64
• timezone — 可选。返回值所使用的时区。String

返回值

返回日期或日期时间的时间部分，形式为相对于固定时间点（目前选定为 1970-01-02）的偏移量。DateTime

示例

计算两个日期之间的时间差

SELECT toTime('2025-06-15 12:00:00'::DateTime) - toTime('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)

┌─result─┬─toTypeName(result)─┐
│   3600 │ Int32              │
└────────┴────────────────────┘

toTimezone

引入于：v1.1

将 DateTime 或 DateTime64 转换为指定的时区。 数据的内部值（Unix 秒数）不会改变。 只会改变该值的时区属性以及其字符串形式。

语法

toTimeZone(datetime, timezone)

别名: toTimeZone

参数

• date — 要转换的值。DateTime 或 DateTime64
• timezone — 目标时区名称。String

返回值

返回与输入时间点相同、但使用指定时区的 DateTime 或 DateTime64

示例

用法示例

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;

行 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 引入

将指定时区的日期或日期时间值转换为 UTC 时区的时间戳。此函数主要为与 Apache Spark 及类似框架的兼容性而提供。

语法

toUTCTimestamp(datetime, time_zone)

别名：to_utc_timestamp

参数

• datetime — 日期或日期时间类型的常量值或表达式。DateTime 或 DateTime64
• time_zone — 表示时区的 String 类型常量值或表达式。String

返回值

返回 UTC 时区的日期或日期时间值。DateTime 或 DateTime64

示例

将时区转换为 UTC 时间

SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')

┌─toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')─┐
│                                     2023-03-15 16:00:00 │
└─────────────────────────────────────────────────────────┘

toUnixTimestamp

自 v1.1 起提供

将 String、Date 或 DateTime 转换为 Unix 时间戳（自 1970-01-01 00:00:00 UTC 起的秒数），类型为 UInt32。

语法

toUnixTimestamp(date[, timezone])

参数

• date — 要转换的值。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• timezone — 可选。用于转换的时区。如果未指定，则使用服务器时区。String

返回值

返回 Unix 时间戳。UInt32

示例

用法示例

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;

行 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

此函数返回日期或 datetime 的周序号。toWeek() 的双参数形式允许指定一周从星期日还是星期一开始，以及返回值是在 0 到 53 还是 1 到 53 的范围内。

toISOWeek() 是一个兼容性函数，等价于 toWeek(date,3)。

下表描述了 mode 参数的工作方式。

Mode	First day of week	Range	Week 1 is the first week ...
0	Sunday	0-53	with a Sunday in this year
1	Monday	0-53	with 4 or more days this year
2	Sunday	1-53	with a Sunday in this year
3	Monday	1-53	with 4 or more days this year
4	Sunday	0-53	with 4 or more days this year
5	Monday	0-53	with a Monday in this year
6	Sunday	1-53	with 4 or more days this year
7	Monday	1-53	with a Monday in this year
8	Sunday	1-53	contains January 1
9	Monday	1-53	contains January 1

对于含义为“该周在本年度中包含 4 天或以上”的 mode 值，周的编号遵循 ISO 8601:1988：

• 如果包含 1 月 1 日的那一周在新的一年中包含 4 天或以上，则该周为第 1 周。
• 否则，该周是上一年的最后一周，而下一周为第 1 周。

对于含义为“包含 1 月 1 日”的 mode 值，包含 1 月 1 日的那一周就是第 1 周。 这一周在新的一年中包含多少天无关紧要，即使只包含一天也是如此。 也就是说，如果 12 月的最后一周包含下一年的 1 月 1 日，那么它将成为下一年的第 1 周。

第一个参数也可以指定为 String，其格式应为 parseDateTime64BestEffort() 所支持的格式。对字符串参数的支持仅出于与 MySQL 的兼容性原因，这是某些第三方工具所要求的。由于将来对字符串参数的支持可能会依赖新的 MySQL 兼容性 SETTING，并且字符串解析通常较慢，因此建议不要使用这种方式。

语法

toWeek(datetime[, mode[, time_zone]])

别名：week

参数

• datetime — 用于获取周编号的日期或日期时间值。Date 或 DateTime
• mode — 可选。0 到 9 的模式决定一周的第一天以及周编号的取值范围。默认值为 0。
• time_zone — 可选。时区。String

返回值

根据指定的模式返回周编号。UInt32

示例

使用不同模式获取周编号

SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9

┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │    52 │    52 │     1 │
└────────────┴───────┴───────┴───────┘

toYYYYMM

首次引入于：v1.1

将日期或日期时间转换为一个 UInt32 数值，包含年份和月份（YYYY * 100 + MM）。 可接受第二个可选的时区参数。如果提供，则该时区必须为字符串常量。

此函数与函数 YYYYMMDDToDate() 的作用相反。

语法

toYYYYMM(datetime[, timezone])

参数

• datetime — 要转换的日期或日期时间。可以是 Date、Date32、DateTime 或 DateTime64
• timezone — 可选。用于转换的时区。如指定，时区必须是字符串常量。String

返回值

返回一个包含年份和月份的 UInt32 值（YYYY * 100 + MM）。UInt32

示例

将当前日期转换为 YYYYMM 格式

SELECT toYYYYMM(now(), 'US/Eastern')

┌─toYYYYMM(now(), 'US/Eastern')─┐
│                        202303 │
└───────────────────────────────┘

toYYYYMMDD

引入版本：v1.1

将日期或日期时间转换为一个 UInt32 类型的数值，数值中包含年份、月份和日期（YYYY * 10000 + MM * 100 + DD）。接受第二个可选的时区参数。如果提供，该时区必须是字符串常量。

语法

toYYYYMMDD(datetime[, timezone])

参数

• datetime — 要转换的日期或带时间的日期。Date 或 Date32 或 DateTime 或 DateTime64
• timezone — 可选。用于转换的时区。如果提供，时区必须是字符串常量。String

返回值

返回一个包含年、月和日的 UInt32 数值（YYYY * 10000 + MM * 100 + DD）。UInt32

示例

将当前日期转换为 YYYYMMDD 格式

SELECT toYYYYMMDD(now(), 'US/Eastern')

┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│                        20230302 │
└─────────────────────────────────┘

toYYYYMMDDhhmmss

引入于：v1.1

将日期或带时间的日期转换为一个 UInt64 数值，按 YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss 的方式编码年份、月份、日期、小时、分钟和秒。 接受第二个可选的时区参数。如果提供，该时区必须是字符串常量。

语法

toYYYYMMDDhhmmss(datetime[, timezone])

参数

• datetime — 要转换的日期或日期时间值。类型为 Date、Date32、DateTime 或 DateTime64
• timezone — 可选。转换所使用的时区。如果指定，时区必须是字符串常量。类型为 String

返回值

返回一个 UInt64 数值，包含年份、月份、日期、小时、分钟和秒（YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss）。UInt64

示例

将当前日期和时间转换为 YYYYMMDDhhmmss 格式

SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')

┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│                        20230302112209 │
└───────────────────────────────────────┘

toYear

引入版本：v1.1

返回 Date 或 DateTime 值的年份部分（公元年，AD）。

语法

toYear(datetime)

别名: YEAR

参数

• datetime — 要从中获取年份的日期或日期时间值。类型为 Date、Date32、DateTime 或 DateTime64。

返回值

返回给定 Date 或 DateTime 的年份，类型为 UInt16。

示例

使用示例

SELECT toYear(toDateTime('2023-04-21 10:20:30'))

┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                     2023  │
└───────────────────────────────────────────┘

toYearNumSinceEpoch

引入版本：v25.3

返回自 1970 年以来经过的年份数。

语法

toYearNumSinceEpoch(date)

参数

• date — 要转换的日期或日期时间值。Date 或 DateTime 或 DateTime64

返回值

正整数

示例

示例

SELECT toYearNumSinceEpoch(toDate('2024-10-01'))

54

toYearWeek

引入于：v20.1

返回某个日期对应的年份和周数。对于一年中的第一周和最后一周，结果中的年份可能与参数日期所在的年份不同。

mode 参数的行为与 toWeek() 的 mode 参数相同。

警告：toYearWeek() 返回的周数可能与 toWeek() 返回的不同。toWeek() 始终在给定年份的上下文中返回周数，如果 toWeek() 返回 0，则 toYearWeek() 会返回上一年最后一周对应的值。参见下面示例中的 prev_yearWeek。

第一个参数也可以指定为 String，其格式需为 parseDateTime64BestEffort() 支持的格式。对字符串参数的支持仅出于与 MySQL 的兼容性考虑，这是某些第三方工具所期望的行为。由于未来对字符串参数的支持可能会依赖新的 MySQL 兼容性设置，并且字符串解析通常较慢，因此建议不要使用这种方式。

语法

toYearWeek(datetime[, mode[, timezone]])

别名: yearweek

参数

• datetime — 要获取其年份和周数的日期或带时间的日期。Date 或 DateTime
• mode — 可选。0 到 9 的模式决定一周的第一天以及周数的取值范围。默认值为 0。- timezone — 可选。时区。String

返回值

返回由年份和周数组合而成的整数值。UInt32

示例

使用不同模式获取 year-week 组合

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

┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │    201652 │    201652 │    201701 │        202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘

today

引入版本：v1.1

在对查询进行分析时返回当前日期。等同于 toDate(now())。

语法

today()

别名: curdate, current_date

参数

• 无。

返回值

返回当前日期（Date 类型）

示例

使用示例

SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │   2025-03-03 │
└────────────┴────────────┴──────────────┘

yesterday

Introduced in: v1.1

不接受任何参数，并在查询分析过程中的某个时刻返回昨天的日期。

Syntax

yesterday()

参数

• 无。

返回值

返回昨天的日期。Date

示例

获取昨天的日期

SELECT yesterday();
SELECT today() - 1;

┌─yesterday()─┐
│  2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2025-06-09 │
└───────────────────┘