跳转到主要内容
本节中的大多数函数都接受可选的时区参数，例如 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 │
└─────────────────────┴────────────┴────────────┴─────────────────────┘
为兼容 SQL 标准，以下函数 NOW、CURRENT_TIMESTAMP、TODAY 和 CURRENT_DATE 可在不加括号的情况下使用。

​
UTCTimestamp

引入版本：v22.11.0 返回查询分析时刻的当前日期和时间。该函数是常量表达式。 此函数的结果与 now('UTC') 相同。添加它仅是为了支持 MySQL。推荐使用 now。 语法 
UTCTimestamp()
别名: UTC_timestamp 参数
  • 无。
返回值 返回查询分析时刻的当前日期和时间。DateTime 示例 获取当前 UTC 时间戳
Query
SELECT UTCTimestamp()
Response
┌──────UTCTimestamp()─┐
│ 2024-05-28 08:32:09 │
└─────────────────────┘

​
YYYYMMDDToDate

引入版本：v23.9.0 将包含年份、月份和日期数字的数值转换为 Date。 此函数与 toYYYYMMDD() 的作用相反。 如果输入未编码出有效的 Date 值，则输出结果未定义。 语法 
YYYYMMDDToDate(YYYYMMDD)
参数 返回值 根据给定参数返回一个 Date 值 Date 示例 示例
Query
SELECT YYYYMMDDToDate(20230911);
Response
┌─toYYYYMMDD(20230911)─┐
│           2023-09-11 │
└──────────────────────┘

​
YYYYMMDDToDate32

引入版本：v23.9.0 将包含年、月、日的数值转换为 Date32。 此函数与 toYYYYMMDD() 函数相反。 如果输入未编码为有效的 Date32 值，则输出结果未定义。 语法 
YYYYMMDDToDate32(YYYYMMDD)
参数 返回值 返回由给定参数生成的 Date32 值 Date32 示例 示例
Query
SELECT YYYYMMDDToDate32(20000507);
Response
┌─YYYYMMDDToDate32(20000507)─┐
│                 2000-05-07 │
└────────────────────────────┘

​
YYYYMMDDhhmmssToDateTime

引入版本：v23.9.0 将包含年、月、日、时、分、秒的数字转换为 DateTime。 此函数与 toYYYYMMDDhhmmss() 的作用相反。 如果输入未编码为有效的 DateTime 值，则输出结果未定义。 语法 
YYYYMMDDhhmmssToDateTime(YYYYMMDDhhmmss[, timezone])
参数
  • YYYYMMDDhhmmss — 包含年、月、日、时、分、秒的数值。(U)Int* 或 Float* 或 Decimal
  • timezone — 时区名称。String
返回值 根据给定参数返回 DateTime 值。DateTime 示例 示例
Query
SELECT YYYYMMDDToDateTime(20230911131415);
Response
┌──────YYYYMMDDhhmmssToDateTime(20230911131415)─┐
│                           2023-09-11 13:14:15 │
└───────────────────────────────────────────────┘

​
YYYYMMDDhhmmssToDateTime64

引入版本：v23.9.0 将包含年、月、日、小时、分钟和秒的数字转换为 DateTime64。 此函数与 toYYYYMMDDhhmmss() 函数的作用相反。 如果输入未编码为有效的 DateTime64 值，则输出结果未定义。 语法 
YYYYMMDDhhmmssToDateTime64(YYYYMMDDhhmmss[, precision[, timezone]])
参数
  • YYYYMMDDhhmmss — 包含年、月、日、时、分、秒的数值。(U)Int* 或 Float* 或 Decimal
  • precision — 小数部分精度 (0-9) 。UInt8
  • timezone — 时区名称。String
返回值 根据给定参数返回一个 DateTime64 值。DateTime64 示例 示例
Query
SELECT YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul');
Response
┌─YYYYMMDDhhmm⋯/Istanbul')─┐
│  2023-09-11 13:14:15.000 │
└──────────────────────────┘

​
addDate

引入版本：v23.9.0 将时间间隔加到给定的日期、日期时间，或以字符串编码的日期或日期时间上。 如果相加后的值超出该数据类型的取值范围，则结果未定义。 语法 
addDate(datetime, interval)
参数 返回值 返回将 interval 添加到 datetime 后得到的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 示例 为日期添加时间间隔
Query
SELECT addDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
Response
┌─addDate(toDa⋯valYear(3))─┐
│               2021-01-01 │
└──────────────────────────┘

​
addDays

