日期和时间函数

formatDateTime

用法：

formatDateTime(<datetime expression>, <format string>[, <timezone string>])

formatDateTime 根据提供的格式字符串将日期时间输出为字符串。支持的格式化选项列表请参阅 ClickHouse 文档 ↗。

示例：

-- 以 UTC 格式输出当前的 YYYY-MM-DD
formatDateTime(now(), '%Y-%m-%d')

-- 以日期时间的时区输出 YYYY-MM-DD
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d')
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d')

-- 以 UTC 格式输出 YYYY-MM-DD
formatDateTime(<a datetime with a timezone>, '%Y-%m-%d', 'Etc/UTC')
formatDateTime(toDateTime('2022-12-01 16:17:00', 'America/New_York'), '%Y-%m-%d', 'Etc/UTC')

now

用法：

now()

返回当前时间，类型为 DateTime。

today New

用法：

today()

返回当前日期，类型为 Date。

toDateTime

用法：

toDateTime(<expression>[, 'timezone string'])

toDateTime 将表达式转换为日期时间。此函数不支持 ISO 8601 格式的时区；如果您的时间不是 UTC，则必须使用第二个可选参数提供时区。

示例：

-- double1 包含一个以秒为单位的 Unix 时间戳
toDateTime(double1)

-- blob1 包含格式为 'YYYY-MM-DD hh:mm:ss' 的日期时间
toDateTime(blob1)

-- 字面量值：
toDateTime(355924804) -- Unix 时间戳
toDateTime('355924804') -- 包含 Unix 时间戳的字符串
toDateTime('1981-04-12 12:00:04') -- 格式为 'YYYY-MM-DD hh:mm:ss' 的日期时间字符串

-- 解释相对于纽约时间的日期
toDateTime('2022-12-01 16:17:00', 'America/New_York')

toYear New

用法：

toYear(<datetime>)

toYear 返回日期时间的年份。

示例：

-- 返回数字 2025
toYear(toDateTime('2025-10-27 00:00:00'))

toMonth New

用法：

toMonth(<datetime>)

toMonth 返回日期时间的月份。

示例：

-- 返回数字 10
toMonth(toDateTime('2025-10-27 00:00:00'))

toDayOfWeek New

用法：

toDayOfWeek(<datetime>)

toDayOfWeek 接收一个日期时间，并返回该星期几的数值。

返回 1 表示星期一，返回 2 表示星期二，依此类推。

示例：

-- 2025 年 10 月 27 日星期一，返回数字 1
toDayOfWeek(toDateTime('2025-10-27 00:00:00'))

-- 2025 年 10 月 28 日星期二，返回数字 2
toDayOfWeek(toDateTime('2025-10-28 00:00:00'))

-- 2025 年 11 月 2 日星期日，返回数字 7
toDayOfWeek(toDateTime('2025-11-02 00:00:00'))

toDayOfMonth New

用法：

toDayOfMonth(<datetime>)

toDayOfMonth 返回日期时间在当月第几天的数值。

示例：

-- 返回数字 27
toDayOfMonth(toDateTime('2025-10-27 00:00:00'))

toHour New

用法：

toHour(<datetime>)

toHour 返回日期时间中小时的数值。

示例：

-- 返回数字 9
toHour(toDateTime('2025-10-27 09:11:13'))

toMinute New

用法：

toMinute(<datetime>)

toMinute 返回日期时间中分钟的数值。

示例：

-- 返回数字 11
toMinute(toDateTime('2025-10-27 09:11:13'))

toSecond New

用法：

toSecond(<datetime>)

toSecond 返回日期时间中秒钟的数值。

示例：

-- 返回数字 13
toSecond(toDateTime('2025-10-27 09:11:13'))

toUnixTimestamp

用法：

toUnixTimestamp(<datetime>)

toUnixTimestamp 将日期时间转换为整数 Unix 时间戳。

示例：

-- 获取当前的 Unix 时间戳
toUnixTimestamp(now())

toStartOfInterval

用法：

toStartOfInterval(<datetime>, INTERVAL '<n>' <unit>[, <timezone string>])

toStartOfInterval 将日期时间向下取整到指定时间间隔的最近偏移量。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将当前时间向下取整到最近的 15 分钟
toStartOfInterval(now(), INTERVAL '15' MINUTE)

-- 将时间戳向下取整到天
toStartOfInterval(timestamp, INTERVAL '1' DAY)

-- 统计每个小时窗口中归档的数据点数量
SELECT
  toStartOfInterval(timestamp, INTERVAL '1' HOUR) AS hour,
  sum(_sample_interval) AS count
FROM your_dataset
GROUP BY hour
ORDER BY hour ASC

toStartOfYear New

用法：

toStartOfYear(<datetime>)

toStartOfYear 将日期时间向下取整到最近的年初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-01-01 00:00:00
toStartOfYear(toDateTime('2025-10-27 00:00:00'))

toStartOfMonth New

用法：

toStartOfMonth(<datetime>)

toStartOfMonth 将日期时间向下取整到最近的月初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-01 00:00:00
toStartOfMonth(toDateTime('2025-10-27 00:00:00'))

toStartOfWeek New

用法：

toStartOfWeek(<datetime>)

toStartOfWeek 将日期时间向下取整到这周的周初。这对于将数据分组到相等大小的时间范围内非常有用。

以星期一作为一周的第一天。

示例：

-- 将星期一的时间向下取整至星期一 2025-10-27 00:00:00
toStartOfWeek(toDateTime('2025-10-27 00:00:00'))

-- 将星期三的时间向下取整至星期一 2025-10-27 00:00:00
toStartOfWeek(toDateTime('2025-10-29 00:00:00'))

toStartOfDay New

用法：

toStartOfDay(<datetime>)

toStartOfDay 将日期时间向下取整到最近的天初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 00:00:00
toStartOfDay(toDateTime('2025-10-27 00:00:00'))

toStartOfHour New

用法：

toStartOfHour(<datetime>)

toStartOfHour 将日期时间向下取整到最近的小时初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 16:00:00
toStartOfHour(toDateTime('2025-10-27 16:55:25'))

toStartOfFifteenMinutes New

用法：

toStartOfFifteenMinutes(<datetime>)

toStartOfFifteenMinutes 将日期时间向下取整到最近的 15 分钟初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 16:45:00
toStartOfFifteenMinutes(toDateTime('2025-10-27 16:55:25'))

toStartOfTenMinutes New

用法：

toStartOfTenMinutes(<datetime>)

toStartOfTenMinutes 将日期时间向下取整到最近的 10 分钟初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 16:50:00
toStartOfTenMinutes(toDateTime('2025-10-27 16:55:25'))

toStartOfFiveMinutes New

用法：

toStartOfFiveMinutes(<datetime>)

toStartOfFiveMinutes 将日期时间向下取整到最近的 5 分钟初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 16:55:00
toStartOfFiveMinutes(toDateTime('2025-10-27 16:55:25'))

toStartOfMinute New

用法：

toStartOfMinute(<datetime>)

toStartOfMinute 将日期时间向下取整到最近的分钟初。这对于将数据分组到相等大小的时间范围内非常有用。

示例：

-- 将时间戳向下取整至 2025-10-27 16:55:00
toStartOfMinute(toDateTime('2025-10-27 16:55:25'))

toYYYYMM New

用法：

toYYYYMM(<datetime>)

toYYYYMM 返回一个表示日期时间的年份和月份的数字。例如，2025-05-03 的日期时间将返回数字 202505。

示例：

-- 返回数字 202510
toYYYYMM(toDateTime('2025-10-27 16:55:25'))