跳到主要内容
跳到主要内容

处理日期和时间的函数

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

示例

makeDate​

从年、月和日参数创建一个 Date

  • 从年、月和日参数，或
  • 从年和年中的天数参数。

语法

别名：

  • MAKEDATE(year, month, day);
  • MAKEDATE(year, day_of_year);

参数

返回值

  • 从参数创建的日期。 Date。

示例

根据年、月和日创建日期：

结果：

根据年和年中的天数参数创建日期：

结果：

makeDate32​

从年、月、日（或可选的年和天）创建 Date32 类型的日期。

语法

参数

备注

如果省略 month，则 day 应该取值在 1 到 365 之间；否则，day 应该取值在 1 到 31 之间。

返回值

  • 从参数创建的日期。 Date32。

示例

从年、月和日创建日期：

查询：

结果：

从年和年中的天数创建日期：

查询：

结果：

makeDateTime​

根据年、月、日、小时、分钟和秒参数创建一个 DateTime。

语法

参数

返回值

  • 从参数创建的日期和时间。 DateTime。

示例

结果：

makeDateTime64​

从其组件（年、月、日、小时、分钟、秒）创建带有可选亚秒精度的 DateTime64 数据类型值。

语法

参数

返回值

  • 从提供的参数创建的日期和时间。 DateTime64。

示例

timestamp​

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

语法

别名：TIMESTAMP

参数

  • expr - 日期或带时间的日期。 String。
  • expr_time - 可选参数。要添加的时间。 String。

示例

结果：

结果：

返回值

timeZone​

返回当前会话的时区，即设置 session_timezone 的值。如果在分布式表的上下文中执行函数，则生成与每个分片相关的正常列值，否则生成常量值。

语法

别名：timezone。

返回值

示例

结果：

另请参见

serverTimeZone​

返回服务器的时区，即设置 timezone 的值。如果在分布式表的上下文中执行函数，则生成与每个分片相关的正常列值。否则，生成常量值。

语法

别名：serverTimezone。

返回值

示例

结果：

另请参见

toTimeZone​

将日期或带时间的日期转换为指定的时区。不会更改数据的内部值（Unix秒数），仅更改值的时区属性和字符串表示。

语法

别名：toTimezone。

参数

  • value — 时间或日期和时间。 DateTime64。
  • timezone — 返回值的时区。 String。此参数是常量，因为 toTimezone 更改列的时区（时区是 DateTime* 类型的属性）。

返回值

示例

结果：

另请参见

timeZoneOf​

返回 DateTime 或 DateTime64 数据类型的时区名称。

语法

别名：timezoneOf。

参数

返回值

示例

结果：

timeZoneOffset​

返回与 UTC 的时区偏移（以秒为单位）。该函数考虑到在指定日期和时间的 夏令时 和历史时区变更。使用 IANA 时区数据库 来计算偏移。

语法

别名：timezoneOffset。

参数

返回值

  • 从 UTC 的偏差（以秒为单位）。 Int32。

示例

结果：

toYear​

返回日期或带时间的日期的年份组件（公元）。

语法

别名：YEAR

参数

返回值

  • 给定日期/时间的年份。 UInt16。

示例

结果：

toQuarter​

返回日期或带时间的日期的季度（1-4）。

语法

别名：QUARTER

参数

返回值

  • 给定日期/时间的季度（1、2、3 或 4）。 UInt8。

示例

结果：

toMonth​

返回日期或带时间的日期的月份组件（1-12）。

语法

别名：MONTH

参数

返回值

  • 给定日期/时间的月份（1 - 12）。 UInt8。

示例

结果：

toDayOfYear​

返回一个日期或带时间的日期在年内的天数（1-366）。

语法

别名：DAYOFYEAR

参数

返回值

  • 给定日期/时间的年中的天数（1 - 366）。 UInt16。

示例

结果：

toDayOfMonth​

返回日期或带时间的日期在月份内的天数（1-31）。

语法

别名：DAYOFMONTH, DAY

参数

返回值

  • 给定日期/时间的日期（1 - 31）。 UInt8。

示例

结果：

toDayOfWeek​

返回日期或带时间的日期在周内的天数。

toDayOfWeek() 的两个参数形式使您能够指定一周是从星期一还是星期日开始，以及返回值是否应在范围 0 到 6 或 1 到 7。如果省略模式参数，则默认模式为 0。日期的时区可以作为第三个参数指定。

模式一周的第一天范围
0星期一1-7：星期一 = 1，星期二 = 2，...，星期日 = 7
1星期一0-6：星期一 = 0，星期二 = 1，...，星期日 = 6
2星期日0-6：星期日 = 0，星期一 = 1，...，星期六 = 6
3星期日1-7：星期日 = 1，星期一 = 2，...，星期六 = 7

语法

别名：DAYOFWEEK。

参数

  • t - 一个 Date， Date32， DateTime 或 DateTime64
  • mode - 决定一周的第一天。可能的值是 0、1、2 或 3。请查看上面的表格以了解差异。
  • timezone - 可选参数，它的行为与其他转换函数相同。

第一个参数也可以作为 String 指定，且支持 parseDateTime64BestEffort() 支持的格式。仅因兼容某些第三方工具而存在字符串参数支持。由于字符串参数的支持可能在未来依赖于新的 MySQL 兼容性设置，并且字符串解析通常较慢，因此建议不要使用它。