引入版本：v1.1.0 为日期、日期时间，或以字符串编码的日期或日期时间增加指定天数。 语法 
addDays(datetime, num)
参数 返回值 返回 datetime 加上 num 天后的结果。Date 或 Date32 或 DateTime 或 DateTime64 示例 为不同的日期类型增加天数
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 day)
Response
┌─plus(CAST('1⋯valDay(10))─┐
│               1998-06-26 │
└──────────────────────────┘

​
addHours

引入版本：v1.1.0 为日期、日期时间，或以字符串编码的日期或日期时间增加指定小时数。 语法 
addHours(datetime, num)
参数 返回值 返回 datetime 加上 num 小时后的结果：DateTime 或 DateTime64(3) 示例 为不同日期类型添加小时
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 hour)
Response
┌─plus(CAST('1⋯alHour(10))─┐
│      1998-06-16 10:00:00 │
└──────────────────────────┘

​
addInterval

引入版本：v22.11.0 将一个时间间隔加到另一个时间间隔或时间间隔元组中。
相同类型的时间间隔会合并成一个时间间隔。例如，如果传入 toIntervalDay(1) 和 toIntervalDay(2)，则结果将是 (3)，而不是 (1,1)。
语法 
addInterval(interval_1, interval_2)
参数
  • interval_1 — 第一个时间间隔或由多个时间间隔组成的 Tuple。Interval 或 Tuple(Interval)
  • interval_2 — 要相加的第二个时间间隔。Interval
返回值 返回由时间间隔组成的 Tuple Tuple(Interval) 示例 时间间隔相加
Query
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
┌─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 向日期时间或字符串形式的日期时间添加指定的微秒数。 语法 
addMicroseconds(datetime, num)
参数 返回值 返回 date_time 加上 num 微秒后的结果。DateTime64 示例 为不同的日期时间类型添加微秒
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 microsecond)
Response
┌─plus(CAST('19⋯osecond(10))─┐
│ 1998-06-16 00:00:00.000010 │
└────────────────────────────┘

​
addMilliseconds

版本引入：v22.6.0 为日期时间或以字符串编码的日期时间添加指定的毫秒数。 语法 
addMilliseconds(datetime, num)
参数 返回值 返回加上 num 毫秒后的 datetime。DateTime64 示例 为不同的日期时间类型添加毫秒
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 10 millisecond)
Response
┌─plus(CAST('1⋯second(10))─┐
│  1998-06-16 00:00:00.010 │
└──────────────────────────┘

​
addMinutes

引入版本：v1.1.0 将指定的分钟数加到日期、日期时间，或以字符串编码的日期或日期时间上。 语法 
addMinutes(datetime, num)
参数 返回值 返回 datetime 加上 num 分钟后的值。DateTime 或 DateTime64(3) 示例 为不同日期类型添加分钟
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 minute)
Response
┌─plus(CAST('1⋯Minute(10))─┐
│      1998-06-16 00:10:00 │
└──────────────────────────┘

​
addMonths

引入版本：v1.1.0 为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的月份。 语法 
addMonths(datetime, num)
参数 返回值 返回 datetime 加上 num 个月后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 向不同日期类型添加月份
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 month)
Response
┌─plus(CAST('1⋯lMonth(10))─┐
│               1999-04-16 │
└──────────────────────────┘

​
addNanoseconds

引入版本：v22.6.0 为日期时间或以字符串编码的日期时间添加指定数量的纳秒。 语法 
addNanoseconds(datetime, num)
参数 返回值 返回 datetime 加上 num 纳秒后的结果，类型为 DateTime64 示例 为不同的日期时间类型添加纳秒
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::DateTime, INTERVAL 1000 nanosecond)
Response
┌─plus(CAST('199⋯osecond(1000))─┐
│ 1998-06-16 00:00:00.000001000 │
└───────────────────────────────┘

​
addQuarters

引入版本：v20.1.0 为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的季度。 语法 
addQuarters(datetime, num)
参数 返回值 返回在 datetime 基础上加上 num 个季度后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 为不同的日期类型添加季度
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 quarter)
Response
┌─plus(CAST('1⋯uarter(10))─┐
│               2000-12-16 │
└──────────────────────────┘

​
addSeconds

首次引入于：v1.1.0 将指定的秒数加到日期、日期时间，或字符串编码的日期或日期时间上。 语法 
addSeconds(datetime, num)
参数 返回值 返回 datetime 加上 num 秒后的值。DateTime 或 DateTime64(3) 示例 为不同日期类型添加秒数
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 second)
Response
┌─dateAdd('1998-06-16'::Date, INTERVAL 10 second)─┐
│                             1998-06-16 00:00:10 │
└─────────────────────────────────────────────────┘

​
addTupleOfIntervals

引入版本：v22.11.0 将一个时间间隔 Tuple 依次添加到日期或日期时间中。 语法 
addTupleOfIntervals(datetime, intervals)
参数 返回值 返回加上 intervals 后的 date。Date 或 Date32 或 DateTime 或 DateTime64 示例 将时间间隔 Tuple 添加到日期
Query
WITH toDate('2018-01-01') AS date
SELECT addTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 MONTH, INTERVAL 1 YEAR))
Response
┌─addTupleOfIntervals(date, (toIntervalDay(1), toIntervalMonth(1), toIntervalYear(1)))─┐
│                                                                           2019-02-02 │
└──────────────────────────────────────────────────────────────────────────────────────┘

​
addWeeks

引入版本：v1.1.0 为日期、日期时间或以字符串编码的日期/日期时间增加指定的周数。 语法 
addWeeks(datetime, num)
参数 返回值 返回 datetime 加上 num 周后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 为不同日期类型添加周数
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 week)
Response
┌─plus(CAST('1⋯alWeek(10))─┐
│               1998-08-25 │
└──────────────────────────┘

​
addYears

引入于：v1.1.0 为日期、日期时间或字符串编码的日期/日期时间增加指定的年数。 语法 
addYears(datetime, num)
参数 返回值 返回 datetime 加上 num 年后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 为不同日期类型添加年份
Query
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
┌─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 语法
Query
SELECT dateAdd('1998-06-16'::Date, INTERVAL 10 year)
Response
┌─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。 语法 
age('unit', startdate, enddate[, timezone])
参数
  • unit — 结果的时间间隔类型。
单位可能的值
nanosecondnanosecond, nanoseconds, ns
microsecondmicrosecond, microseconds, us, u
millisecondmillisecond, milliseconds, ms
secondsecond, seconds, ss, s
minuteminute, minutes, mi, n
hourhour, hours, hh, h
dayday, days, dd, d
weekweek, weeks, wk, ww
monthmonth, months, mm, m
quarterquarter, quarters, qq, q
yearyear, years, yyyy, yy
  • startdate — 相减时的第一个时间值 (减数) 。Date 或 Date32 或 DateTime 或 DateTime64
  • enddate — 相减时的第二个时间值 (被减数) 。Date 或 Date32 或 DateTime 或 DateTime64
  • timezone — 可选。时区名称。如果指定，则同时应用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 各自的时区。如果两者不一致，则结果未定义。String
返回值 返回以 unit 表示的 enddate 与 startdate 之差。Int32 示例 按小时计算年龄
Query
SELECT age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))
Response
┌─age('hour', toDateTime('2018-01-01 22:30:00'), toDateTime('2018-01-02 23:00:00'))─┐
│                                                                                24 │
└───────────────────────────────────────────────────────────────────────────────────┘
按不同单位计算年龄
Query
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
┌──────────e─┬──────────s─┬─day_age─┬─month_age─┬─year_age─┐
│ 2022-01-01 │ 2021-12-29 │       3 │         0 │        0 │
└────────────┴────────────┴─────────┴───────────┴──────────┘

​
changeDay

引入版本：v24.7.0 更改日期或日期时间中的日字段。 语法 
changeDay(date_or_datetime, value)
参数 返回值 返回与 date_or_datetime 类型相同、但日期部分已修改的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeDay('2024-01-31'::DateTime, 15)
Response
2024-01-15 00:00:00

​
changeHour

首次引入于：v24.7.0 更改日期或日期时间中的小时部分。 语法 
changeHour(date_or_datetime, value)
参数 返回值 返回一个与 date_or_datetime 类型相同、但小时部分已修改的值。DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeHour('2024-01-01 12:00:00'::DateTime, 5)
Response
2024-01-01 05:00:00

​
changeMinute

引入版本：v24.7.0 更改 日期或日期时间 的分钟部分。 语法 
changeMinute(date_or_datetime, value)
参数 返回值 返回一个与 date_or_datetime 类型相同、分钟部分已修改的值。DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeMinute('2024-01-01 12:30:00'::DateTime, 45)
Response
2024-01-01 12:45:00

​
changeMonth

引入版本：v24.7.0 更改日期或日期时间中的月份部分。 语法 
changeMonth(date_or_datetime, value)
参数 返回值 返回与 date_or_datetime 类型相同、月份部分已修改的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeMonth('2024-01-01'::DateTime, 12)
Response
2024-12-01 00:00:00

​
changeSecond

引入版本：v24.7.0 更改日期或日期时间的秒部分。 语法 
changeSecond(date_or_datetime, value)
参数 返回值 返回与 date_or_datetime 类型相同、但秒部分已被修改的值。DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeSecond('2024-01-01 12:30:45'::DateTime, 15)
Response
2024-01-01 12:30:15

​
changeYear

首次引入版本：v24.7.0 更改日期或日期时间中的年份部分。 语法 
changeYear(date_or_datetime, value)
参数 返回值 返回一个与 date_or_datetime 类型相同、但年份部分已修改的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 使用示例
Query
SELECT changeYear('2024-01-01'::DateTime, 2023)
Response
2023-01-01 00:00:00

​
dateDiff

引入版本：v23.4.0 返回 startdate 与 enddate 之间跨过的指定 unit 边界数。 该差值按相对单位计算。例如，对于单位 day，2021-12-29 与 2022-01-01 之间相差 3 天 (参见 toRelativeDayNum) ；对于单位 month，相差 1 个月 (参见 toRelativeMonthNum) ；对于单位 year，相差 1 年 (参见 toRelativeYearNum) 。 如果指定单位为 week，则 dateDiff 假定每周从星期一开始。 请注意，这一行为与函数 toWeek() 不同，后者默认将星期日视为每周的开始。 如需 dateDiff 的替代方案，请参见函数 age。 语法 
dateDiff(unit, startdate, enddate[, timezone])
别名: timestampDiff, TIMESTAMP_DIFF, DATE_DIFF, date_diff, timestamp_diff 参数
  • unit — 结果所使用的时间间隔类型。
单位可能的值
nanosecondnanosecond, nanoseconds, ns
microsecondmicrosecond, microseconds, us, u
millisecondmillisecond, milliseconds, ms
secondsecond, seconds, ss, s
minuteminute, minutes, mi, n
hourhour, hours, hh, h
dayday, days, dd, d
weekweek, weeks, wk, ww
monthmonth, months, mm, m
quarterquarter, quarters, qq, q
yearyear, years, yyyy, yy
  • startdate — 要相减的第一个时间值 (减数) 。Date 或 Date32 或 DateTime 或 DateTime64
  • enddate — 要减去第一个时间值的第二个时间值 (被减数) 。Date 或 Date32 或 DateTime 或 DateTime64
  • timezone — 可选。时区名称。如果指定，则同时应用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 各自的时区。如果两者不一致，则结果未指定。String
返回值 返回 enddate 与 startdate 之间以 unit 表示的差值。Int64 示例 按小时计算日期差值
Query
SELECT dateDiff('hour', toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
Response
┌─res─┐
│  25 │
└─────┘
按不同单位计算日期差
Query
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
┌──────────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’
语法 
dateName(date_part, date[, timezone])
参数 返回值 返回指定的日期部分。String 示例 提取不同的日期部分
Query
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
┌─dateName('year', date_value)─┬─dateName('month', date_value)─┬─dateName('day', date_value)─┐
│ 2021                         │ April                         │ 14                          │
└──────────────────────────────┴───────────────────────────────┴─────────────────────────────┘

​
dateTrunc

引入版本：v20.8.0 按指定的日期部分截断日期和时间值。 语法 
dateTrunc(unit, datetime[, timezone])
别名: DATE_TRUNC 参数
  • unit — 用于截断结果的时间间隔类型。可能的值：nanosecond (仅限 DateTime64) 、microsecond (仅限 DateTime64) 、millisecond (仅限 DateTime64) 、second、minute、hour、day、week、month、quarter、year。 String
  • datetime — 日期和时间。Date 或 Date32 或 DateTime 或 DateTime64
  • timezone — 可选。返回的日期时间使用的时区名称。如未指定，函数将使用 datetime 参数的时区。String
返回值 返回截断后的日期时间值。
Unit Argumentdatetime ArgumentReturn Type
Year, Quarter, Month, WeekDate32 or DateTime64 or Date or DateTimeDate32 or Date
Day, Hour, Minute, SecondDate32, DateTime64, Date, or DateTimeDateTime64 or DateTime
Millisecond, Microsecond,AnyDateTime64
Nanosecondwith scale 3, 6, or 9
示例 不指定时区进行截断
Query
SELECT now(), dateTrunc('hour', now());
Response
┌───────────────now()─┬─dateTrunc('hour', now())──┐
│ 2020-09-28 10:40:45 │       2020-09-28 10:00:00 │
└─────────────────────┴───────────────────────────┘
使用指定时区截断
Query
SELECT now(), dateTrunc('hour', now(), 'Asia/Istanbul');
Response
┌───────────────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。 此函数的反向操作是 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/%y01/02/18
%e一个月中的第几天，左侧补空格 (1-31)2
%f秒的小数部分123456
%F短格式 YYYY-MM-DD 日期，等同于 %Y-%m-%d2018-01-02
%g两位数年份格式，与 ISO 8601 对齐18
%G用于 ISO 周数的四位数年份格式2018
%h12 小时制小时 (01-12)09
%H24 小时制小时 (00-23)22
%i分钟 (00-59)33
%I12 小时制小时 (01-12)10
%j一年中的第几天 (001-366)002
%k24 小时制小时 (00-23)14
%l12 小时制小时 (01-12)09
%m以整数表示的月份 (01-12)01
%M完整月份名称 (January-December)January
%n换行符
%pAM 或 PM 标记PM
%Q季度 (1-4)1
%r12 小时制 HH:MM AM/PM 时间，等同于 %h:%i %p10:30 PM
%R24 小时制 HH:MM 时间，等同于 %H:%i22:33
%s秒 (00-59)44
%S秒 (00-59)44
%t水平制表符
%TISO 8601 时间格式 (HH:MM:SS) ，等同于 %H:%i:%S22:33:44
%uISO 8601 星期数字表示，周一为 1 (1-7)2
%VISO 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) 。
语法 
formatDateTime(datetime, format[, timezone])
别名：DATE_FORMAT 参数
  • datetime — 要格式化的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
  • format — 包含替换字段的格式字符串。String
  • timezone — 可选。格式化后时间使用的时区名称。String
返回值 根据指定格式返回时间和日期值。String 示例 使用年份占位符格式化日期
Query
SELECT formatDateTime(toDate('2010-01-04'), '%g')
Response
┌─formatDateTime(toDate('2010-01-04'), '%g')─┐
│ 10                                         │
└────────────────────────────────────────────┘
将 DateTime64 格式化为带有小数秒的格式
Query
SELECT formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')
Response
┌─formatDateTime(toDateTime64('2010-01-04 12:34:56.123456', 7), '%f')─┐
│ 1234560                                                             │
└─────────────────────────────────────────────────────────────────────┘
按时区格式化
Query
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
┌──────────────────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 文档。 此函数的反向操作是 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
’文本转义符定界符
”单引号字面量’
语法 
formatDateTimeInJodaSyntax(datetime, format[, timezone])
参数
  • datetime — 要格式化的日期或日期时间值。DateTime 或 Date 或 Date32 或 DateTime64
  • format — 使用 Joda 语法替换字段的格式字符串。String
  • timezone — 可选。格式化时间所用的时区名称。String
返回值 根据指定格式返回日期和时间值。String 示例 使用 Joda 语法格式化日期时间
Query
SELECT formatDateTimeInJodaSyntax(toDateTime('2010-01-04 12:34:56'), 'yyyy-MM-dd HH:mm:ss')
Response
┌─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 日以来经过的天数，返回 ISO 8601 定义的前推格里高利历中的对应日期。 该计算方式与 MySQL 的 FROM_DAYS() 函数相同。如果结果无法表示在 Date 类型的取值范围内，则结果未定义。 语法 
fromDaysSinceYearZero(days)
别名: FROM_DAYS 参数
  • days — 自零年开始经过的天数。UInt32
返回值 返回与自零年开始经过的天数对应的日期。Date 示例 将自零年开始经过的天数转换为日期
Query
SELECT
fromDaysSinceYearZero(739136) AS date1,
fromDaysSinceYearZero(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
Response
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

​
fromDaysSinceYearZero32

引入版本：v23.11.0 对于自 0000 年 1 月 1 日 起经过的给定天数，返回 ISO 8601 定义的前推格里高利历中的对应日期。 其计算方式与 MySQL 的 FROM_DAYS() 函数相同。如果结果无法在 Date32 类型的取值范围内表示，则结果未定义。 语法 
fromDaysSinceYearZero32(days)
参数
  • days — 自零年起累计经过的天数。UInt32
返回值 返回与自零年起累计经过的天数对应的日期。Date32 示例 将自零年起累计经过的天数转换为日期
Query
SELECT
fromDaysSinceYearZero32(739136) AS date1,
fromDaysSinceYearZero32(toDaysSinceYearZero(toDate('2023-09-08'))) AS date2
Response
┌──────date1─┬──────date2─┐
│ 2023-09-08 │ 2023-09-08 │
└────────────┴────────────┘

​
fromModifiedJulianDay

引入版本：v21.1.0 将 修正儒略日 数值转换为文本格式的 前推格里高利历 日期 YYYY-MM-DD。此函数支持的日数范围为 -678941 到 2973483 (分别表示 0000-01-01 和 9999-12-31) 。如果日数超出支持范围，则会引发异常。 语法 
fromModifiedJulianDay(day)
参数
  • day — 修正儒略日编号。(U)Int*
返回值 以文本形式返回日期。 String 示例 将修正儒略日转换为日期
Query
SELECT fromModifiedJulianDay(58849)
Response
┌─fromModifiedJulianDay(58849)─┐
│ 2020-01-01                   │
└──────────────────────────────┘

​
fromModifiedJulianDayOrNull

引入版本：v21.1.0 与 fromModifiedJulianDay() 类似，但它不会抛出异常，而是返回 NULL。 语法 
fromModifiedJulianDayOrNull(day)
参数
  • day — 修正儒略日编号。(U)Int*
返回值 如果 day 参数有效，则以文本形式返回日期；否则返回 null。Nullable(String) 示例 将修正儒略日转换为日期，并处理 null 值
Query
SELECT fromModifiedJulianDayOrNull(58849);
SELECT fromModifiedJulianDayOrNull(60000000); -- 无效参数，返回 NULL
Response
┌─fromModified⋯Null(58849)─┐
│ 2020-01-01               │
└──────────────────────────┘
┌─fromModified⋯l(60000000)─┐
│ ᴺᵁᴸᴸ                     │
└──────────────────────────┘

​
fromUTCTimestamp

引入版本：v22.1.0 将日期或日期时间值从 UTC 时区转换为指定时区中的日期或日期时间值。此函数主要是为了兼容 Apache Spark 及类似框架而提供。 语法 
fromUTCTimestamp(datetime, time_zone)
别名：from_utc_timestamp 参数
  • datetime — 日期或日期时间常量值，或表达式。DateTime 或 DateTime64
  • time_zone — String 类型的常量值，或表示时区的表达式。String
返回值 返回指定时区的 DateTime/DateTime64。DateTime 或 DateTime64 示例 将 UTC 时区转换为指定时区
Query
SELECT fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00', 3), 'Asia/Shanghai')
Response
┌─fromUTCTimestamp(toDateTime64('2023-03-16 10:00:00',3), 'Asia/Shanghai')─┐
│                                                 2023-03-16 18:00:00.000 │
└─────────────────────────────────────────────────────────────────────────┘

​
fromUnixTimestamp

引入版本：v20.8.0 此函数将 Unix timestamp 转换为日历日期和一天中的时间。 它有两种调用方式： 语法 
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
Query
SELECT fromUnixTimestamp(423543535)
Response
┌─fromUnixTimestamp(423543535)─┐
│          1983-06-04 10:58:55 │
└──────────────────────────────┘
按格式转换 Unix 时间戳
Query
SELECT fromUnixTimestamp(1234334543, '%Y-%m-%d %R:%S') AS DateTime
Response
┌─DateTime────────────┐
│ 2009-02-11 14:42:23 │
└─────────────────────┘

​
fromUnixTimestampInJodaSyntax

引入版本：v23.1.0 此函数将 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
返回值 传入一个参数时，返回日期时间值；传入两个或三个参数时，返回 String。} DateTime 或 String 示例 使用 Joda 格式转换 Unix 时间戳
Query
SELECT fromUnixTimestampInJodaSyntax(1234334543, 'yyyy-MM-dd HH:mm:ss', 'UTC') AS DateTime
Response
┌─DateTime────────────┐
│ 2009-02-11 06:42:23 │
└─────────────────────┘

​
makeDate

版本引入：v22.6.0 根据以下任一输入创建 Date：
  • 年、月、日
  • 年和一年中的第几天
语法 
makeDate(year, month, day)
makeDate(year, day_of_year)
参数 返回值 返回一个根据给定参数构造的 Date 值 Date 示例 根据年、月、日构造日期
Query
SELECT makeDate(2023, 2, 28) AS date;
Response
┌───────date─┐
│ 2023-02-28 │
└────────────┘
根据年份和年内第几天生成日期
Query
SELECT makeDate(2023, 42) AS date;
Response
┌───────date─┐
│ 2023-02-11 │
└────────────┘

​
makeDate32

引入版本：v22.6.0 通过以下任一方式创建 Date32：
  • 年、月、日
  • 年和一年中的第几天
语法 
makeDate32(year, month, day)
makeDate32(year, day_of_year)
参数 返回值 返回根据提供的参数构造的 Date32 值 Date32 示例 由年、月、日构造 Date32
Query
SELECT makeDate(2023, 2, 28) AS date;
Response
┌───────date─┐
│ 2023-02-28 │
└────────────┘
根据年份和一年中的第几天生成 Date32
Query
SELECT makeDate(2023, 42) AS date;
Response
┌───────date─┐
│ 2023-02-11 │
└────────────┘

​
makeDateTime

引入版本：v22.6.0 根据年、月、日、时、分和秒创建 DateTime，并可选指定 timezone。 语法 
makeDateTime(year, month, day, hour, minute, second[, timezone])
参数 返回值 返回根据提供的参数构造的 DateTime 值 DateTime 示例 根据 year、month、day、hour、minute、second 构造 DateTime
Query
SELECT makeDateTime(2023, 2, 28, 17, 12, 33) AS DateTime;
Response
┌────────────DateTime─┐
│ 2023-02-28 17:12:33 │
└─────────────────────┘

​
makeDateTime64

引入版本：v22.6.0 根据 year、month、day、hour、minute、second 创建 DateTime64，并可选指定 fraction、precision 和 timezone。 语法 
makeDateTime64(year, month, day, hour, minute, second[, fraction[, precision[, timezone]]])
参数 返回值 返回根据给定参数构造的 DateTime64 值 DateTime64 示例 通过 year、month、day、hour、minute、second 构造 DateTime64
Query
SELECT makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5);
Response
┌─makeDateTime64(2023, 5, 15, 10, 30, 45, 779, 5)─┐
│                       2023-05-15 10:30:45.00779 │
└─────────────────────────────────────────────────┘

​
monthName

首次引入于：v22.1.0 返回日期或日期时间值对应的月份名称字符串。 语法 
monthName(datetime)
参数 返回值 返回月份名称。String 示例 从日期中获取月份名称
Query
WITH toDateTime('2021-04-14 11:22:33') AS date_value
SELECT monthName(date_value)
Response
┌─monthName(date_value)─┐
│ April                 │
└───────────────────────┘

​
now

引入版本：v1.1.0 返回查询分析时的当前日期和时间。该函数是一个常量表达式。 语法 
now([timezone])
别名: current_timestamp 参数
  • timezone — 可选。返回值所用的时区名称。String
返回值 返回当前日期和时间。DateTime 示例 不带时区的查询
Query
SELECT now()
Response
┌───────────────now()─┐
│ 2020-10-17 07:42:09 │
└─────────────────────┘
指定时区的查询
Query
SELECT now('Asia/Istanbul')
Response
┌─now('Asia/Istanbul')─┐
│  2020-10-17 10:42:23 │
└──────────────────────┘
不使用括号的 SQL 标准语法
Query
SELECT NOW, CURRENT_TIMESTAMP
Response
┌─────────────────NOW─┬───CURRENT_TIMESTAMP─┐
│ 2020-10-17 07:42:19 │ 2020-10-17 07:42:19 │
└─────────────────────┴─────────────────────┘

​
now64

引入版本：v20.1.0 返回查询分析时刻的当前日期和时间，具有子秒级精度。该函数是一个常量表达式。 语法 
now64([scale[, timezone]])
参数
  • scale — 可选。时间粒度 (precision) 为 10^-precision 秒。有效范围：[0 : 9]。通常使用 3 (默认，毫秒) 、6 (微秒) 或 9 (纳秒) 。UInt8
  • timezone — 可选。用于返回值的时区名称。String
返回值 返回带有子秒级精度的当前日期和时间。DateTime64 示例 使用默认精度和自定义精度的查询
Query
SELECT now64(), now64(9, 'Asia/Istanbul')
Response
┌─────────────────now64()─┬─────now64(9, 'Asia/Istanbul')─┐
│ 2022-08-21 19:34:26.196 │ 2022-08-21 22:34:26.196542766 │
└─────────────────────────┴───────────────────────────────┘

​
nowInBlock

自 v22.8.0 引入 返回处理每个数据块时的当前日期和时间。与函数 now 不同，它不是常量表达式，因此对于运行时间较长的查询，不同块中的返回值会不同。 在运行时间较长的 INSERT SELECT 查询中，使用此函数生成当前时间是合理的。 语法 
nowInBlock([timezone])
参数
  • timezone — 可选。返回值所用的时区名称。String
返回值 返回处理每个数据块时的当前日期和时间。DateTime 示例 与 now() 函数的区别
Query
SELECT
    now(),
    nowInBlock(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
Response
┌───────────────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 不同，它不是常量表达式，因此对于长时间运行的查询，不同块返回的值会有所不同。 在长时间运行的 INSERT SELECT 查询中，使用此函数生成当前时间很有意义。 语法 
nowInBlock64([scale[, timezone]])
参数
  • scale — 可选。时间粒度 (precision) ：10^-precision 秒。有效范围：[0 : 9]。通常使用 3 (默认，毫秒) 、6 (微秒) 或 9 (纳秒) 。UInt8
  • timezone — 可选。返回值的时区名称。String
返回值 返回处理每个数据块时刻的当前日期和时间，具有子秒级精度。DateTime64 示例 与 now64() 函数的区别
Query
SELECT
    now64(),
    nowInBlock64(),
    sleep(1)
FROM numbers(3)
SETTINGS max_block_size = 1
FORMAT PrettyCompactMonoBlock
Response
┌─────────────────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 设置的值。 如果该函数是在分布式表的上下文中执行的，则会生成一个普通列，其值对应各个分片。否则，会生成一个常量值。 语法 
serverTimezone()
别名：serverTimeZone 参数
  • 无。
返回值 返回服务器时区，类型为 String 示例 使用示例
Query
SELECT serverTimeZone()
Response
┌─serverTimeZone()─┐
│ UTC              │
└──────────────────┘

​
subDate

引入版本：v23.9.0 从给定的日期、日期时间，或以字符串编码的日期或日期时间中减去时间间隔。 如果相减后的值超出该数据类型的取值范围，则结果未定义。 语法 
subDate(datetime, interval)
参数 返回值 返回从 datetime 中减去 interval 后得到的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 示例 从日期中减去时间间隔
Query
SELECT subDate(toDate('2018-01-01'), INTERVAL 3 YEAR)
Response
┌─subDate(toDate('2018-01-01'), toIntervalYear(3))─┐
│                                       2015-01-01 │
└──────────────────────────────────────────────────┘

​
subtractDays

引入版本：v1.1.0 从日期、日期时间，或字符串形式的日期或日期时间中减去指定天数。 语法 
subtractDays(datetime, num)
参数 返回值 返回 datetime 减去 num 天后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 从不同日期类型中减去天数
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 day)
Response
┌─minus(CAST('⋯valDay(10))─┐
│               1998-06-06 │
└──────────────────────────┘

​
subtractHours

引入版本：v1.1.0 从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的小时数。 语法 
subtractHours(datetime, num)
参数 返回值 返回 datetime 减去 num 小时后的结果。DateTime 或 DateTime64(3) 示例 对不同日期类型减去小时数
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 hour)
Response
┌─minus(CAST('⋯alHour(10))─┐
│      1998-06-15 14:00:00 │
└──────────────────────────┘

​
subtractInterval

首次引入版本：v22.11.0 将一个取负的时间间隔加到另一个时间间隔或由多个时间间隔组成的元组上。 注意：相同类型的时间间隔会合并为单个时间间隔。例如，如果传入 toIntervalDay(2) 和 toIntervalDay(1)， 那么结果将是 (1)，而不是 (2,1)。 语法 
subtractInterval(interval_1, interval_2)
参数
  • interval_1 — 第一个时间间隔，或由时间间隔组成的 Tuple。Interval 或 Tuple(Interval)
  • interval_2 — 将被取反的第二个时间间隔。Interval
返回值 返回由时间间隔组成的元组 Tuple(T) 示例 时间间隔相减
Query
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
┌─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 从日期时间或字符串编码的日期时间中减去指定数量的微秒。 语法 
subtractMicroseconds(datetime, num)
参数 返回值 返回 datetime 减去 num 微秒后的结果：DateTime64 示例 对不同的日期时间类型减去微秒
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 microsecond)
Response
┌─minus(CAST('1⋯osecond(10))─┐
│ 1998-06-15 23:59:59.999990 │
└────────────────────────────┘

​
subtractMilliseconds

引入版本：v22.6.0 从日期时间或字符串形式编码的日期时间中减去指定毫秒数。 语法 
subtractMilliseconds(datetime, num)
参数 返回值 返回 datetime 减去 num 毫秒后的结果。DateTime64 示例 从不同的日期时间类型中减去毫秒
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 millisecond)
Response
┌─minus(CAST('⋯second(10))─┐
│  1998-06-15 23:59:59.990 │
└──────────────────────────┘

​
subtractMinutes

引入版本：v1.1.0 从日期、日期时间或以字符串编码的日期/日期时间中减去指定的分钟数。 语法 
subtractMinutes(datetime, num)
参数 返回值 返回 datetime 减去 num 分钟后的值。DateTime 或 DateTime64(3) 示例 从不同日期类型中减去分钟
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 minute)
Response
┌─minus(CAST('⋯Minute(10))─┐
│      1998-06-15 23:50:00 │
└──────────────────────────┘

​
subtractMonths

引入版本：v1.1.0 从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的月数。 语法 
subtractMonths(datetime, num)
参数 返回值 返回 datetime 减去 num 个月后的结果。Date 或 Date32 或 DateTime 或 DateTime64 示例 从不同日期类型中减去月份
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 month)
Response
┌─minus(CAST('⋯lMonth(10))─┐
│               1997-08-16 │
└──────────────────────────┘

​
subtractNanoseconds

自 v20.1.0 起引入 从日期时间或以字符串编码的日期时间中减去指定纳秒数。 语法 
subtractNanoseconds(datetime, num)
参数 返回值 返回 datetime 减去 num 纳秒后的结果。DateTime64 示例 从不同的日期时间类型中减去纳秒
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::DateTime, INTERVAL 10 nanosecond)
Response
┌─minus(CAST('19⋯anosecond(10))─┐
│ 1998-06-15 23:59:59.999999990 │
└───────────────────────────────┘

​
subtractQuarters

引入版本：v20.1.0 从日期、日期时间或以字符串编码的日期或日期时间中减去指定数量的季度。 语法 
subtractQuarters(datetime, num)
参数 返回值 返回 datetime 减去 num 个季度后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 从不同日期类型中减去季度
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 quarter)
Response
┌─minus(CAST('1⋯Quarter(10))─┐
│                1996-09-16 │
└───────────────────────────┘

​
subtractSeconds

引入版本：v1.1.0 从日期、日期时间，或以字符串编码的日期或日期时间中减去指定的秒数。 语法 
subtractSeconds(datetime, num)
参数 返回值 返回 datetime 减去 num 秒后的结果：DateTime 或 DateTime64(3) 示例 从不同日期类型中减去秒数
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 second)
Response
┌─minus(CAST('⋯Second(10))─┐
│      1998-06-15 23:59:50 │
└──────────────────────────┘

​
subtractTupleOfIntervals

引入版本：v22.11.0 从日期或日期时间中依次减去一个由时间间隔组成的元组。 语法 
subtractTupleOfIntervals(datetime, intervals)
参数 返回值 返回减去 intervals 后的 date。Date 或 Date32 或 DateTime 或 DateTime64 示例 从日期中减去时间间隔 Tuple
Query
WITH toDate('2018-01-01') AS date SELECT subtractTupleOfIntervals(date, (INTERVAL 1 DAY, INTERVAL 1 YEAR))
Response
┌─subtractTupl⋯alYear(1)))─┐
│               2016-12-31 │
└──────────────────────────┘

​
subtractWeeks

引入版本：v1.1.0 从日期、日期时间，或以字符串编码的日期/日期时间中减去指定的周数。 语法 
subtractWeeks(datetime, num)
参数 返回值 返回 datetime 减去 num 周后的结果。Date 或 Date32 或 DateTime 或 DateTime64 示例 从不同日期类型中减去周数
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 week)
Response
┌─minus(CAST('⋯alWeek(10))─┐
│               1998-04-07 │
└──────────────────────────┘

​
subtractYears

引入版本：v1.1.0 从日期、日期时间或以字符串形式编码的日期或日期时间中减去指定的年数。 语法 
subtractYears(datetime, num)
参数 返回值 返回 datetime 减去 num 年后的值。Date 或 Date32 或 DateTime 或 DateTime64 示例 从不同日期类型中减去年数
Query
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
┌─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 语法
Query
SELECT dateSub('1998-06-16'::Date, INTERVAL 10 year)
Response
┌─minus(CAST('⋯alYear(10))─┐
│               1988-06-16 │
└──────────────────────────┘

​
timeDiff

Introduced in: v23.4.0 返回两个日期或日期时间值之间以秒为单位的差值。 差值按 enddate - startdate 计算。 该函数等同于 dateDiff('second', startdate, enddate)。 如需计算其他单位 (小时、天、月等) 的时间差，请改用 dateDiff 函数。 Syntax 
timeDiff(startdate, enddate)
参数 返回值 返回 enddate 与 startdate 之间的差值，以秒表示。Int64 示例 计算以秒为单位的时间差
Query
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) AS res
Response
┌───res─┐
│ 90000 │
└───────┘
计算时间差并换算为小时
Query
SELECT timeDiff(toDateTime('2018-01-01 22:00:00'), toDateTime('2018-01-02 23:00:00')) / 3600 AS hours
Response
┌─hours─┐
│    25 │
└───────┘
相当于按秒计算的 dateDiff
Query
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
┌─time_diff_result─┬─date_diff_result─┐
│           259200 │           259200 │
└──────────────────┴──────────────────┘

​
timeSlot

Introduced in: v1.1.0 将时间向下舍入到半小时时间间隔的起始时间点。
尽管此函数可以接受扩展类型 Date32 和 DateTime64 的值作为参数， 但如果传入超出正常范围的时间 (Date 为 1970 年至 2149 年 / DateTime 为 2106 年) ，则会产生错误结果。
Syntax 
timeSlot(time[, time_zone])
参数
  • time — 要向下取整到半小时时间间隔起始点的时间。DateTime 或 Date32 或 DateTime64
  • time_zone — 可选。String 类型的常量值，或表示时区的表达式。String
返回值 返回向下取整到半小时时间间隔起始点的时间。DateTime 示例 将时间向下取整到半小时时间间隔
Query
SELECT timeSlot(toDateTime('2000-01-02 03:04:05', 'UTC'))
Response
┌─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 的标度不同。将采用所有给定参数中的最高标度。 语法 
timeSlots(StartTime, Duration[, Size])
参数
  • StartTime — 时间区间的起始时间。DateTime 或 DateTime64
  • Duration — 时间区间的持续时间，以秒为单位。UInt32 或 DateTime64
  • Size — 可选。时间槽的大小，以秒为单位。默认值为 1800 (30 分钟) 。UInt32 或 DateTime64
返回值 返回一个 DateTime/DateTime64 数组 (返回类型与 StartTime 的类型一致) 。对于 DateTime64，返回值的标度可能与 StartTime 的标度不同——将采用所有给定参数中的最高标度。Array(DateTime) 或 Array(DateTime64) 示例 为一个时间区间生成时间槽
Query
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
┌─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) 类型。 如果提供了第二个参数 expr_time，则会将指定时间加到转换后的值上。 语法 
timestamp(expr[, expr_time])
参数
  • expr — 日期或日期时间。String
  • expr_time — 可选。要添加到转换后值的时间。String
返回值 返回 expr 转换后的值，或加上时间后的 expr DateTime64(6) 示例 将日期字符串转换为 DateTime64(6)
Query
SELECT timestamp('2023-12-31') AS ts;
Response
┌─────────────────────────ts─┐
│ 2023-12-31 00:00:00.000000 │
└────────────────────────────┘
为日期字符串添加时间
Query
SELECT timestamp('2023-12-31 12:00:00', '12:00:00.11') AS ts;
Response
┌─────────────────────────ts─┐
│ 2024-01-01 00:00:00.110000 │
└────────────────────────────┘

​
timezone

引入版本：v21.4.0 返回当前会话的时区名称，或者将时区偏移量或时区名称转换为规范的时区名称。 语法 
timezone()
别名: timeZone 参数
  • 无。
返回值 返回规范的时区名称，返回类型为 String 示例 用法示例
Query
SELECT timezone()
Response
┌─timezone()───────┐
│ Europe/Amsterdam │
└──────────────────┘

​
timezoneOf

首次引入于：v21.4.0 返回 DateTime 或 DateTime64 值的时区名称。 语法 
timezoneOf(datetime)
别名: timeZoneOf 参数
  • datetime — 类型为 DateTime 或 DateTime64 的值
  • timezone — 可选。要将 datetime 值转换为的时区名称。String
返回值 返回 datetime 的时区名称。String 示例 使用示例
Query
SELECT timezoneOf(now());
Response
┌─timezoneOf(now())─┐
│ Europe/Amsterdam  │
└───────────────────┘

​
timezoneOffset

Introduced in: v21.6.0 返回相对于 UTC 的时区偏移量，单位为秒。 该函数会将指定日期和时间对应的夏令时以及历史时区变更考虑在内。 Syntax 
timezoneOffset(datetime)
别名: timeZoneOffset 参数 返回值 返回相对于 UTC 的偏移量，单位为秒 Int32 示例 使用示例
Query
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
┌────────────────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) 。 语法 
toDayOfMonth(datetime)
别名：DAY, DAYOFMONTH 参数 返回值 返回给定日期/时间在当月中的第几天，类型为 UInt8 示例 使用示例
Query
SELECT toDayOfMonth(toDateTime('2023-04-21 10:20:30'))
Response
┌─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
语法 
toDayOfWeek(datetime[, mode[, timezone]])
别名: DAYOFWEEK 参数
  • datetime — 用于获取星期几的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64
  • mode — 可选。指定周模式 (0-3) 的整数。省略时默认为 0。UInt8
  • timezone — 可选。转换时使用的时区。String
返回值 返回给定 Date 或 DateTime 对应的星期几。UInt8 示例 使用示例
Query
-- 以下日期为 2023 年 4 月 21 日，是星期五：
SELECT
    toDayOfWeek(toDateTime('2023-04-21')),
    toDayOfWeek(toDateTime('2023-04-21'), 1)
Response
┌─toDayOfWeek(toDateTime('2023-04-21'))─┬─toDayOfWeek(toDateTime('2023-04-21'), 1)─┐
│                                     5 │                                        4 │
└───────────────────────────────────────┴──────────────────────────────────────────┘

​
toDayOfYear

引入版本：v18.4.0 返回 Date 或 DateTime 值在一年中是第几天 (1-366) 。 语法 
toDayOfYear(datetime)
别名: DAYOFYEAR 参数 返回值 返回给定 Date 或 DateTime 是一年中的第几天。UInt16 示例 用法示例
Query
SELECT toDayOfYear(toDateTime('2023-04-21 10:20:30'))
Response
┌─toDayOfYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                            111 │
└────────────────────────────────────────────────┘

​
toDaysInMonth

引入版本：v26.3.0 返回 Date 或 DateTime 所在月份的天数。 返回值范围为 28 到 31。 语法 
toDaysInMonth(datetime)
参数 返回值 返回给定日期/时间所在月份的天数。UInt8 示例 使用示例
Query
SELECT toDaysInMonth(toDate('2023-02-01')), toDaysInMonth(toDate('2024-02-01')), toDaysInMonth(toDate('2023-01-01'))
Response
┌─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 日起，按照 ISO 8601 定义的前推公历 计算所经过的天数。 该计算方式与 MySQL 的 TO_DAYS 函数相同。 语法 
toDaysSinceYearZero(date[, time_zone])
别名: TO_DAYS 参数 返回值 返回自 0000-01-01 以来经过的天数。UInt32 示例 计算自零年起的天数
Query
SELECT toDaysSinceYearZero(toDate('2023-09-08'))
Response
┌─toDaysSinceYearZero(toDate('2023-09-08')))─┐
│                                     713569 │
└────────────────────────────────────────────┘

​
toHour

引入版本：v1.1.0 返回 DateTime 或 DateTime64 值的小时部分 (0-23) 。 语法 
toHour(datetime)
别名: HOUR 参数 返回值 返回 datetime 的小时值 (0-23) 。UInt8 示例 使用示例
Query
SELECT toHour(toDateTime('2023-04-21 10:20:30'))
Response
┌─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 日的第一周。 语法 
toISOWeek(datetime[, timezone])
参数 返回值 根据 ISO 8601 标准返回 ISO 周数。返回 1 到 53 之间的数值。UInt8 示例 获取 ISO 周数
Query
SELECT toDate('2016-12-27') AS date, toISOWeek(date) AS isoWeek
Response
┌───────date─┬─isoWeek─┐
│ 2016-12-27 │      52 │
└────────────┴─────────┘
ISO 周可能属于不同年份
Query
SELECT toDate('2025-12-29') AS date, toISOWeek(date) AS isoWeek, toYear(date) AS year
Response
┌───────date─┬─isoWeek─┬─year─┐
│ 2025-12-29 │       1 │ 2025 │
└────────────┴─────────┴──────┘

​
toISOYear

引入版本：v18.4.0 将日期或日期时间转换为 ISO 年编号。 语法 
toISOYear(datetime)
参数 返回值 返回将输入值转换后的 ISO 年编号。UInt16 示例 从日期值中获取 ISO 年
Query
SELECT
toISOYear(toDate('2024/10/02')) as year1,
toISOYear(toDateTime('2024-10-02 01:30:00')) as year2
Response
┌─week1─┬─week2─┐
│    40 │    40 │
└───────┴───────┘

​
toLastDayOfMonth

引入版本：v1.1.0 将日期或日期时间向上取整到当月的最后一天。
返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。
语法 
toLastDayOfMonth(value)
别名: LAST_DAY 参数 返回值 返回给定日期或日期时间所在月份最后一天对应的日期。Date 示例 向上取整到当月最后一天
Query
SELECT toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))
Response
┌─toLastDayOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-30 │
└─────────────────────────────────────────────────────┘

​
toLastDayOfWeek

Introduced in: v23.5.0 将日期或日期时间向上取整到最近的星期六或星期日。
返回类型可通过设置 enable_extended_results_for_datetime_functions 来配置。
语法 
toLastDayOfWeek(datetime[, mode[, timezone]])
参数
  • datetime — 要转换的日期或日期时间。Date 或 DateTime 或 Date32 或 DateTime64
  • mode — 按 toWeek() 函数中的说明确定一周的第一天。默认值为 0。UInt8
  • timezone — 可选。转换时使用的时区。如果未指定，则使用 server 的时区。String
返回值 根据 mode，返回给定日期当天或之后最近的星期六或星期日对应的日期。Date 或 Date32 示例 向上取整到最近的星期六或星期日
Query
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
行 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) 。 语法 
toMillisecond(datetime)
别名：MILLISECOND 参数 返回值 返回 datetime 所在分钟内的毫秒值 (0 - 59) 。UInt16 示例 使用示例
Query
SELECT toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3));
Response
┌──toMillisecond(toDateTime64('2023-04-21 10:20:30.456', 3))─┐
│                                                        456 │
└────────────────────────────────────────────────────────────┘

​
toMinute

引入版本：v1.1.0 返回 Date 或 DateTime 值的分钟部分 (0-59) 。 语法 
toMinute(datetime)
别名: MINUTE 参数 返回值 返回 datetime 的分钟值 (0 - 59) 。UInt8 示例 使用示例
Query
SELECT toMinute(toDateTime('2023-04-21 10:20:30'))
Response
┌─toMinute(toDateTime('2023-04-21 10:20:30'))─┐
│                                          20 │
└─────────────────────────────────────────────┘

​
toModifiedJulianDay

引入版本：v21.1.0 将文本格式 YYYY-MM-DD 的逆推格里高利历日期转换为 Int32 类型的修正儒略日数值。此函数支持 0000-01-01 到 9999-12-31 范围内的日期。如果参数无法解析为日期，或日期无效，则会引发异常。 语法 
toModifiedJulianDay(date)
参数 返回值 返回修正儒略日数值。Int32 示例 将日期转换为修正儒略日
Query
SELECT toModifiedJulianDay('2020-01-01')
Response
┌─toModifiedJulianDay('2020-01-01')─┐
│                             58849 │
└───────────────────────────────────┘

​
toModifiedJulianDayOrNull

Introduced in：v21.1.0 与 toModifiedJulianDay() 类似，但它不会抛出异常，而是返回 NULL。 Syntax 
toModifiedJulianDayOrNull(date)
参数 返回值 对于有效的 date，返回修正儒略日数；否则返回 null。Nullable(Int32) 示例 将日期转换为修正儒略日，并处理 null 值
Query
SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- 无效日期，返回 NULL
Response
┌─toModifiedJu⋯020-01-01')─┐
│                    58849 │
└──────────────────────────┘
┌─toModifiedJu⋯000-00-00')─┐
│                     ᴺᵁᴸᴸ │
└──────────────────────────┘

​
toMonday

引入版本：v1.1.0 将日期或日期时间向下取整到同一周的周一。返回该日期。
返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。
语法 
toMonday(value)
参数 返回值 返回给定日期或日期时间所在周的周一对应日期。Date 示例 向下舍入到所在周的周一
Query
SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- 星期五
toMonday(toDate('2023-04-24'));              -- 已经是星期一
Response
┌─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) 。 语法 
toMonth(datetime)
别名: MONTH 参数 返回值 返回给定日期/时间中的月份。UInt8 示例 用法示例
Query
SELECT toMonth(toDateTime('2023-04-21 10:20:30'))
Response
┌─toMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                          4 │
└────────────────────────────────────────────┘

​
toMonthNumSinceEpoch

引入版本：v25.3.0 返回自 1970 年起经过的月数 语法 
toMonthNumSinceEpoch(date)
参数 返回值 正整数 示例 示例
Query
SELECT toMonthNumSinceEpoch(toDate('2024-10-01'))
Response
657

​
toQuarter

引入版本：v1.1.0 返回给定 Date 或 DateTime 值所在年份中的季度 (1-4) 。 语法 
toQuarter(datetime)
别名: QUARTER 参数 返回值 返回给定日期/时间所在年份的季度。UInt8 示例 使用示例
Query
SELECT toQuarter(toDateTime('2023-04-21 10:20:30'))
Response
┌─toQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                            2 │
└──────────────────────────────────────────────┘

​
toRelativeDayNum

引入版本：v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的天数。 确切的时间点属于实现细节，因此不应单独使用此函数。 该函数的主要用途是计算两个日期或日期时间之间相差的天数，例如 toRelativeDayNum(dt1) - toRelativeDayNum(dt2)。 语法 
toRelativeDayNum(date)
参数 返回值 返回自过去某个固定参考点起的天数。UInt32 示例 获取相对天数
Query
SELECT toRelativeDayNum(toDate('2023-04-01')) - toRelativeDayNum(toDate('2023-01-01'))
Response
┌─minus(toRela⋯3-01-01')))─┐
│                       90 │
└──────────────────────────┘

​
toRelativeHourNum

引入版本：v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的小时数。 具体的时间点属于实现细节，因此不应单独使用此函数。 此函数的主要用途是计算两个日期或日期时间之间相差的小时数，例如 toRelativeHourNum(dt1) - toRelativeHourNum(dt2)。 语法 
toRelativeHourNum(date)
参数 返回值 返回自过去某个固定参考点起经过的小时数。UInt32 示例 获取相对小时数
Query
SELECT toRelativeHourNum(toDateTime('2023-01-01 12:00:00')) - toRelativeHourNum(toDateTime('2023-01-01 00:00:00')) AS hours_difference
Response
┌─hours_difference─┐
│               12 │
└──────────────────┘

​
toRelativeMinuteNum

自以下版本引入：v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的分钟数。 确切的时间点属于实现细节，因此不应单独使用此函数。 该函数的主要用途是计算两个日期或日期时间之间相差的分钟数，例如：toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)。 语法 
toRelativeMinuteNum(date)
参数 返回值 返回距过去某个固定参考点的分钟数。UInt32 示例 获取相对分钟数
Query
SELECT toRelativeMinuteNum(toDateTime('2023-01-01 00:30:00')) - toRelativeMinuteNum(toDateTime('2023-01-01 00:00:00')) AS minutes_difference
Response
┌─minutes_difference─┐
│                 30 │
└────────────────────┘

​
toRelativeMonthNum

引入版本：v1.1.0 将日期或日期时间转换为自过去某个固定时间点以来经过的月数。 确切的时间点属于实现细节，因此此函数不适合单独使用。 该函数的主要用途是计算两个日期或日期时间之间相差的月数，例如 toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)。 语法 
toRelativeMonthNum(date)
参数 返回值 返回从过去某个固定参考点起算的月份数。UInt32 示例 获取相对月份序号
Query
SELECT toRelativeMonthNum(toDate('2023-04-01')) - toRelativeMonthNum(toDate('2023-01-01')) AS months_difference
Response
┌─months_difference─┐
│                 3 │
└───────────────────┘

​
toRelativeQuarterNum

引入版本：v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的季度数。 确切的时间点属于实现细节，因此不适合单独使用此函数。 此函数的主要用途是计算两个日期或日期时间之间相差的季度数，例如：toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)。 语法 
toRelativeQuarterNum(date)
参数 返回值 返回从过去某个固定参考点起算的季度数。UInt32 示例 获取相对季度编号
Query
SELECT toRelativeQuarterNum(toDate('2023-04-01')) - toRelativeQuarterNum(toDate('2023-01-01')) AS quarters_difference
Response
┌─quarters_difference─┐
│                   1 │
└─────────────────────┘

​
toRelativeSecondNum

Introduced in: v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的秒数。 该确切时间点属于实现细节，因此此函数不适合单独使用。 此函数的主要用途是计算两个日期或日期时间之间相差的秒数，例如 toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)。 Syntax 
toRelativeSecondNum(date)
参数 返回值 返回自过去某个固定参考点起经过的秒数。UInt32 示例 获取相对秒数
Query
SELECT toRelativeSecondNum(toDateTime('2023-01-01 00:01:00')) - toRelativeSecondNum(toDateTime('2023-01-01 00:00:00')) AS seconds_difference
Response
┌─seconds_difference─┐
│                 60 │
└────────────────────┘

​
toRelativeWeekNum

引入版本：v1.1.0 将 date 或 date with time 转换为自过去某个固定时间点起经过的周数。 该确切时间点属于实现细节，因此此函数不适合单独使用。 此函数的主要用途是计算两个日期或日期时间之间相差的周数，例如：toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)。 语法 
toRelativeWeekNum(date)
参数 返回值 返回自过去某个固定参考点以来的周数。UInt32 示例 获取相对周数
Query
SELECT toRelativeWeekNum(toDate('2023-01-08')) - toRelativeWeekNum(toDate('2023-01-01')) AS weeks_difference
Response
┌─weeks_difference─┐
│                1 │
└──────────────────┘

​
toRelativeYearNum

引入版本：v1.1.0 将日期或日期时间转换为自过去某个固定时间点起经过的年数。 确切的时间点属于实现细节，因此不建议单独使用此函数。 此函数的主要用途是计算两个日期或日期时间之间相差的年数，例如 toRelativeYearNum(dt1) - toRelativeYearNum(dt2)。 语法 
toRelativeYearNum(date)
参数 返回值 返回距过去某个固定参考点的年份数。UInt16 示例 获取相对年份数
Query
SELECT toRelativeYearNum('2010-10-01'::DateTime) - toRelativeYearNum('2000-01-01'::DateTime)
Response
┌─minus(toRela⋯ateTime')))─┐
│                       10 │
└──────────────────────────┘

​
toSecond

引入版本：v1.1.0 返回 DateTime 或 DateTime64 值中的秒部分 (0-59) 。 语法 
toSecond(datetime)
别名：SECOND 参数 返回值 返回 datetime 在当前分钟中的秒数 (0 - 59) 。UInt8 示例 用法示例
Query
SELECT toSecond(toDateTime('2023-04-21 10:20:30'))
Response
┌─toSecond(toDateTime('2023-04-21 10:20:30'))─┐
│                                          30 │
└─────────────────────────────────────────────┘

​
toStartOfDay

引入版本：v1.1.0 将日期时间向下取整到当天起始时刻。
返回类型可通过设置 enable_extended_results_for_datetime_functions 来配置。
语法 
toStartOfDay(datetime)
参数
  • datetime — 要向下取整的日期或日期时间。Date 或 DateTime
返回值 返回向下取整到当天开始时刻的日期时间。DateTime 或 DateTime64 示例 向下取整到当天开始时刻
Query
SELECT toStartOfDay(toDateTime('2023-04-21 10:20:30'))
Response
┌─toStartOfDay(toDateTime('2023-04-21 10:20:30'))─┐
│                             2023-04-21 00:00:00 │
└─────────────────────────────────────────────────┘

​
toStartOfFifteenMinutes

引入版本：v1.1.0 将日期时间向下取整到所在十五分钟时间间隔的起始时刻。
返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。
语法 
toStartOfFifteenMinutes(datetime)
参数 返回值 返回取整到最近 15 分钟时间间隔起点的日期时间。DateTime 或 DateTime64 示例 示例
Query
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
行 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 来配置。
Syntax 
toStartOfFiveMinutes(datetime)
别名: toStartOfFiveMinute 参数 返回值 返回向下取整到最近 5 分钟起始时刻的日期时间。DateTime 或 DateTime64 示例 示例
Query
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
行 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 进行配置。
语法 
toStartOfHour(datetime)
参数 返回值 返回向下舍入到整点的日期时间。DateTime 或 DateTime64 示例 向下舍入到整点
Query
SELECT
    toStartOfHour(toDateTime('2023-04-21 10:20:30'));
Response
┌─────────────────res─┬─toTypeName(res)─┐
│ 2023-04-21 10:00:00 │ DateTime        │
└─────────────────────┴─────────────────┘

​
toStartOfISOYear

Introduced in: v1.1.0 将日期或日期时间向下取整到 ISO 年的第一天，该日期可能与普通年份的第一天不同。参见 ISO week date。
返回类型可通过设置 enable_extended_results_for_datetime_functions 来配置。
Syntax 
toStartOfISOYear(value)
参数 返回值 返回给定日期或日期时间所在 ISO 年的第一天。Date 示例 向下取整到 ISO 年的第一天
Query
SELECT toStartOfISOYear(toDateTime('2023-04-21 10:20:30'))
Response
┌─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 年
QUARTER1900 年第 1 季度
MONTH1900 年 1 月
WEEK1970 年第 1 周 (01-05)
DAY1970-01-01
HOUR(*)
MINUTE1970-01-01 00:00:00
SECOND1970-01-01 00:00:00
MILLISECOND1970-01-01 00:00:00
MICROSECOND1970-01-01 00:00:00
NANOSECOND1970-01-01 00:00:00
(*) 小时间隔比较特殊：计算始终以当天的 00:00:00 (午夜) 为基准进行。因此，只有
1 到 23 之间的小时值才有意义。
如果指定了 unit 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 示例 基本时间间隔取整
Query
SELECT toStartOfInterval(toDateTime('2023-01-15 14:30:00'), INTERVAL 1 MONTH)
Response
┌─toStartOfInt⋯alMonth(1))─┐
│               2023-01-01 │
└──────────────────────────┘
使用起点
Query
SELECT toStartOfInterval(toDateTime('2023-01-01 14:45:00'), INTERVAL 1 MINUTE, toDateTime('2023-01-01 14:35:30'))
Response
┌─toStartOfInt⋯14:35:30'))─┐
│      2023-01-01 14:44:30 │
└──────────────────────────┘

​
toStartOfMicrosecond

引入版本：v22.6.0 将日期时间向下取整到微秒开始时刻。 语法 
toStartOfMicrosecond(datetime[, timezone])
参数
  • datetime — 日期和时间。DateTime64
  • timezone — 可选。返回值使用的时区。若未指定，则函数使用 value 参数的时区。String
返回值 带有亚微秒部分的输入值 DateTime64 示例 不带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64);
Response
┌────toStartOfMicrosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999000 │
└───────────────────────────────┘
指定时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMicrosecond(dt64, 'Asia/Istanbul');
Response
┌─toStartOfMicrosecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999999000 │
└─────────────────────────────────────────────┘

