日期和时间处理函数

日期和时间处理函数文档

本节中的大多数函数都接受可选的时区参数，例如 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、LOCALTIME、LOCALTIMESTAMP、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)

参数

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

返回值

根据给定参数返回一个 Date 值 Date

示例

示例

Query

SELECT YYYYMMDDToDate(20230911);

Response

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

​

YYYYMMDDToDate32

引入版本：v23.9.0

将包含年、月、日的数值转换为 Date32。 此函数与 toYYYYMMDD() 函数相反。 如果输入未编码为有效的 Date32 值，则输出结果未定义。

语法

YYYYMMDDToDate32(YYYYMMDD)

参数

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

返回值

返回由给定参数生成的 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 YYYYMMDDhhmmssToDateTime(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

┌─YYYYMMDDhhmmssToDateTime64(20230911131415, 3, 'Asia/Istanbul')─┐
│                                        2023-09-11 13:14:15.000 │
└────────────────────────────────────────────────────────────────┘

​

addDate

引入版本：v23.9.0

将时间间隔加到给定的日期、日期时间，或以字符串编码的日期或日期时间上。 如果相加后的值超出该数据类型的取值范围，则结果未定义。

语法

addDate(datetime, interval)

参数

• datetime — 要添加 interval 的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• interval — 要添加的时间间隔。Interval

返回值

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

示例

为日期添加时间间隔

Query

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

Response

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

​

addDays

引入版本：v1.1.0

为日期、日期时间，或以字符串编码的日期或日期时间增加指定天数。

语法

addDays(datetime, num)

参数

• datetime — 要在其基础上增加指定天数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要增加的天数。(U)Int* 或 Float*

返回值

返回 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('1998-06-16', 'Date'), toIntervalDay(10))─┐
│                                          1998-06-26 │
└─────────────────────────────────────────────────────┘

​

addHours

引入版本：v1.1.0

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

语法

addHours(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalHour(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)

参数

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

返回值

返回 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('1998-06-16', 'DateTime'), toIntervalMicrosecond(10))─┐
│                                      1998-06-16 00:00:00.000010 │
└─────────────────────────────────────────────────────────────────┘

​

addMilliseconds

版本引入：v22.6.0

为日期时间或以字符串编码的日期时间添加指定的毫秒数。

语法

addMilliseconds(datetime, num)

参数

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

返回值

返回加上 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('1998-06-16', 'DateTime'), toIntervalMillisecond(10))─┐
│                                         1998-06-16 00:00:00.010 │
└─────────────────────────────────────────────────────────────────┘

​

addMinutes

引入版本：v1.1.0

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

语法

addMinutes(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalMinute(10))─┐
│                                    1998-06-16 00:10:00 │
└────────────────────────────────────────────────────────┘

​

addMonths

引入版本：v1.1.0

为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的月份。

语法

addMonths(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalMonth(10))─┐
│                                            1999-04-16 │
└───────────────────────────────────────────────────────┘

​

addNanoseconds

引入版本：v22.6.0

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

语法

addNanoseconds(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'DateTime'), toIntervalNanosecond(1000))─┐
│                                    1998-06-16 00:00:00.000001000 │
└──────────────────────────────────────────────────────────────────┘

​

addQuarters

引入版本：v20.1.0

为日期、日期时间或以字符串编码的日期或日期时间增加指定数量的季度。

语法

addQuarters(datetime, num)

参数

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

返回值

返回在 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('1998-06-16', 'Date'), toIntervalQuarter(10))─┐
│                                              2000-12-16 │
└─────────────────────────────────────────────────────────┘

​

addSeconds

首次引入于：v1.1.0

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

语法

addSeconds(datetime, num)

参数

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

返回值

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

┌─plus(CAST('1998-06-16', 'Date'), toIntervalSecond(10))─┐
│                                    1998-06-16 00:00:10 │
└────────────────────────────────────────────────────────┘

​

addTupleOfIntervals

引入版本：v22.11.0

将一个时间间隔 Tuple 依次添加到日期或日期时间中。