返回值

  • 给定日期/时间的星期几（1-7），具体取决于选择的模式。

示例

以下日期为 2023 年 4 月 21 日，那是星期五：

结果：

toHour​

返回带时间的日期的小时组件（0-24）。

假定如果时钟向前移动，则增加一个小时，并发生在早上 2 点；如果时钟向后移动，则减少一个小时，并发生在早上 3 点。（这并不总是确切发生时刻 - 这取决于时区）。

语法

别名：HOUR

参数

返回值

  • 给定日期/时间的小时数（0 - 23）。 UInt8。

示例

结果：

toMinute​

返回带时间的日期的分钟组件（0-59）。

语法

别名：MINUTE

参数

返回值

  • 给定日期/时间的分钟数（0 - 59）。 UInt8。

示例

结果：

toSecond​

返回带时间的日期的秒组件（0-59）。不考虑闰秒。

语法

别名：SECOND

参数

返回值

  • 给定日期/时间的秒数（0 - 59）。 UInt8。

示例

结果：

toMillisecond​

返回带时间的日期的毫秒组件（0-999）。

语法

参数

别名：MILLISECOND

结果：

返回值

  • 给定日期/时间的毫秒数（0 - 999）。 UInt16。

toUnixTimestamp​

将字符串、日期或带时间的日期转换为 Unix 时间戳 的 UInt32 表示。

如果使用字符串调用该函数，则接受一个可选的时区参数。

语法

返回值

  • 返回 unix 时间戳。 UInt32。

示例

结果：

备注

toStartOf*、toLastDayOf*、toMonday、timeSlot 函数的返回类型由配置参数 enable_extended_results_for_datetime_functions 决定，默认值为 0。

行为为

  • enable_extended_results_for_datetime_functions = 0：
    • 函数 toStartOfYear、toStartOfISOYear、toStartOfQuarter、toStartOfMonth、toStartOfWeek、toLastDayOfWeek、toLastDayOfMonth、toMonday 返回 Date 或 DateTime。
    • 函数 toStartOfDay、toStartOfHour、toStartOfFifteenMinutes、toStartOfTenMinutes、toStartOfFiveMinutes、toStartOfMinute、timeSlot 返回 DateTime。尽管这些函数可以接受扩展类型 Date32 和 DateTime64 的值作为参数，但传递超出正常范围的时间（1970 年到 2149 年的日期 / 2106 年的日期时间）将产生错误结果。
  • enable_extended_results_for_datetime_functions = 1：
    • 在参数是 Date 或 DateTime 的情况下，函数 toStartOfYear、toStartOfISOYear、toStartOfQuarter、toStartOfMonth、toStartOfWeek、toLastDayOfWeek、toLastDayOfMonth、toMonday 返回 Date 或 DateTime，在参数是 Date32 或 DateTime64 的情况下返回 Date32 或 DateTime64。
    • 函数 toStartOfDay、toStartOfHour、toStartOfFifteenMinutes、toStartOfTenMinutes、toStartOfFiveMinutes、toStartOfMinute、timeSlot 在参数是 Date 或 DateTime 的情况下返回 DateTime，在参数是 Date32 或 DateTime64 的情况下返回 DateTime64。

toStartOfYear​

将日期或带时间的日期向下取整至该年的第一天。返回日期作为 Date 对象。

语法

参数

返回值

  • 输入日期/时间的年份的第一天。 Date。

示例

结果：

toStartOfISOYear​

将日期或带时间的日期向下取整至 ISO 年的第一天，这可能与“常规”年不同。（请参见 https://en.wikipedia.org/wiki/ISO_week_date。）

语法

参数

返回值

  • 输入日期/时间的年份的第一天。 Date。

示例

结果：

toStartOfQuarter​

将日期或带时间的日期向下取整至该季度的第一天。季度的第一天是 1 月 1 日、4 月 1 日、7 月 1 日或 10 月 1 日。 返回日期。

语法

参数

返回值

  • 给定日期/时间的季度的第一天。 Date。

示例

结果：

toStartOfMonth​

将日期或带时间的日期向下取整至该月的第一天。返回日期。

语法

参数

返回值

  • 给定日期/时间的月份的第一天。 Date。

示例

结果：

备注

解析不正确日期的行为是实现特定的。 ClickHouse 可能返回零日期、引发异常，或进行“自然”溢出。

toLastDayOfMonth​

将日期或带时间的日期向上取整至该月的最后一天。返回日期。

语法

别名：LAST_DAY

参数

返回值

  • 给定日期/时间的月份的最后一天。 Date。

示例

结果：

toMonday​

将日期或带时间的日期向下取整至最近的星期一。返回日期。

语法

参数

返回值

  • 对于给定日期的最近星期一的日期。 Date。

示例

结果：

toStartOfWeek​

将日期或带时间的日期向下取整至最近的星期日或星期一。返回日期。模式参数的工作方式与函数 toWeek() 中的模式参数完全相同。如果没有指定模式，则默认为 0。

语法

参数

  • t - 一个 Date， Date32， DateTime 或 DateTime64
  • mode - 决定一周的第一天，如 toWeek() 函数所述
  • timezone - 可选参数，它的行为与其他转换函数相同