​
toStartOfMillisecond

引入版本：v22.6.0 将日期时间向下取整到毫秒的开始时刻。 语法 
toStartOfMillisecond(datetime[, timezone])
参数
  • datetime — 日期和时间。DateTime64
  • timezone — 可选。返回值的时区。若未指定，函数将使用 value 参数的时区。String
返回值 带有亚毫秒精度的输入值。DateTime64 示例 不带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64);
Response
┌────toStartOfMillisecond(dt64)─┐
│ 2020-01-01 10:20:30.999000000 │
└───────────────────────────────┘
指定时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfMillisecond(dt64, 'Asia/Istanbul');
Response
┌─toStartOfMillisecond(dt64, 'Asia/Istanbul')─┐
│               2020-01-01 12:20:30.999000000 │
└─────────────────────────────────────────────┘

​
toStartOfMinute

引入版本：v1.1.0 将日期时间向下取整到该分钟的起始时刻。
返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。
语法 
toStartOfMinute(datetime)
参数 返回值 返回向下取整到该分钟开始时刻的日期时间。DateTime 或 DateTime64 示例 向下取整到该分钟开始时刻
Query
SELECT
    toStartOfMinute(toDateTime('2023-04-21 10:20:30')),
    toStartOfMinute(toDateTime64('2023-04-21 10:20:30.5300', 8))