语法

addTupleOfIntervals(datetime, intervals)

参数

• datetime — 要添加时间间隔的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64
• intervals — 要添加到 datetime 的时间间隔 Tuple。Tuple(Interval)

返回值

返回加上 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 — 要添加指定周数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要添加的周数。(U)Int* 或 Float*

返回值

返回 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('1998-06-16', 'Date'), toIntervalWeek(10))─┐
│                                           1998-08-25 │
└──────────────────────────────────────────────────────┘

​

addYears

引入于：v1.1.0

为日期、日期时间或字符串编码的日期/日期时间增加指定的年数。

语法

addYears(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalYear(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 — 结果的时间间隔类型。

单位	可能的值
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

返回值

返回以 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
• value — 新值。(U)Int*

返回值

返回与 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 — 要更改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回一个与 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 — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回一个与 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
• value — 新值。(U)Int*

返回值

返回与 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 — 要修改的值。Date 或 Date32 或 DateTime 或 DateTime64
• value — 新值。(U)Int*

返回值

返回与 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
• value — 新值。(U)Int*

返回值

返回一个与 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 — 结果所使用的时间间隔类型。

单位	可能的值
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

示例

按小时计算日期差值

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

参数

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

返回值

返回指定的日期部分。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 Argument	datetime Argument	Return Type
Year, Quarter, Month, Week	Date32 or DateTime64 or Date or DateTime	Date32 or Date
Day, Hour, Minute, Second	Date32, DateTime64, Date, or DateTime	DateTime64 or DateTime
Millisecond, Microsecond,	Any	DateTime64
Nanosecond		with 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/%y	01/02/18
%e	一个月中的第几天，左侧补空格 (1-31)	2
%f	秒的小数部分	123456
%F	短格式 YYYY-MM-DD 日期，等同于 %Y-%m-%d	2018-01-02
%g	两位数年份格式，与 ISO 8601 对齐	18
%G	用于 ISO 周数的四位数年份格式	2018
%h	12 小时制小时 (01-12)	09
%H	24 小时制小时 (00-23)	22
%i	分钟 (00-59)	33
%I	12 小时制小时 (01-12)	10
%j	一年中的第几天 (001-366)	002
%k	24 小时制小时 (00-23)	14
%l	12 小时制小时 (01-12)	09
%m	以整数表示的月份 (01-12)	01
%M	完整月份名称 (January-December)	January
%n	换行符
%p	AM 或 PM 标记	PM
%Q	季度 (1-4)	1
%r	12 小时制 HH:MM AM/PM 时间，等同于 %h:%i %p	10:30 PM
%R	24 小时制 HH:MM 时间，等同于 %H:%i	22:33
%s	秒 (00-59)	44
%S	秒 (00-59)	44
%t	水平制表符
%T	ISO 8601 时间格式 (HH:MM:SS) ，等同于 %H:%i:%S	22:33:44
%u	ISO 8601 星期数字表示，周一为 1 (1-7)	2
%V	ISO 8601 周数 (01-53)	01
%w	以整数表示的星期几，周日为 0 (0-6)	2
%W	完整星期名称 (Monday-Sunday)	Monday
%y	年份后两位 (00-99)	18
%Y	年份	2018
%z	相对于 UTC 的时间偏移，格式为 +HHMM 或 -HHMM	-0500
%%	% 符号	%

• 在早于 v23.4 的 ClickHouse 版本中，如果格式化的值是 Date、Date32、DateTime (它们不包含秒的小数部分) 或 precision 为 0 的 DateTime64，%f 会输出单个零 (0) 。
• 在早于 v25.1 的 ClickHouse 版本中，%f 输出的位数会与 DateTime64 的 标度 指定的位数一致，而不是固定为 6 位。
• 在早于 v23.4 的 ClickHouse 版本中，%M 输出的是分钟 (00-59) ，而不是完整月份名称 (January-December) 。

语法

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')─┐
│ 123456                                                              │
└─────────────────────────────────────────────────────────────────────┘

按时区格式化

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); -- invalid argument, returns NULL

Response

┌─fromModifiedJulianDayOrNull(58849)─┐
│ 2020-01-01                         │
└────────────────────────────────────┘
┌─fromModifiedJulianDayOrNull(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 时间戳转换为日历日期和一天中的时间。

它有两种调用方式：

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

语法

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 02:58:55 │
└──────────────────────────────┘

按格式转换 Unix 时间戳

Query

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

Response

┌─DateTime────────────┐
│ 2009-02-11 06: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 │
└─────────────────────┘

​

localtime

在 v26.7.0 中引入

返回在查询分析时刻，服务器 (或会话) 时区中的当前时间。 该函数是一个常量表达式。它是符合 SQL 标准 / PostgreSQL 的 LOCALTIME，等价于 CAST(now() AS Time)。

此函数是非确定性的：对于相同的参数，它可能返回不同的结果。

语法

localtime()

参数

• 无。

返回值

返回当前时间。Time

示例

不带括号的 SQL 标准语法

Query

SELECT LOCALTIME

Response

┌───────LOCALTIME─┐
│        07:42:09 │
└─────────────────┘

​

makeDate

版本引入：v22.6.0

根据以下任一输入创建 Date：

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

语法

makeDate(year, month, day)
makeDate(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

返回值

返回一个根据给定参数构造的 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)

参数

• 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

示例

由年、月、日构造 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])