返回值

  • 对于给定日期的最近星期日或星期一的日期，具体取决于模式。 Date。

示例

结果：

toLastDayOfWeek​

将日期或带时间的日期向上取整至最近的星期六或星期日。返回日期。模式参数的工作方式与函数 toWeek() 中的模式参数完全相同。如果没有指定模式，则默认模式为 0。

语法

参数

  • t - 一个 Date， Date32， DateTime 或 DateTime64
  • mode - 决定一周的最后一天，如 toWeek 函数所述
  • timezone - 可选参数，它的行为与其他转换函数相同

返回值

  • 对于给定日期的最近星期日或星期一的日期，具体取决于模式。 Date。

示例

结果：

toStartOfDay​

将带时间的日期向下取整至一天的开始。

语法

参数

返回值

  • 给定日期/时间的一天的开始。 DateTime。

示例

结果：

toStartOfHour​

将带时间的日期向下取整至小时的开始。

语法

参数

返回值

  • 给定日期/时间的小时的开始。 DateTime。

示例

结果：

toStartOfMinute​

将带时间的日期向下取整至分钟的开始。

语法

参数

返回值

  • 给定日期/时间的分钟的开始。 DateTime。

示例

结果：

toStartOfSecond​

截短亚秒部分。

语法

参数

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

返回值

示例

不带时区的查询：

结果：

带有时区的查询：

结果：

另请参见

toStartOfMillisecond​

将带时间的日期向下取整至毫秒的开始。

语法

参数

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

返回值

示例

不带时区的查询：

结果：

带有时区的查询：

结果：

toStartOfMicrosecond​

将带时间的日期向下取整至微秒的开始。

语法

参数

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

返回值

示例

不带时区的查询：

结果：

带有时区的查询：

结果：

另请参见

toStartOfNanosecond​

将带时间的日期向下取整至纳秒的开始。

语法

参数

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

返回值

示例

不带时区的查询：

结果：

带有时区的查询：

结果：

另请参见

toStartOfFiveMinutes​

将带时间的日期向下取整至五分钟间隔的开始。

语法

参数

返回值

  • 给定日期/时间的五分钟间隔的开始。 DateTime。

示例

结果：

toStartOfTenMinutes​

将带时间的日期向下取整至十分钟间隔的开始。

语法

参数

返回值

  • 给定日期/时间的十分钟间隔的开始。 DateTime。

示例

结果：

toStartOfFifteenMinutes​

将带时间的日期向下取整至十五分钟间隔的开始。

语法

参数

返回值

  • 给定日期/时间的十五分钟间隔的开始。 DateTime。

示例

结果：

toStartOfInterval​

此函数使用 toStartOfInterval(date_or_date_with_time, INTERVAL x unit [, time_zone]) 语法对其他 toStartOf*() 函数进行了概括。 例如，

  • toStartOfInterval(t, INTERVAL 1 YEAR) 的返回值与 toStartOfYear(t) 相同，
  • toStartOfInterval(t, INTERVAL 1 MONTH) 的返回值与 toStartOfMonth(t) 相同，
  • toStartOfInterval(t, INTERVAL 1 DAY) 的返回值与 toStartOfDay(t) 相同，
  • toStartOfInterval(t, INTERVAL 15 MINUTE) 的返回值与 toStartOfFifteenMinutes(t) 相同。

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

间隔开始
YEAR年 0
QUARTER1900 年第一季度
MONTH1900 年一月
WEEK1970 年第一周 (01-05)
DAY1970-01-01
HOUR(*)
MINUTE1970-01-01 00:00:00
SECOND1970-01-01 00:00:00
MILLISECOND1970-01-01 00:00:00
MICROSECOND1970-01-01 00:00:00
NANOSECOND1970-01-01 00:00:00

(*) 小时间隔是特殊的：计算始终相对于当天的 00:00:00 (午夜) 进行。因此，只有 1 到 23 之间的小时值是有用的。

如果指定了单位为 WEEK，toStartOfInterval 假定周的开始是星期一。请注意，这一行为与默认以星期天开始的 toStartOfWeek 函数不同。

语法

别名: time_bucket, date_bin.

第二个重载模仿 TimescaleDB 的 time_bucket() 函数，以及 PostgreSQL 的 date_bin() 函数，例如：

结果：

另见

toTimeWithFixedDate​

将带时间的日期转换为某个固定日期，同时保留时间。

语法

别名: toTime - 仅在启用 use_legacy_to_time 设置时可以使用。

参数

返回值

  • DateTime，其中日期等于 1970-01-02，同时保留时间。 DateTime.
备注

如果 date 输入参数包含子秒组件，它们将在返回的 DateTime 值中以秒为精度被舍弃。

示例

查询：

结果：

toRelativeYearNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的年数。

语法

参数

返回值

  • 从过去某个固定参考点开始的年数。 UInt16.

示例

查询：

结果：

toRelativeQuarterNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的季度数。

语法

参数

返回值

  • 从过去某个固定参考点开始的季度数。 UInt32.

示例

查询：

结果：

toRelativeMonthNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的月数。

语法

参数

返回值

  • 从过去某个固定参考点开始的月数。 UInt32.