FORMAT Vertical
Response
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 来配置。
语法 
toStartOfMonth(value)
参数 返回值 返回给定日期或日期时间所在月份的第一天。Date 示例 向下取整到当月第一天
Query
SELECT toStartOfMonth(toDateTime('2023-04-21 10:20:30'))
Response
┌─toStartOfMonth(toDateTime('2023-04-21 10:20:30'))─┐
│                                        2023-04-01 │
└───────────────────────────────────────────────────┘

​
toStartOfNanosecond

引入版本：v22.6.0 将日期时间向下取整到纳秒的起始时刻。 语法 
toStartOfNanosecond(datetime[, timezone])
参数
  • datetime — 日期和时间。DateTime64
  • timezone — 可选。返回值的时区。如果未指定，则该函数使用 value 参数的时区。String
返回值 带纳秒的输入值。DateTime64 示例 不带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64);
Response
┌─────toStartOfNanosecond(dt64)─┐
│ 2020-01-01 10:20:30.999999999 │
└───────────────────────────────┘
带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999999999', 9) AS dt64
SELECT toStartOfNanosecond(dt64, 'Asia/Istanbul');
Response
┌─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 来配置。
语法 
toStartOfQuarter(value)
参数 返回值 返回给定日期或日期时间所在季度的第一天。Date 示例 向下取整到所在季度的第一天
Query
SELECT toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))
Response
┌─toStartOfQuarter(toDateTime('2023-04-21 10:20:30'))─┐
│                                          2023-04-01 │
└─────────────────────────────────────────────────────┘