参数

• 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

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

参数

• 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

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)

参数

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

返回值

返回月份名称。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])

别名: localtimestamp, 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()─┐
│ Etc/UTC          │
└──────────────────┘

​

subDate

引入版本：v23.9.0

从给定的日期、日期时间，或以字符串编码的日期或日期时间中减去时间间隔。 如果相减后的值超出该数据类型的取值范围，则结果未定义。

语法

subDate(datetime, interval)

参数

• datetime — 要从中减去 interval 的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64
• interval — 要减去的时间间隔。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 — 要从中减去指定天数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64 或 String
• num — 要减去的天数。(U)Int* 或 Float*

返回值

返回 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('1998-06-16', 'Date'), toIntervalDay(10))─┐
│                                           1998-06-06 │
└──────────────────────────────────────────────────────┘

​

subtractHours

引入版本：v1.1.0

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

语法

subtractHours(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalHour(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 — 要减去指定微秒数的日期时间。DateTime 或 DateTime64 或 String
• num — 要减去的微秒数。(U)Int* 或 Float*

返回值

返回 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('1998-06-16', 'DateTime'), toIntervalMicrosecond(10))─┐
│                                       1998-06-15 23:59:59.999990 │
└──────────────────────────────────────────────────────────────────┘

​

subtractMilliseconds

引入版本：v22.6.0

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

语法

subtractMilliseconds(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'DateTime'), toIntervalMillisecond(10))─┐
│                                          1998-06-15 23:59:59.990 │
└──────────────────────────────────────────────────────────────────┘

​

subtractMinutes

引入版本：v1.1.0

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

语法

subtractMinutes(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalMinute(10))─┐
│                                     1998-06-15 23:50:00 │
└─────────────────────────────────────────────────────────┘

​

subtractMonths

引入版本：v1.1.0

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

语法

subtractMonths(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalMonth(10))─┐
│                                             1997-08-16 │
└────────────────────────────────────────────────────────┘

​

subtractNanoseconds

自 v20.1.0 起引入

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

语法

subtractNanoseconds(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'DateTime'), toIntervalNanosecond(10))─┐
│                                   1998-06-15 23:59:59.999999990 │
└─────────────────────────────────────────────────────────────────┘

​

subtractQuarters

引入版本：v20.1.0

从日期、日期时间或以字符串编码的日期或日期时间中减去指定数量的季度。

语法

subtractQuarters(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalQuarter(10))─┐
│                                               1995-12-16 │
└──────────────────────────────────────────────────────────┘

​

subtractSeconds

引入版本：v1.1.0

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

语法