示例

查询：

结果：

toRelativeWeekNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的周数。

语法

参数

返回值

  • 从过去某个固定参考点开始的周数。 UInt32.

示例

查询：

结果：

toRelativeDayNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的天数。

语法

参数

返回值

  • 从过去某个固定参考点开始的天数。 UInt32.

示例

查询：

结果：

toRelativeHourNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的小时数。

语法

参数

返回值

  • 从过去某个固定参考点开始的小时数。 UInt32.

示例

查询：

结果：

toRelativeMinuteNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的分钟数。

语法

参数

返回值

  • 从过去某个固定参考点开始的分钟数。 UInt32.

示例

查询：

结果：

toRelativeSecondNum​

将日期或带时间的日期转换为自某一固定过去点以来经过的秒数。

语法

参数

返回值

  • 从过去某个固定参考点开始的秒数。 UInt32.

示例

查询：

结果：

toISOYear​

将日期或带时间的日期转换为 ISO 年的 UInt16 数字。

语法

参数

返回值

  • 输入值转换为 ISO 年数字。 UInt16.

示例

查询：

结果：

toISOWeek​

将日期或带时间的日期转换为包含 ISO 周序号的 UInt8 数字。

语法

参数

  • value — 带日期或带时间的值。

返回值

  • value 转换为当前 ISO 周序号。 UInt8.

示例

查询：

响应：

toWeek​

此函数返回日期或日期时间的周序号。 toWeek() 的两个参数形式允许您指定周的开始是星期天还是星期一，返回值的范围是从 0 到 53 还是从 1 到 53。如果省略模式参数，则默认模式为 0。

toISOWeek() 是与 toWeek(date,3) 等价的兼容函数。

下表描述了模式参数的工作原理。

模式周的第一天范围第 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 天或更多”含义的模式值，周数依据 ISO 8601:1988 进行编号：

  • 如果包含 1 月 1 日的那一周在新年有 4 天或更多，则为第 1 周。

  • 否则，它是前一年的最后一周，下一周为第 1 周。

对于具有“包含 1 月 1 日”含义的模式值，包含 1 月 1 日的那一周为第 1 周。无论这一周在新年中包含多少天，甚至只包含一天。 即如果 12 月的最后一周包含下一年的 1 月 1 日，它将是下一年的第一周。

语法

别名: WEEK

参数

  • t – 日期或日期时间。
  • mode – 可选参数，取值范围为 [0,9]，默认值为 0。
  • Timezone – 可选参数，其行为与其他转换函数相同。

第一个参数也可以指定为 String，格式应符合 parseDateTime64BestEffort() 所支持的格式。字符串参数的支持仅是为了与某些 3rd 方工具所期望的 MySQL 兼容。由于字符串参数支持未来可能依赖于新的 MySQL 兼容性设置，并且字符串解析一般比较慢，建议不要使用它。

示例

toYearWeek​

返回日期的年份和周数。结果中的年份可能与日期参数中的年份不同，尤其是在年的第一周和最后一周。

模式参数的用法与 toWeek() 的模式参数相同。对于单参数语法，使用模式值 0。

toISOYear() 是与 intDiv(toYearWeek(date,3),100) 等价的兼容函数。

危险

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

语法

别名: YEARWEEK

第一个参数也可以指定为 String，格式应符合 parseDateTime64BestEffort() 所支持的格式。字符串参数的支持仅是为了与某些 3rd 方工具所期望的 MySQL 兼容。由于字符串参数支持未来可能依赖于新的 MySQL 兼容性设置，并且字符串解析一般比较慢，建议不要使用它。

示例

toDaysSinceYearZero​

返回给定日期以来在 ISO 8601 称为 1 January 0000 的天数。这一计算与 MySQL 的 TO_DAYS() 函数相同。

语法

别名: TO_DAYS

参数

返回值

自 0000-01-01 日期以来经过的天数。 UInt32.

示例

结果：

另见

fromDaysSinceYearZero​

返回自 1 January 0000 以来经过的天数所对应的日期，计算遵循 或荡Gregorian calendar. 该计算与 MySQL 的 FROM_DAYS() 函数相同。

如果结果无法在 Date 类型的范围内表示，则结果为未定义。

语法

别名: FROM_DAYS

参数

  • days — 自年份零以来经过的天数。

返回值

自年份零以来经过的天数对应的日期。 Date.

示例

结果：

另见

fromDaysSinceYearZero32​

像 fromDaysSinceYearZero 但返回 Date32。

age​

返回 startdate 和 enddate 之间的 unit 组件的差异。差异使用 1 纳秒的精度进行计算。 例如，2021-12-29 和 2022-01-01 之间的差异在 day 单位下为 3 天，在 month 单位下为 0 个月，在 year 单位下为 0 年。

有关 age 的替代方法，请参见函数 date_diff。

语法

参数

  • unit — 结果的间隔类型。 String. 可能的值：

    • nanosecond, nanoseconds, ns
    • microsecond, microseconds, us, u
    • millisecond, milliseconds, ms
    • second, seconds, ss, s
    • minute, minutes, mi, n
    • hour, hours, hh, h
    • day, days, dd, d
    • week, weeks, wk, ww
    • month, months, mm, m
    • quarter, quarters, qq, q
    • year, years, yyyy, yy

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

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

  • timezone — 时区名称（可选）。如果指定，则适用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 的时区。如果它们不相同，则结果未定义。 String.