​
toStartOfSecond

引入版本：v20.5.0 将日期时间向下取整到秒的起始时刻。 语法 
toStartOfSecond(datetime[, timezone])
参数
  • datetime — 要截去子秒部分的日期和时间。DateTime64
  • timezone — 可选。返回值使用的时区。若未指定，函数将使用参数 value 的时区。String
返回值 返回去除子秒部分后的输入值。DateTime64 示例 不带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64);
Response
┌───toStartOfSecond(dt64)─┐
│ 2020-01-01 10:20:30.000 │
└─────────────────────────┘
带时区的查询
Query
WITH toDateTime64('2020-01-01 10:20:30.999', 3) AS dt64
SELECT toStartOfSecond(dt64, 'Asia/Istanbul');
Response
┌─toStartOfSecond(dt64, 'Asia/Istanbul')─┐
│                2020-01-01 13:20:30.000 │
└────────────────────────────────────────┘

​
toStartOfTenMinutes

引入版本：v20.1.0 将日期时间向下取整到最近一个十分钟时间间隔的起始时刻。
返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。
语法 
toStartOfTenMinutes(datetime)
参数 返回值 返回舍入到最近 10 分钟时间间隔起始时刻的日期时间。DateTime 或 DateTime64 示例 示例
Query
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
行 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 来配置返回类型。
语法 
toStartOfWeek(datetime[, mode[, timezone]])
参数
  • datetime — 要转换的日期或日期时间。Date 或 DateTime 或 Date32 或 DateTime64
  • mode — 按 toWeek() 函数中的说明确定每周的第一天。默认值为 0。UInt8
  • timezone — 转换时使用的时区。如果未指定，则使用服务器的时区。String