subtractSeconds(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalSecond(10))─┐
│                                     1998-06-15 23:59:50 │
└─────────────────────────────────────────────────────────┘

​

subtractTupleOfIntervals

引入版本：v22.11.0

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

语法

subtractTupleOfIntervals(datetime, intervals)

参数

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

返回值

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

┌─subtractTupleOfIntervals(date, (toIntervalDay(1), toIntervalYear(1)))─┐
│                                                            2016-12-31 │
└───────────────────────────────────────────────────────────────────────┘

​

subtractWeeks

引入版本：v1.1.0

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

语法

subtractWeeks(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalWeek(10))─┐
│                                            1998-04-07 │
└───────────────────────────────────────────────────────┘

​

subtractYears

引入版本：v1.1.0

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

语法

subtractYears(datetime, num)

参数

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

返回值

返回 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('1998-06-16', 'Date'), toIntervalYear(10))─┐
│                                            1988-06-16 │
└───────────────────────────────────────────────────────┘

​

timeDiff

Introduced in: v23.4.0

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

该函数等同于 dateDiff('second', startdate, enddate)。

如需计算其他单位 (小时、天、月等) 的时间差，请改用 dateDiff 函数。

Syntax

timeDiff(startdate, enddate)

参数

• startdate — 第一个被相减的时间值 (减数) 。Date 或 Date32 或 DateTime 或 DateTime64
• enddate — 第二个时间值，即从中减去 startdate 的值 (被减数) 。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回 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())─┐
│ Etc/UTC           │
└───────────────────┘

​

timezoneOffset

Introduced in: v21.6.0

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

Syntax

timezoneOffset(datetime)

别名: timeZoneOffset

参数

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

返回值

返回相对于 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

参数

• datetime — 要从中获取一个月中第几天的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间在当月中的第几天，类型为 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

参数

• datetime — 用于获取一年中第几天的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定 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)

参数

• datetime — 日期或日期时间，用于获取其所在月份的天数。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间所在月份的天数。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

参数

• date — 要计算自零年起经过天数的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64
• time_zone — 时区。String

返回值

返回自 0000-01-01 以来经过的天数。UInt32

示例

计算自零年起的天数

Query

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

Response

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

​

toHour

引入版本：v1.1.0

返回 DateTime 或 DateTime64 值的小时部分 (0-23) 。

语法

toHour(datetime)

别名: HOUR

参数

• datetime — 要提取小时的日期时间。DateTime 或 DateTime64

返回值

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

参数

• datetime — 用于获取 ISO 周数的日期或日期时间。Date 或 DateTime 或 Date32 或 DateTime64
• timezone — 可选。时区。String

返回值

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

参数

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

返回值

返回将输入值转换后的 ISO 年编号。UInt16

示例

从日期值中获取 ISO 年

Query

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

Response

┌─year1─┬─year2─┐
│  2024 │  2024 │
└───────┴───────┘

​

toLastDayOfMonth

引入版本：v1.1.0

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

返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。

语法

toLastDayOfMonth(value)

别名: LAST_DAY

参数

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

返回值

返回给定日期或日期时间所在月份最后一天对应的日期。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')), /* a Friday */
    toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
    toLastDayOfWeek(toDate('2023-04-23')), /* a Sunday */
    toLastDayOfWeek(toDate('2023-04-23'), 1) /* a Sunday */
FORMAT Vertical

Response

Row 1:
──────
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30')):    2023-04-22
toLastDayOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-23
toLastDayOfWeek(toDate('2023-04-23')):                 2023-04-29
toLastDayOfWeek(toDate('2023-04-23'), 1):              2023-04-23

​

toMicrosecond

引入版本：v25.7.0

返回 DateTime64 值的微秒部分 (0-999999) 。

语法

toMicrosecond(datetime)

别名: MICROSECOND

参数

• datetime — 要提取微秒的日期时间。DateTime64

返回值

返回 datetime 中当前秒内的微秒值 (0 - 999999) 。UInt32

示例

用法示例

Query

SELECT toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6));