返回值

以 unit 表达的 enddate 和 startdate 之间的差异。 Int.

示例

结果：

结果：

date_diff​

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

如果指定了 unit 为 week，则 date_diff 假定周的开始是星期一。请注意，这一行为与默认以星期天开始的 toWeek() 函数不同。

有关 date_diff 的替代方法，请参见函数 age。

语法

别名: dateDiff, DATE_DIFF, timestampDiff, timestamp_diff, TIMESTAMP_DIFF.

参数

  • unit — 结果的间隔类型。 String. 可能的值：

    • nanosecond, nanoseconds, ns
    • microsecond, microseconds, us, u
    • millisecond, milliseconds, ms
    • second, seconds, ss, s
    • minute, minutes, mi, n
    • hour, hours, hh, h
    • day, days, dd, d
    • week, weeks, wk, ww
    • month, months, mm, m
    • quarter, quarters, qq, q
    • year, years, yyyy, yy

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

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

  • timezone — 时区名称（可选）。如果指定，则适用于 startdate 和 enddate。如果未指定，则使用 startdate 和 enddate 的时区。如果它们不相同，则结果未定义。 String.

返回值

以 unit 表达的 enddate 和 startdate 之间的差异。 Int.

示例

结果：

结果：

date_trunc​

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

语法

别名: dateTrunc.

参数

  • unit — 用于截断结果的时间间隔类型。 String Literal. 可能的值：

    • nanosecond - 仅与 DateTime64 兼容
    • microsecond - 仅与 DateTime64 兼容
    • millisecond - 仅与 DateTime64 兼容
    • second
    • minute
    • hour
    • day
    • week
    • month
    • quarter
    • year

    unit 参数不区分大小写。

  • value — 日期和时间。 Date, Date32, DateTime 或 DateTime64.

  • timezone — 返回值的 时区名称（可选）。如果未指定，函数将使用 value 参数的时区。 String.

返回值

如果 unit 参数为 Year、Quarter、Month 或 Week，

  • 且 value 参数为 Date32 或 DateTime64，则返回 Date32。
  • 否则返回 Date。

如果 unit 参数为 Day、Hour、Minute 或 Second，

  • 且 value 参数为 Date32 或 DateTime64，则返回 DateTime64。
  • 否则返回 DateTime。

如果 unit 参数为 Millisecond、Microsecond 或 Nanosecond，则返回 DateTime64，其级别为 3 或 6 或 9（取决于 unit 参数）。

示例

没有时区的查询：

结果：

指定时区的查询：

结果：

另见

date_add​

将时间间隔或日期间隔添加到提供的日期或带时间的日期。

如果添加后的值超出数据类型的范围，则结果未定义。

语法

替代语法：

别名: dateAdd, DATE_ADD。

参数

  • unit — 要添加的间隔类型。注意：这不是一个 String，因此不能加引号。 可能的值：

    • second
    • minute
    • hour
    • day
    • week
    • month
    • quarter
    • year

  • value — 要添加的间隔值。 Int.

  • date — 要向其添加 value 的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64.

返回值

通过将 value 以 unit 的形式添加到 date 得到的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

结果：

另见

date_sub​

从提供的日期或带时间的日期中减去时间间隔或日期间隔。

如果减法后的值超出数据类型的范围，则结果未定义。

语法

替代语法：

别名: dateSub, DATE_SUB。

参数

  • unit — 要减去的间隔类型。注意：这不是一个 String，因此不能加引号。

    可能的值：

    • second
    • minute
    • hour
    • day
    • week
    • month
    • quarter
    • year

  • value — 要减去的间隔值。 Int.

  • date — 要从中减去 value 的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64.

返回值

通过将 value 以 unit 的形式从 date 中减去得到的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

结果：

另见

timestamp_add​

将指定的时间值添加到提供的日期或日期时间值中。

如果添加后的值超出数据类型的范围，则结果未定义。

语法

别名: timeStampAdd, TIMESTAMP_ADD。

参数

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

  • value — 要添加的间隔值。 Int.

  • unit — 要添加的间隔类型。 String. 可能的值：

    • second
    • minute
    • hour
    • day
    • week
    • month
    • quarter
    • year

返回值

带有指定的 value 以 unit 形式添加到 date 的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

timestamp_sub​

从提供的日期或带时间的日期中减去时间间隔。

如果减法后的值超出数据类型的范围，则结果未定义。

语法

别名: timeStampSub, TIMESTAMP_SUB。

参数

  • unit — 要减去的间隔类型。 String. 可能的值：

    • second
    • minute
    • hour
    • day
    • week
    • month
    • quarter
    • year

  • value — 要减去的间隔值。 Int.

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

返回值

通过将 value 以 unit 形式从 date 中减去得到的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

addDate​

将时间间隔添加到提供的日期、带时间的日期或以字符串编码的日期/带时间的日期中。

如果添加后的值超出数据类型的范围，则结果未定义。

语法

参数

返回值

通过将 interval 添加到 date 得到的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

别名: ADDDATE

另见

subDate​