返回值 根据 mode，返回给定日期当天或之前最近的星期日或星期一对应的日期。Date 或 Date32 示例 向下取整到最近的星期日或星期一
Query
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
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 来配置。
语法 
toStartOfYear(value)
参数 返回值 返回给定日期/时间所在年份的第一天。Date 示例 向下取整到该年的第一天
Query
SELECT toStartOfYear(toDateTime('2023-04-21 10:20:30'))
Response
┌─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 
toTimeWithFixedDate(date[, timezone])
参数 返回值 以相对于某个固定时间点的偏移量形式，返回日期或日期时间值中的时间部分 (当前固定时间点为 1970-01-02) 。DateTime 示例 计算两个日期之间的时间差
Query
SELECT toTimeWithFixedDate('2025-06-15 12:00:00'::DateTime) - toTimeWithFixedDate('2024-05-10 11:00:00'::DateTime) AS result, toTypeName(result)
Response
┌─result─┬─toTypeName(result)─┐
│   3600 │ Int32              │
└────────┴────────────────────┘

​
toTimezone

自 v1.1.0 引入 将 DateTime 或 DateTime64 转换为指定的时区。 数据的内部值 (Unix 秒数) 不会改变。 只有该值的时区属性和字符串表示形式会发生变化。 语法 
toTimezone(datetime, timezone)
别名: toTimeZone 参数 返回值 返回与输入相同的时间戳，但时区为指定时区。DateTime 或 DateTime64 示例 使用示例
Query
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
行 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 及类似框架。 语法 
toUTCTimestamp(datetime, time_zone)
别名: to_utc_timestamp 参数
  • datetime — 日期或日期时间类型的常量值或表达式。DateTime 或 DateTime64
  • time_zone — 表示时区的 String 类型常量值或表达式。String