Response

┌─toMicrosecond(toDateTime64('2023-04-21 10:20:30.456789', 6))─┐
│                                                       456789 │
└──────────────────────────────────────────────────────────────┘

​

toMillisecond

引入版本：v24.2.0

返回 DateTime 或 DateTime64 值中的毫秒部分 (0-999) 。

语法

toMillisecond(datetime)

别名：MILLISECOND

参数

• datetime — 要提取毫秒部分的日期时间。DateTime 或 DateTime64

返回值

返回 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 — 要提取分钟的日期时间值。DateTime 或 DateTime64

返回值

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

参数

• date — String 格式的日期。String 或 FixedString

返回值

返回修正儒略日数值。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 — 文本形式的日期。String 或 FixedString

返回值

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

示例

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

Query

SELECT toModifiedJulianDayOrNull('2020-01-01');
SELECT toModifiedJulianDayOrNull('0000-00-00'); -- invalid date, returns NULL

Response

┌─toModifiedJulianDayOrNull('2020-01-01')─┐
│                                   58849 │
└─────────────────────────────────────────┘
┌─toModifiedJulianDayOrNull('0000-00-00')─┐
│                                    ᴺᵁᴸᴸ │
└─────────────────────────────────────────┘

​

toMonday

引入版本：v1.1.0

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

返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。

语法

toMonday(value)

参数

• value — 要向下舍入到所在周周一的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期或日期时间所在周的周一对应日期。Date

示例

向下舍入到所在周的周一

Query

SELECT
toMonday(toDateTime('2023-04-21 10:20:30')), -- A Friday
toMonday(toDate('2023-04-24'));              -- Already a Monday

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

参数

• datetime — 用于提取月份的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间中的月份。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)

参数

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

返回值

正整数

示例

示例

Query

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

Response

657

​

toNanosecond

首次引入于：v25.7.0

返回 DateTime64 值中的纳秒分量 (0-999999999) 。

语法

toNanosecond(datetime)

别名: NANOSECOND

参数

• datetime — 要从中提取纳秒的日期时间。DateTime64

返回值

返回 datetime 中当前秒内的纳秒值 (0 - 999999999) 。UInt32

示例

使用示例

Query

SELECT toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9));

Response

┌─toNanosecond(toDateTime64('2023-04-21 10:20:30.123456789', 9))─┐
│                                                      123456789 │
└────────────────────────────────────────────────────────────────┘

​

toQuarter

引入版本：v1.1.0

返回给定 Date 或 DateTime 值所在年份中的季度 (1-4) 。

语法

toQuarter(datetime)

别名: QUARTER

参数

• datetime — 用于获取所在年份季度的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定日期/时间所在年份的季度。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)

参数

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

返回值

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

示例

获取相对天数

Query

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

Response

┌─minus(toRelativeDayNum(toDate('2023-04-01')), toRelativeDayNum(toDate('2023-01-01')))─┐
│                                                                                    90 │
└───────────────────────────────────────────────────────────────────────────────────────┘

​

toRelativeHourNum

引入版本：v1.1.0

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

语法

toRelativeHourNum(date)

参数

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

返回值

返回自过去某个固定参考点起经过的小时数。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)

参数

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

返回值

返回距过去某个固定参考点的分钟数。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)

参数

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

返回值

返回从过去某个固定参考点起算的月份数。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)

参数

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

返回值

返回从过去某个固定参考点起算的季度数。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)

参数

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

返回值

返回自过去某个固定参考点起经过的秒数。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)

参数

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

返回值

返回自过去某个固定参考点以来的周数。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)

参数

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

返回值

返回距过去某个固定参考点的年份数。UInt16

示例

获取相对年份数

Query

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

Response

┌─minus(toRelativeYearNum(CAST('2010-10-01', 'DateTime')), toRelativeYearNum(CAST('2000-01-01', 'DateTime')))─┐
│                                                                                                          10 │
└─────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

​

toSecond

引入版本：v1.1.0