从提供的日期、带时间的日期或以字符串编码的日期/带时间的日期中减去时间间隔。

如果减法后的值超出数据类型的范围，则结果未定义。

语法

参数

返回值

通过将 interval 从 date 中减去得到的日期或带时间的日期。 Date, Date32, DateTime 或 DateTime64。

示例

结果：

别名: SUBDATE

另见

now​

返回查询分析时的当前日期和时间。该函数为常量表达式。

别名: current_timestamp。

语法

参数

返回值

示例

没有时区的查询：

结果：

指定时区的查询：

结果：

now64​

返回查询分析时的当前日期和时间，精度为子秒。该函数为常量表达式。

语法

参数

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

返回值

  • 当前日期和时间，精度为子秒。 DateTime64.

示例

结果：

nowInBlock​

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

该函数适用于在长时间运行的 INSERT SELECT 查询中生成当前时间。

语法

参数

返回值

  • 每个数据块处理时的当前日期和时间。 DateTime.

示例

结果：

today​

返回查询分析时的当前日期。它与 'toDate(now())' 相同，并且具有别名: curdate, current_date。

语法

参数

  • 无

返回值

示例

查询：

结果：

在 2024 年 3 月 3 日运行上述查询将返回以下响应：

yesterday​

接受零个参数并在查询分析时返回昨天的日期。 与 'today() - 1' 相同。

timeSlot​

将时间舍入到半小时长度区间的开始。

语法

参数

  • time — 要舍入到半小时长度区间开始的时间。 DateTime/Date32/DateTime64。
  • time_zone — 表示时区的字符串类型常量或表达式。 String。
备注

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

返回类型

  • 返回舍入到半小时长度区间开始的时间。 DateTime。

示例

查询：

结果：

toYYYYMM​

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

该函数是函数 YYYYMMDDToDate() 的反向操作。

示例

结果：

toYYYYMMDD​

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

示例

结果：

toYYYYMMDDhhmmss​

将带有时间的日期转换为包含年份、月份、日期、小时、分钟和秒数字的 UInt64 数字（YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss）。接受第二个可选的时区参数。如果提供，此时区必须是字符串常量。

示例

结果：

YYYYMMDDToDate​

将包含年份、月份和日期数字的数字转换为 Date。

该函数是函数 toYYYYMMDD() 的反向操作。

如果输入不编码有效的 Date 值，则输出为未定义。

语法

参数

返回值

  • 由参数创建的日期。 Date。

示例

结果：

YYYYMMDDToDate32​

类似于函数 YYYYMMDDToDate()，但生成 Date32。

YYYYMMDDhhmmssToDateTime​

将包含年份、月份、日期、小时、分钟和秒数字的数字转换为 DateTime。

如果输入不编码有效的 DateTime 值，则输出为未定义。

该函数是函数 toYYYYMMDDhhmmss() 的反向操作。

语法

参数

  • yyyymmddhhmmss - 表示年份、月份、日期的数字。 Integer、Float 或 Decimal。
  • timezone - 返回值的 Timezone（可选）。

返回值

  • 由参数创建的带有时间的日期。 DateTime。

示例

结果：

YYYYMMDDhhmmssToDateTime64​

类似于函数 YYYYMMDDhhmmssToDate()，但生成 DateTime64。

在 timezone 参数后接受一个额外的可选的 precision 参数。

changeYear​

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

语法

参数

返回值

  • 与 date_or_datetime 相同的类型。

示例

结果：

changeMonth​

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

语法

参数

返回值

  • 返回与 date_or_datetime 相同类型的值。

示例

结果：

changeDay​

更改日期或日期时间的日期成分。

语法

参数

返回值

  • 返回与 date_or_datetime 相同类型的值。

示例

结果：

changeHour​

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

语法

参数

返回值

示例

结果：

changeMinute​

更改日期或日期时间的分钟成分。

语法

参数

返回值

示例

结果：

changeSecond​

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

语法

参数

返回值

示例

结果：

addYears​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的年份。

语法

参数

返回值

示例

addQuarters​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的季度。

语法

参数

返回值

示例

addMonths​

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

语法

参数

返回值

示例

addWeeks​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的周。

语法

参数

返回值

示例

addDays​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的天。

语法

参数

返回值

示例

addHours​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的小时。

语法

参数

返回值 o

示例

addMinutes​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的分钟。

语法

参数

返回值

示例

addSeconds​

向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的秒。

语法

参数

返回值

示例

addMilliseconds​

向带时间的日期或字符串编码的带时间的日期添加指定数量的毫秒。

语法

参数

返回值

  • 返回 date_time 加 num 毫秒。 DateTime64。

示例

addMicroseconds​

向带时间的日期或字符串编码的带时间的日期添加指定数量的微秒。

语法

参数

返回值

  • 返回 date_time 加 num 微秒。 DateTime64。

示例

addNanoseconds​

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

语法

参数

返回值

  • 返回 date_time 加 num 纳秒。 DateTime64。

示例

addInterval​

向另一个间隔或间隔元组添加间隔。

语法

参数

返回值

备注

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

示例

查询：

结果：

addTupleOfIntervals​

连续向日期或日期时间添加间隔元组。

语法

参数

返回值

示例

查询：

结果：