返回值 返回 UTC 时区的日期或日期时间。DateTime 或 DateTime64 示例 转换为 UTC 时区
Query
SELECT toUTCTimestamp(toDateTime('2023-03-16'), 'Asia/Shanghai')
Response
┌─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 起的秒数) 。 语法 
toUnixTimestamp(date[, timezone])
参数 返回值 返回 Unix 时间戳。UInt32 示例 使用示例
Query
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
行 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(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，格式需受 parseDateTime64BestEffort() 支持。支持字符串参数仅是为了兼容 MySQL，因为某些第三方工具依赖这种行为。由于未来对字符串参数的支持可能会取决于新的 MySQL 兼容性设置，而且字符串解析通常较慢，因此建议不要使用这种方式。 语法 
toWeek(datetime[, mode[, time_zone]])
别名: week 参数
  • datetime — 要获取其周数的日期或日期时间值。Date 或 DateTime
  • mode — 可选。取值范围为 0 到 9，用于确定每周的第一天以及周数的取值范围。默认值为 0。 - time_zone — 可选。时区。String
返回值 根据指定的模式返回周数。UInt32 示例 获取不同模式下的周数
Query
SELECT toDate('2016-12-27') AS date, toWeek(date) AS week0, toWeek(date,1) AS week1, toWeek(date,9) AS week9
Response
┌───────date─┬─week0─┬─week1─┬─week9─┐
│ 2016-12-27 │    52 │    52 │     1 │
└────────────┴───────┴───────┴───────┘

​
toYYYYMM

引入版本：v1.1.0 将日期或日期时间转换为包含年份和月份数字 (YYYY * 100 + MM) 的 UInt32 数值。 接受第二个可选的时区参数；如果提供，该时区必须是字符串常量。 此函数与函数 YYYYMMDDToDate() 相反。 语法 
toYYYYMM(datetime[, timezone])
参数
  • datetime — 要转换的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64
  • timezone — 可选。用于转换的时区。如果提供，时区必须为字符串常量。String
返回值 返回一个 UInt32 数值，其中包含年份和月份 (YYYY * 100 + MM) 。UInt32 示例 将当前日期转换为 YYYYMM 格式
Query
SELECT toYYYYMM(now(), 'US/Eastern')
Response
┌─toYYYYMM(now(), 'US/Eastern')─┐
│                        202303 │
└───────────────────────────────┘

​
toYYYYMMDD

引入版本：v1.1.0 将日期或日期时间转换为一个包含年、月、日数字 (YYYY * 10000 + MM * 100 + DD) 的 UInt32 数值。接受第二个可选的时区参数；如果提供，该时区必须是字符串常量。 语法 
toYYYYMMDD(datetime[, timezone])
参数
  • datetime — 要转换的日期或日期时间值。Date 或 Date32 或 DateTime 或 DateTime64
  • timezone — 可选。转换时使用的时区。如提供，该时区必须是字符串常量。String
返回值 返回一个 UInt32 数值，包含年、月、日 (YYYY * 10000 + MM * 100 + DD) 。UInt32 示例 将当前日期转换为 YYYYMMDD 格式
Query
SELECT toYYYYMMDD(now(), 'US/Eastern')
Response
┌─toYYYYMMDD(now(), 'US/Eastern')─┐
│                        20230302 │
└─────────────────────────────────┘

​
toYYYYMMDDhhmmss

引入版本：v1.1.0 将日期或日期时间转换为 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 格式
Query
SELECT toYYYYMMDDhhmmss(now(), 'US/Eastern')
Response
┌─toYYYYMMDDhhmmss(now(), 'US/Eastern')─┐
│                        20230302112209 │
└───────────────────────────────────────┘

​
toYear

引入版本：v1.1.0 返回 Date 或 DateTime 值的年份部分 (公元) 。 语法 
toYear(datetime)
别名: YEAR 参数 返回值 返回给定 Date 或 DateTime 的年份，类型为 UInt16 示例 使用示例
Query
SELECT toYear(toDateTime('2023-04-21 10:20:30'))
Response
┌─toYear(toDateTime('2023-04-21 10:20:30'))─┐
│                                     2023  │
└───────────────────────────────────────────┘

​
toYearNumSinceEpoch

引入版本：v25.3.0 返回自 1970 年以来经过的年数 语法 
toYearNumSinceEpoch(date)
参数 返回值 正整数 示例 示例
Query
SELECT toYearNumSinceEpoch(toDate('2024-10-01'))
Response
54

​
toYearWeek

引入版本：v20.1.0 返回日期对应的年份和周数。对于一年中的第一周和最后一周，结果中的年份可能与日期参数中的年份不同。 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 示例 获取不同模式下的年份-周数组合
Query
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
┌───────date─┬─yearWeek0─┬─yearWeek1─┬─yearWeek9─┬─prev_yearWeek─┐
│ 2016-12-27 │    201652 │    201652 │    201701 │        202152 │
└────────────┴───────────┴───────────┴───────────┴───────────────┘

​
today

于 v1.1.0 中引入 返回查询分析时刻的当前日期。等同于 toDate(now())。 语法 
today()
别名：curdate, current_date 参数
  • 无。
返回值 返回当前日期 Date 示例 用法示例
Query
SELECT today() AS today, curdate() AS curdate, current_date() AS current_date FORMAT Pretty
Response
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-03 │ 2025-03-03 │   2025-03-03 │
└────────────┴────────────┴──────────────┘
不使用括号的 SQL 标准语法
Query
SELECT TODAY, CURDATE,CURRENT_DATE
Response
┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      TODAY ┃    CURDATE ┃ CURRENT_DATE ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2025-03-04 │ 2025-03-04 │   2025-03-04 │
└────────────┴────────────┴──────────────┘

​
yesterday

引入版本：v1.1.0 不接受任何参数，并返回查询分析过程中某一时刻的昨天日期。 语法 
yesterday()
参数
  • 无。
返回值 返回昨天的日期。Date 示例 获取昨天的日期
Query
SELECT yesterday();
SELECT today() - 1;
Response
┌─yesterday()─┐
│  2025-06-09 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2025-06-09 │
└───────────────────┘
最后修改于 2026年6月10日