返回 DateTime 或 DateTime64 值中的秒部分 (0-59) 。

语法

toSecond(datetime)

别名：SECOND

参数

• datetime — 要提取秒数的日期时间。DateTime 或 DateTime64

返回值

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

参数

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

返回值

返回取整到最近 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

Row 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

参数

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

返回值

返回向下取整到最近 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

Row 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 — 要取整的日期时间。DateTime 或 DateTime64

返回值

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

示例

向下取整到整点

Query

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

Response

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

​

toStartOfISOYear

Introduced in: v1.1.0

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

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

Syntax

toStartOfISOYear(value)

参数

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

返回值

返回给定日期或日期时间所在 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 年
QUARTER	1900 年第 1 季度
MONTH	1900 年 1 月
WEEK	1970 年第 1 周 (01-05)
DAY	1970-01-01
HOUR	(*)
MINUTE	1970-01-01 00:00:00
SECOND	1970-01-01 00:00:00
MILLISECOND	1970-01-01 00:00:00
MICROSECOND	1970-01-01 00:00:00
NANOSECOND	1970-01-01 00:00:00
(*) 小时间隔比较特殊：计算始终以当天的 00:00:00 (午夜) 为基准进行。因此，只有
1 到 23 之间的小时值才有意义。

如果指定了 unit WEEK，toStartOfInterval 会假定每周从星期一开始。请注意，这一行为与函数 toStartOfWeek 不同，后者默认每周从星期日开始。

第二种重载分别模拟了 TimescaleDB 的 time_bucket() 函数和 PostgreSQL 的 date_bin() 函数。

语法

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

别名: date_bin, time_bucket

参数

• 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

┌─toStartOfInterval(toDateTime('2023-01-15 14:30:00'), toIntervalMonth(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

┌─toStartOfInterval(toDateTime('2023-01-01 14:45:00'), toIntervalMinute(1), toDateTime('2023-01-01 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 13: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 13:20:30.999000000 │
└─────────────────────────────────────────────┘

​

toStartOfMinute

引入版本：v1.1.0

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

返回类型可通过设置 enable_extended_results_for_datetime_functions 进行配置。

语法

toStartOfMinute(datetime)

参数

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

返回值

返回向下取整到该分钟开始时刻的日期时间。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)

参数

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

返回值

返回给定日期或日期时间所在月份的第一天。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 13: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)

参数

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

返回值

返回给定日期或日期时间所在季度的第一天。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)

参数

• datetime — 日期时间。DateTime 或 DateTime64

返回值

返回舍入到最近 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

Row 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')), /* a Friday */
        toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1), /* a Friday */
        toStartOfWeek(toDate('2023-04-24')), /* a Monday */
        toStartOfWeek(toDate('2023-04-24'), 1) /* a Monday */
    FORMAT Vertical

Response

Row 1:
──────
toStartOfWeek(toDateTime('2023-04-21 10:20:30')):    2023-04-16
toStartOfWeek(toDateTime('2023-04-21 10:20:30'), 1): 2023-04-17
toStartOfWeek(toDate('2023-04-24')):                 2023-04-23
toStartOfWeek(toDate('2023-04-24'), 1):              2023-04-24

​

toStartOfYear

引入版本：v1.1.0

将日期或日期时间向下取整到当年的第一天。返回值为 Date 对象。

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

语法

toStartOfYear(value)

参数

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

返回值

返回给定日期/时间所在年份的第一天。Date

示例

向下取整到该年的第一天

Query

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

Response

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

​

toTimeWithFixedDate

引入版本：v25.5.0

提取日期时间的时间部分。 返回结果是相对于固定时间点的偏移量，该时间点目前为 1970-01-02； 但确切的时间点属于实现细节，未来可能会变更。

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

这是旧版 toTime 函数，因名称 toTime 现已被 toTime 占用而在 v25.5 中更名；该函数会将值转换为 Time 数据类型。 启用设置 use_legacy_to_time 后，仍可通过旧名称 toTime 访问该函数 (自 v26.7 起默认值为 0，而在 v25.6 至 v26.6 期间默认值为 1) 。