subtractYears​

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

语法

参数

返回值

示例

subtractQuarters​

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

语法

参数

返回值

示例

subtractMonths​

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

语法

参数

返回值

示例

subtractWeeks​

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

语法

参数

返回值

示例

subtractDays​

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

语法

参数

返回值

示例

subtractHours​

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

语法

参数

返回值

示例

结果：

subtractMinutes​

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

语法

参数

返回值

示例

结果：

subtractSeconds​

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

语法

参数

返回值

示例

结果：

subtractMilliseconds​

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

语法

参数

返回值

  • 返回 date_time 减去 num 毫秒。 DateTime64。

示例

结果：

subtractMicroseconds​

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

语法

参数

返回值

  • 返回 date_time 减去 num 微秒。 DateTime64。

示例

结果：

subtractNanoseconds​

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

语法

参数

返回值

  • 返回 date_time 减去 num 纳秒。 DateTime64。

示例

结果：

subtractInterval​

将否定间隔加到另一个间隔或间隔元组上。

语法

参数

返回值

备注

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

示例

查询：

结果：

subtractTupleOfIntervals​

连续从日期或日期时间中减去间隔元组。

语法

参数

返回值

示例

查询：

结果：

timeSlots​

对于从 'StartTime' 开始并持续 'Duration' 秒的时间间隔，它返回一个时间点的数组，这些点来自这个间隔并向下舍入到 'Size' 秒。 'Size' 是一个可选参数，默认设置为 1800（30分钟）。 这是必要的，例如，在查找相应会话中的页面浏览量时。 接受 DateTime 和 DateTime64 作为 'StartTime' 参数。对于 DateTime， 'Duration' 和 'Size' 参数必须是 UInt32。对于 'DateTime64'，它们必须是 Decimal64。 返回一个 DateTime/DateTime64 数组（返回类型与 'StartTime' 的类型相匹配）。对于 DateTime64，返回值的比例可以与 'StartTime' 的比例不同 —— 所有给定参数中取最高比例。

语法

示例

结果：

formatDateTime​

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

formatDateTime 使用 MySQL 日期时间格式样式，具体请参考 https://dev.mysql.com/doc/refman/8.0/en/date-and-time-functions.html#function_date-format。

此函数的反操作是 parseDateTime。

别名：DATE_FORMAT。

语法

返回值

根据确定的格式返回时间和日期值。

替换字段

使用替换字段，你可以定义生成字符串的模式。“示例”列显示 2018-01-02 22:33:44 的格式化结果。