如果 datetime 参数包含亚秒部分，返回的 DateTime 值会舍弃这些部分，精度为秒。

语法

toTimeWithFixedDate(datetime[, timezone])

参数

• datetime — 要转换为时间的日期时间。DateTime 或 DateTime64
• timezone — 可选。返回值的时区。String

返回值

以相对于固定时间点 (目前为 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              │
└────────┴────────────────────┘

将丢弃亚秒部分

Query

SELECT toTimeWithFixedDate(toDateTime64('1970-12-10 01:20:30.3000', 3)) AS result, toTypeName(result)

Response

┌──────────────result─┬─toTypeName(result)─┐
│ 1970-01-02 01:20:30 │ DateTime           │
└─────────────────────┴────────────────────┘

以 legacy 名称调用的同一函数

Query

SET use_legacy_to_time = 1;
SELECT toTime(toDateTime64('1970-12-10 01:20:30.3000', 3)) AS result, toTypeName(result)

Response

┌──────────────result─┬─toTypeName(result)─┐
│ 1970-01-02 01:20:30 │ DateTime           │
└─────────────────────┴────────────────────┘

​

toTimezone

自 v1.1.0 引入

将 DateTime 或 DateTime64 转换为指定的时区。 数据的内部值 (Unix 秒数) 不会改变。 只有该值的时区属性和字符串表示形式会发生变化。

语法

toTimezone(datetime, timezone)

别名: toTimeZone

参数

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

返回值

返回与输入相同的时间戳，但时区为指定时区。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])

参数

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

返回值

返回 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(toDateTime('2026-01-01 03:04:05', 'UTC'), 'US/Eastern')

Response

┌─toYYYYMM(toDateTime('2026-01-01 03:04:05', 'UTC'), 'US/Eastern')─┐
│                                                           202512 │
└──────────────────────────────────────────────────────────────────┘

​

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(toDateTime('2026-01-02 03:04:05', 'UTC'), 'US/Eastern')

Response

┌─toYYYYMMDD(toDateTime('2026-01-02 03:04:05', 'UTC'), 'US/Eastern')─┐
│                                                           20260101 │
└────────────────────────────────────────────────────────────────────┘

​

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(toDateTime('2023-03-02 16:22:09', 'UTC'), 'US/Eastern')

Response

┌─toYYYYMMDDhhmmss(toDateTime('2023-03-02 16:22:09', 'UTC'), 'US/Eastern')─┐
│                                                           20230302112209 │
└──────────────────────────────────────────────────────────────────────────┘

​

toYear

引入版本：v1.1.0

返回 Date 或 DateTime 值的年份部分 (公元) 。

语法

toYear(datetime)

别名: YEAR

参数

• datetime — 用于提取年份的日期或日期时间。Date 或 Date32 或 DateTime 或 DateTime64

返回值

返回给定 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)

参数

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

返回值

正整数

示例

示例

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

别名：current_date, curdate

参数

• 无。

返回值

返回当前日期 Date

示例

用法示例

Query

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

Response

┏━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃      today ┃    curdate ┃ current_date ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ 2026-08-02 │ 2026-08-02 │   2026-08-02 │
└────────────┴────────────┴──────────────┘

不使用括号的 SQL 标准语法

Query

SELECT TODAY, CURDATE,CURRENT_DATE

Response

┌──────TODAY─┬────CURDATE─┬─CURRENT_DATE─┐
│ 2026-08-02 │ 2026-08-02 │   2026-08-02 │
└────────────┴────────────┴──────────────┘

​

yesterday

引入版本：v1.1.0

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

此函数是非确定性的：对于相同的参数，它可能返回不同的结果。

语法

yesterday()

参数

• 无。

返回值

返回昨天的日期。Date

示例

获取昨天的日期

Query

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

Response

┌─yesterday()─┐
│  2026-08-01 │
└─────────────┘
┌─minus(today(), 1)─┐
│        2026-08-01 │
└───────────────────┘