占位符描述示例
%a缩写的星期几名称 (周一-周日)Mon
%b缩写的月份名称 (一月-十二月)Jan
%c作为整数的月份 (01-12)，参见下面的“注释 4”01
%C年除以 100 并截断为整数 (00-99)20
%d零填充的月份天数 (01-31)02
%D短形式 MM/DD/YY 日期，相当于 %m/%d/%y01/02/18
%e空格填充的月份天数 ( 1-31)，参见下面的“注释 5”  2
%f毫秒，参见下面的“注释 1”和“注释 2”123456
%F短形式 YYYY-MM-DD 日期，相当于 %Y-%m-%d2018-01-02
%g两位数年份格式，符合 ISO 8601，从四位数表示法中缩写18
%GISO 周编号的四位数年份格式，从 ISO 8601 标准定义的基于周的年份计算，通常与 %V 一起使用2018
%h12 小时格式的小时数 (01-12)09
%H24 小时格式的小时数 (00-23)22
%i分钟 (00-59)33
%I12 小时格式的小时数 (01-12)10
%j一年的天数 (001-366)002
%k24 小时格式的小时数 (00-23)，参见下面的“注释 4”14
%l12 小时格式的小时数 (01-12)，参见下面的“注释 4”09
%m作为整数的月份 (01-12)01
%M完整的月份名称 (一月-十二月)，参见下面的“注释 3”January
%n换行符 ('')
%p上午或下午的表示PM
%Q季度 (1-4)1
%r12 小时 HH:MM AM/PM 时间，相当于 %h:%i %p10:30 PM
%R24 小时 HH:MM 时间，相当于 %H:%i22:33
%s秒 (00-59)44
%S秒 (00-59)44
%t水平制表符字符 (')
%TISO 8601 时间格式 (HH:MM:SS)，相当于 %H:%i:%S22:33:44
%uISO 8601 周几的数字，周一为 1 (1-7)2
%VISO 8601 周编号 (01-53)01
%w星期几作为整数，周日为 0 (0-6)2
%W完整的星期几名称 (周一-周日)Monday
%y年的最后两位数字 (00-99)18
%Y年2018
%zUTC 的时间偏移量，以 +HHMM 或 -HHMM 的形式表示-0500
%%百分号%

注释 1：在 ClickHouse 版本早于 v23.4 时，如果格式化值为没有小数秒的 Date、Date32 或 DateTime，或者为精度为 0 的 DateTime64，%f 将打印一个零 (0)。可以使用设置 formatdatetime_f_prints_single_zero = 1 恢复以前的行为。

注释 2：在 ClickHouse 版本早于 v25.1 时，%f 将根据 DateTime64 的缩放打印指定数量的数字，而不是固定的 6 位数字。可以使用设置 formatdatetime_f_prints_scale_number_of_digits= 1 恢复以前的行为。

注释 3：在 ClickHouse 版本早于 v23.4 时，%M 打印分钟 (00-59)，而不是完整的月份名称 (一月-十二月)。可以使用设置 formatdatetime_parsedatetime_m_is_month_name = 0 恢复以前的行为。

注释 4：在 ClickHouse 版本早于 v23.11 时，函数 parseDateTime 要求格式化器 %c (月份) 和 %l/%k (小时) 有前导零，例如 07。在后来的版本中，可以省略前导零，例如 7。可以使用设置 parsedatetime_parse_without_leading_zeros = 0 恢复以前的行为。请注意，函数 formatDateTime 默认仍然会为 %c 和 %l/%k 打印前导零，以不打破现有用例。此行为可以通过设置 formatdatetime_format_without_leading_zeros = 1 更改。

注释 5：在 ClickHouse 版本早于 v25.5 时，函数 parseDateTime 对格式化器 %e 要求单个数字的天数填充空格，例如 3。在后来的版本中，可以选择填充空格，例如 3 和 3 均有效。要保留以前的行为，请设置 parsedatetime_e_requires_space_padding = 1。类似地，函数 formatDateTime 中的格式化器 %e 之前在单个印刷时无条件空格填充，而现在在不带前导空格的情况打印。要保留以前的行为，请设置 formatdatetime_e_with_space_padding = 1。

示例

结果：

结果：

此外，formatDateTime 函数可以接受一个包含时区名称的第三个字符串参数。例如：Asia/Istanbul。在这种情况下，时间将根据指定的时区进行格式化。

示例

另请参见

formatDateTimeInJodaSyntax​

与 formatDateTime 类似，不同之处在于它使用 Joda 风格格式化日期时间，而不是 MySQL 风格。请参考 https://joda-time.sourceforge.net/apidocs/org/joda/time/format/DateTimeFormat.html。

此函数的反操作是 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
'文本的转义分隔符
''单引号字面量'

示例

结果：

dateName​

返回指定的日期部分。

语法

参数

  • date_part — 日期部分。可能的值：'year'，'quarter'，'month'，'week'，'dayofyear'，'day'，'weekday'，'hour'，'minute'，'second'。字符串。
  • date — 日期。日期，Date32，DateTime 或 DateTime64。
  • timezone — 时区。可选。字符串。

返回值

示例

结果：

monthName​

返回月份的名称。

语法

参数

返回值

示例

结果：

fromUnixTimestamp​

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

可以用两种方式调用：

当给定一个整数类型的单个参数时，它返回一个日期时间类型的值，即类似于 toDateTime。

别名：FROM_UNIXTIME。

示例：

结果：

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

示例：

结果：

另请参见

fromUnixTimestampInJodaSyntax​

与 fromUnixTimestamp 相同，但在第二种方式 (两个或三个参数) 被调用时，格式化使用 Joda 风格，而不是 MySQL 风格。

示例：

结果：

toModifiedJulianDay​

将文本形式的 先验格里历 日期 YYYY-MM-DD 转换为 Int32 的 修正 Julian 日 数字。此函数支持从 0000-01-01 到 9999-12-31 的日期。如果参数不能被解析为日期或日期无效，将引发异常。

语法

参数

返回值

  • 修正 Julian 日数字。Int32。

示例

结果：

toModifiedJulianDayOrNull​

类似于 toModifiedJulianDay()，但不会引发异常，而是返回 NULL。

语法

参数

返回值

示例

结果：

fromModifiedJulianDay​

将 修正 Julian 日 数字转换为文本形式的 先验格里历 日期 YYYY-MM-DD。此函数支持范围从 -678941 到 2973483 的天数（分别表示 0000-01-01 和 9999-12-31）。如果天数超出了支持范围，将引发异常。

语法

参数

返回值

示例

结果：

fromModifiedJulianDayOrNull​

类似于 fromModifiedJulianDayOrNull()，但不会引发异常，而是返回 NULL。

语法

参数

返回值

示例

结果：

toUTCTimestamp​

将 DateTime/DateTime64 类型的值从其他时区转换为 UTC 时区的时间戳。此函数主要是为了与 Apache Spark 和类似框架的兼容性。

语法

参数

返回值

  • 文本形式的 DateTime/DateTime64

示例

结果：

fromUTCTimestamp​

将 DateTime/DateTime64 类型的值从 UTC 时区转换为其他时区的时间戳。此函数主要是为了与 Apache Spark 和类似框架的兼容性。

语法

参数

返回值

  • 文本形式的 DateTime/DateTime64

示例

结果：

UTCTimestamp​

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

备注

此函数的结果与 now('UTC') 相同。它仅是为了支持 MySQL 而添加，now 是首选用法。

语法

别名：UTC_timestamp。

返回值

  • 返回查询分析时的当前日期和时间。DateTime。

示例

查询：

结果：

timeDiff​

返回两个日期或含时间值的日期之间的差异。差异以秒为单位计算。它与 dateDiff 相同，仅为 MySQL 支持而添加。首选使用 dateDiff。

语法

参数

返回值

两个日期或含时间值的日期之间的差异（单位：秒）。

示例

查询：

结果：

相关内容​