处理日期和时间的函数
本节中的大多数函数接受一个可选的时区参数,例如 Europe/Amsterdam
。在这种情况下,时区是指定的,而不是本地(默认)时区。
示例
makeDate
从年份、月份和日期参数创建一个 Date
- 从年份、月份和日期参数,或
- 从年份和年份中的日期参数。
语法
别名:
MAKEDATE(year, month, day);
MAKEDATE(year, day_of_year);
参数
year
— 年。 Integer、Float 或 Decimal。month
— 月。 Integer、Float 或 Decimal。day
— 日。 Integer、Float 或 Decimal。day_of_year
— 年中的日期。 Integer、Float 或 Decimal。
返回值
- 从参数创建的日期。 Date。
示例
从年份、月份和日期创建一个日期:
结果:
从年份和年份中的日期参数创建一个日期:
结果:
makeDate32
从年份、月份、日(或可选的年份和一天)创建一个 Date32 类型的值。
语法
参数
year
— 年。 Integer、Float 或 Decimal。month
— 月(可选)。 Integer、Float 或 Decimal。day
— 日。 Integer、Float 或 Decimal。
如果省略 month
,则 day
应取值在 1
到 365
之间,否则它应取值在 1
到 31
之间。
返回值
- 从参数创建的日期。 Date32。
示例
从年份、月份和日期创建一个日期:
查询:
结果:
从年份和年份中的日期创建一个日期:
查询:
结果:
makeDateTime
从年份、月份、日、小时、分钟和秒参数创建一个 DateTime。
语法
参数
year
— 年。 Integer、Float 或 Decimal。month
— 月。 Integer、Float 或 Decimal。day
— 日。 Integer、Float 或 Decimal。hour
— 时。 Integer、Float 或 Decimal。minute
— 分。 Integer、Float 或 Decimal。second
— 秒。 Integer、Float 或 Decimal。timezone
— Timezone 用于返回值(可选)。
返回值
- 从参数创建的日期和时间。 DateTime。
示例
结果:
makeDateTime64
从其组件(年、月、日、小时、分钟、秒)创建一个 DateTime64 数据类型值。具有可选的亚秒精度。
语法
参数
year
— 年(0-9999)。 Integer、Float 或 Decimal。month
— 月(1-12)。 Integer、Float 或 Decimal。day
— 日(1-31)。 Integer、Float 或 Decimal。hour
— 时(0-23)。 Integer、Float 或 Decimal。minute
— 分(0-59)。 Integer、Float 或 Decimal。second
— 秒(0-59)。 Integer、Float 或 Decimal。precision
— 亚秒组成部分的可选精度(0-9)。 Integer。
返回值
- 从提供的参数创建的日期和时间。 DateTime64。
示例
timestamp
将第一个参数 'expr' 转换为 DateTime64(6) 类型。 如果提供了第二个参数 'expr_time',则将指定的时间添加到转换值。
语法
别名: TIMESTAMP
参数
示例
结果:
结果:
返回值
- DateTime64(6)
timeZone
返回当前会话的时区,即设定值 session_timezone 的值。 如果在分布式表的上下文中执行此函数,则生成一个正常列,其值与每个分片相关,否则返回一个常量值。
语法
别名: timezone
。
返回值
- 时区。 String。
示例
结果:
另见
serverTimeZone
返回服务器的时区,即设定值 timezone 的值。 如果在分布式表的上下文中执行此函数,则生成一个正常列,其值与每个分片相关。否则,返回一个常量值。
语法
别名: serverTimezone
。
返回值
- 时区。 String。
示例
结果:
另见
toTimeZone
将日期或日期时间转换为指定的时区。并不改变数据的内部值(unix秒数),只改变值的时区属性和字符串表示。
语法
别名: toTimezone
。
参数
value
— 时间或日期和时间。 DateTime64。timezone
— 返回值的时区。 String。 这个参数是常量,因为toTimezone
改变列的时区(timezone是DateTime*
类型的属性)。
返回值
- 日期和时间。 DateTime。
示例
结果:
另见
- formatDateTime - 支持非恒定时区。
- toString - 支持非恒定时区。
timeZoneOf
返回 DateTime 或 DateTime64 数据类型的时区名称。
语法
别名: timezoneOf
。
参数
value
— 日期和时间。 DateTime 或 DateTime64。
返回值
- 时区名称。 String。
示例
结果:
timeZoneOffset
返回与 UTC 的时区偏移(以秒为单位)。 该函数考虑了 夏令时 和指定日期时间的历史时区变化。 使用 IANA 时区数据库 计算偏移。
语法
别名: timezoneOffset
。
参数
value
— 日期和时间。 DateTime 或 DateTime64。
返回值
- 与 UTC 的偏移(以秒为单位)。 Int32。
示例
结果:
toYear
返回日期或日期时间的年份成分(公元)。
语法
别名: YEAR
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的年份。 UInt16。
示例
结果:
toQuarter
返回日期或日期时间的季度(1-4)。
语法
别名: QUARTER
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的季度(1、2、3 或 4)。 UInt8。
示例
结果:
toMonth
返回日期或日期时间的月份成分(1-12)。
语法
别名: MONTH
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的月份(1 - 12)。 UInt8。
示例
结果:
toDayOfYear
返回日期或日期时间在年内的天数(1-366)。
语法
别名: DAYOFYEAR
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的天数(1 - 366)。 UInt16。
示例
结果:
toDayOfMonth
返回日期或日期时间在月份中的天数(1-31)。
语法
别名: DAYOFMONTH
、DAY
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的天数(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 或 DateTime64mode
- 确定一周的第一天。可能的值为 0、1、2 或 3。请参见上表获取差异。timezone
- 可选参数,它的行为与其他任何转换函数相同
第一个参数也可以指定为 String,以 parseDateTime64BestEffort() 支持的格式。这种对字符串参数的支持仅出于与 MySQL 兼容的原因,某些第三方工具期待这样。由于字符串参数的支持可能在将来取决于新的 MySQL 兼容设置,并且字符串解析通常较慢,因此建议不要使用它。
返回值
- 所给日期/时间的星期几(1-7),取决于所选模式
示例
以下日期为 2023 年 4 月 21 日,为星期五:
结果:
toHour
返回带时间的日期的小时成分(0-24)。
假设如果时钟向前移动,则为一小时,并发生在凌晨 2 点;如果时钟向后移动,则为一小时,并发生在凌晨 3 点(这并不总是确切发生 - 取决于时区)。
语法
别名: HOUR
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期/时间的小时(0 - 23)。 UInt8。
示例
结果:
toMinute
返回带时间的日期的分钟成分(0-59)。
语法
别名: MINUTE
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期/时间的分钟(0 - 59)。 UInt8。
示例
结果:
toSecond
返回带时间的日期的秒成分(0-59)。不考虑闰秒。
语法
别名: SECOND
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期/时间的秒(0 - 59)。 UInt8。
示例
结果:
toMillisecond
返回带时间的日期的毫秒成分(0-999)。
语法
参数
value
- DateTime 或 DateTime64
别名: MILLISECOND
结果:
返回值
- 所给日期/时间的毫秒(0 - 59)。 UInt16。
toUnixTimestamp
将字符串、日期或带时间的日期转换为 UInt32
表示的 Unix 时间戳。
如果该函数以字符串形式调用,则接受一个可选的时区参数。
语法
返回值
- 返回 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
的值作为参数,但传递超出正常范围的时间(对于Date
从1970年到2149年/对于DateTime
为2106年)将产生错误结果。
- 函数
enable_extended_results_for_datetime_functions = 1
:- 函数
toStartOfYear
、toStartOfISOYear
、toStartOfQuarter
、toStartOfMonth
、toStartOfWeek
、toLastDayOfWeek
、toLastDayOfMonth
、toMonday
返回Date
或DateTime
(如果它们的参数是Date
或DateTime
),并且如果参数是Date32
或DateTime64
,则返回Date32
或DateTime64
。 - 函数
toStartOfDay
、toStartOfHour
、toStartOfFifteenMinutes
、toStartOfTenMinutes
、toStartOfFiveMinutes
、toStartOfMinute
、timeSlot
返回DateTime
(如果它们的参数是Date
或DateTime
),并且如果参数是Date32
或DateTime64
,则返回DateTime64
。
- 函数
toStartOfYear
将日期或日期时间向下取整到该年的第一天。返回值为 Date
对象。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 输入日期/时间的第一天。 Date。
示例
结果:
toStartOfISOYear
将日期或日期时间向下取整到 ISO 年的第一天,这可能与“常规”年份不同。(请参阅 https://en.wikipedia.org/wiki/ISO_week_date)。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 输入日期/时间的第一天。 Date。
示例
结果:
toStartOfQuarter
将日期或日期时间向下取整到该季度的第一天。季度的第一天为 1 月 1 日、4 月 1 日、7 月 1 日或 10 月 1 日。 返回日期。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的季度的第一天。 Date。
示例
结果:
toStartOfMonth
将日期或日期时间向下取整到该月的第一天。返回日期。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的月份的第一天。 Date。
示例
结果:
解析不正确日期的行为是实现特定的。 ClickHouse 可能返回零日期,抛出异常,或执行“自然”溢出。
toLastDayOfMonth
将日期或日期时间向上取整到该月的最后一天。返回日期。
语法
别名: LAST_DAY
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的月份的最后一天。 Date。
示例
结果:
toMonday
将日期或日期时间向下取整到最靠近的星期一。返回日期。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期最靠近的星期一或之前的日期。 Date。
示例
结果:
toStartOfWeek
将日期或日期时间向下取整到最靠近的星期天或星期一。返回日期。模式参数的工作方式与函数 toWeek()
中的模式参数完全相同。如果没有指定模式,则默认值为 0。
语法
参数
t
- Date、Date32、DateTime 或 DateTime64mode
- 确定一周的第一天,如 toWeek() 函数所述timezone
- 可选参数,它的行为与其他任何转换函数相同
返回值
- 最靠近给定日期的星期天或星期一的日期,具体取决于模式。 Date。
示例
结果:
toLastDayOfWeek
将日期或日期时间向上取整到最靠近的星期六或星期天。返回日期。
模式参数的工作方式与函数 toWeek()
中的模式参数完全相同。如果没有指定模式,则默认为 0。
语法
参数
t
- Date、Date32、DateTime 或 DateTime64mode
- 确定一周的最后一天,如 toWeek 函数所述timezone
- 可选参数,它的行为与其他任何转换函数相同
返回值
- 最靠近给定日期的星期天或星期一,具体取决于模式。 Date。
示例
结果:
toStartOfDay
将带时间的日期向下取整到该天的开始。
语法
参数
value
- Date、Date32、DateTime 或 DateTime64
返回值
- 所给日期/时间的开始。 DateTime。
示例
结果:
toStartOfHour
将带时间的日期向下取整到该小时的开始。
语法
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期/时间的开始(小时)。 DateTime。
示例
结果:
toStartOfMinute
将带时间的日期向下取整到该分钟的开始。
语法
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期/时间的开始(分钟)。 DateTime。
示例
结果:
toStartOfSecond
截断亚秒。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— Timezone 用于返回值(可选)。如果未指定,函数使用value
参数的时区。 String。
返回值
- 不带亚秒的输入值。 DateTime64。
示例
不带时区的查询:
结果:
带时区的查询:
结果:
另见
- Timezone 服务器配置参数。
toStartOfMillisecond
将带时间的日期向下取整到毫秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— Timezone 用于返回值(可选)。如果未指定,函数使用value
参数的时区。 String。
返回值
- 输入值带亚毫秒。 DateTime64。
示例
不带时区的查询:
结果:
带时区的查询:
结果:
toStartOfMicrosecond
将带时间的日期向下取整到微秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— Timezone 用于返回值(可选)。如果未指定,函数使用value
参数的时区。 String。
返回值
- 输入值带亚微秒。 DateTime64。
示例
不带时区的查询:
结果:
带时区的查询:
结果:
另见
- Timezone 服务器配置参数。
toStartOfNanosecond
将带时间的日期向下取整到纳秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— Timezone 用于返回值(可选)。如果未指定,函数使用value
参数的时区。 String。
返回值
- 输入值带纳秒。 DateTime64。
示例
不带时区的查询:
结果:
带时区的查询:
结果:
另见
- Timezone 服务器配置参数。
toStartOfFiveMinutes
将带时间的日期向下取整到五分钟间隔的开始。
语法
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期时间的五分钟间隔的开始。 DateTime。
示例
结果:
toStartOfTenMinutes
将带时间的日期向下取整到十分钟间隔的开始。
语法
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期时间的十分钟间隔的开始。 DateTime。
示例
结果:
toStartOfFifteenMinutes
将带时间的日期取整到十五分钟间隔的开始。
语法
参数
value
- DateTime 或 DateTime64
返回值
- 所给日期时间的十五分钟间隔的开始。 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)
相同的结果。
计算是相对于特定时间点进行的:
Interval | Start |
---|---|
YEAR | year 0 |
QUARTER | 1900 Q1 |
MONTH | 1900 January |
WEEK | 1970, 1st week (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 之间的小时值是有用的。
如果指定了单位 WEEK
,则 toStartOfInterval
假定周一为一周的开始。请注意,这种行为与函数 toStartOfWeek
不同,在该函数中,周日为默认的一周开始。
语法
别名: time_bucket
, date_bin
。
第二个重载模拟了 TimescaleDB 的 time_bucket()
函数,分别是 PostgreSQL 的 date_bin()
函数,例如:
结果:
参见
toTime
将带时间的日期转换为某个固定日期,同时保留时间。
语法
参数
date
— 要转换为时间的日期。 Date/DateTime/DateTime64。timezone
(可选) — 返回值的时区。 String。
返回值
- DateTime,日期等于
1970-01-02
,同时保留时间。 DateTime。
如果输入参数 date
包含小于一秒的组件,
它们将在返回的 DateTime
值中以秒为精度被舍弃。
示例
查询:
结果:
toRelativeYearNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的年数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的年数。 UInt16。
示例
查询:
结果:
toRelativeQuarterNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的季度数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的季度数。 UInt32。
示例
查询:
结果:
toRelativeMonthNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的月数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的月数。 UInt32。
示例
查询:
结果:
toRelativeWeekNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的周数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的周数。 UInt32。
示例
查询:
结果:
toRelativeDayNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的天数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的天数。 UInt32。
示例
查询:
结果:
toRelativeHourNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的小时数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的小时数。 UInt32。
示例
查询:
结果:
toRelativeMinuteNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的分钟数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的分钟数。 UInt32。
示例
查询:
结果:
toRelativeSecondNum
将日期或带时间的日期转换为自某个过去固定时间点以来经过的秒数。
语法
参数
date
— 日期或带时间的日期。 Date/DateTime/DateTime64。
返回值
- 从过去某个固定参考点计算的秒数。 UInt32。
示例
查询:
结果:
toISOYear
将日期或带时间的日期转换为 ISO 年,返回 UInt16 类型的数字。
语法
参数
value
— 带日期或带时间的值。 Date、Date32、DateTime 或 DateTime64
返回值
- 输入值转换为 ISO 年的数字。 UInt16。
示例
查询:
结果:
toISOWeek
将日期或带时间的日期转换为包含 ISO 周数的 UInt8 数字。
语法
参数
value
— 带日期或带时间的值。
返回值
value
转换为当前 ISO 周数。 UInt8。
示例
查询:
响应:
toWeek
此函数返回日期或日期时间的周数。 toWeek()
的两参数形式允许您指定一周是从周日开始还是周一开始,以及返回值是否应在 0 到 53 或 1 到 53 的范围内。如果省略 mode 参数,默认模式为 0。
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 天或更多天”模式的值,周按照 ISO 8601:1988 编号:
-
如果包含 1 月 1 日的周在新的一年中有 4 天或更多天,则这一周为第 1 周。
-
否则,它为前一年的最后一周,下一周为第 1 周。
适用于“包含 1 月 1 日”模式的值,其包含 1 月 1 日的那一周为第 1 周。 即使该周在新的一年中仅包含一天,结果也不影响。 也就是说,如果 12 月的最后一周包含下一年的 1 月 1 日,则该周为下一年的第 1 周。
语法
别名: WEEK
参数
t
– 日期或日期时间。mode
– 可选参数,值的范围为 [0,9],默认为 0。Timezone
– 可选参数,表现得像其他转换函数。
第一个参数也可以指定为 String,格式由 parseDateTime64BestEffort() 支持。仅出于与某些第三方工具的 MySQL 兼容理由而存在字符串参数支持。因为字符串参数的支持在将来可能会依赖于新的 MySQL 兼容设置,并且字符串解析通常比较慢,建议不要使用它。
示例
toYearWeek
返回日期的年份和周数。结果中的年份可能与日期参数中的年份不同,适用于年份的第一周和最后一周。
mode 参数的工作方式与 toWeek()
的 mode 参数相同。对于单参数语法,使用 0 的 mode 值。
toISOYear()
是兼容函数,相当于 intDiv(toYearWeek(date,3),100)
。
toYearWeek()
返回的周数与 toWeek()
返回的周数可能不同。toWeek()
总是在给定年份的上下文中返回周数,如果 toWeek()
返回 0
,则 toYearWeek()
返回对应于上一年最后一周的值。请参阅下面示例中的 prev_yearWeek
。
语法
别名: YEARWEEK
第一个参数也可以指定为 String,格式由 parseDateTime64BestEffort() 支持。仅出于与某些第三方工具的 MySQL 兼容理由而存在字符串参数支持。因为字符串参数的支持在将来可能会依赖于新的 MySQL 兼容设置,并且字符串解析通常比较慢,建议不要使用它。
示例
toDaysSinceYearZero
在 ISO 8601 定义的先行公历 中返回给定日期自 公元 0000 年 1 月 1 日 以来经过的天数。计算方式与 MySQL 的 TO_DAYS()
函数相同。
语法
别名: TO_DAYS
参数
date
— 计算自公元零年以来经过的天数的日期。 Date、Date32、DateTime 或 DateTime64。time_zone
— 字符串类型常量值或表示时区的表达式。 String types
返回值
自日期 0000-01-01 以来经过的天数。 UInt32。
示例
结果:
参见
fromDaysSinceYearZero
返回给定的自 公元 0000 年 1 月 1 日 以来经过的天数对应的日期,在 ISO 8601 定义的先行公历 中。计算方式与 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)。
如果指定了单位 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。
返回值
如果 unit 参数为 Year、Quarter、Month 或 Week,
如果 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。
返回值
通过将以 unit
表达的 value
加到 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。
返回值
通过将以 unit
表达的 value
从 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
返回值
在指定的 unit
中运算后,日期或带时间的日期。 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。
返回值
通过将以 unit
表达的 value
从 date
中减去获得的日期或带时间的日期。 Date、Date32、DateTime 或 DateTime64。
示例
结果:
addDate
将时间间隔加到提供的日期、日期时间或字符串编码的日期/日期时间上。
如果加法结果超出数据类型的范围,则结果未定义。
语法
参数
date
— 要加上interval
的日期或带时间的日期。 Date、Date32、DateTime、DateTime64 或 Stringinterval
— 要加的间隔。 Interval。
返回值
通过将 interval
加到 date
上获得的日期或带时间的日期。 Date、Date32、DateTime 或 DateTime64。
示例
结果:
别名: ADDDATE
参见
subDate
从提供的日期、带时间的日期或字符串编码的日期/日期时间中减去时间间隔。
如果减法结果超出数据类型的范围,则结果未定义。
语法
参数
date
— 要从中减去interval
的日期或带时间的日期。 Date、Date32、DateTime、DateTime64 或 Stringinterval
— 要减去的间隔。 Interval。
返回值
通过将 interval
从 date
中减去获得的日期或带时间的日期。 Date、Date32、DateTime 或 DateTime64。
示例
结果:
别名: SUBDATE
参见
now
返回查询解析时当前的日期和时间。此函数是一个常量表达式。
别名: current_timestamp
。
语法
参数
返回值
- 当前的日期和时间。 DateTime。
示例
不带时区的查询:
结果:
带指定时区的查询:
结果:
now64
返回查询解析时当前的日期和时间,带有子秒精度。此函数是一个常量表达式。
语法
参数
scale
- 时间戳精度: 10-precision 秒。有效范围:[ 0 : 9 ]。通常使用 - 3(默认)(毫秒)、6(微秒)、9(纳秒)。timezone
— 返回值的 时区名称(可选)。 String。
返回值
- 当前日期和时间,带有子秒的精度。 DateTime64。
示例
结果:
nowInBlock
返回在每个数据块处理时的当前日期和时间。与函数 now 不同,它不是常量表达式,对于长时间运行的查询,不同的块返回的值可能不同。
在长时间运行的 INSERT SELECT 查询中生成当前时间时使用此函数是有意义的。
语法
参数
返回值
- 在每个数据块处理时的当前日期和时间。 DateTime。
示例
结果:
today
返回查询解析时的当前日期。它与 'toDate(now())' 相同,并具有别名: curdate
, current_date
。
语法
参数
- 无
返回值
- 当前日期。 DateTime。
示例
查询:
结果:
在 2024 年 3 月 3 日运行上述查询将返回以下响应:
yesterday
接受零个参数并返回查询解析时的昨天的日期。 与 'today() - 1' 相同。
timeSlot
将时间四舍五入到半小时长度区间的开始。
语法
参数
time
— 要四舍五入到半小时长度区间开始的时间。 DateTime/Date32/DateTime64。time_zone
— 表示时区的字符串类型常量值或表达式。 String。
尽管此函数可以接受扩展类型 Date32
和 DateTime64
的值作为参数,但传递超出正常范围的时间(对于 Date
的年限为 1970 到 2149 / 对于 DateTime
为 2106)将会产生错误的结果。
返回类型
- 返回四舍五入到半小时长度区间开始的时间。 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()
函数的反向操作。
语法
参数
返回值
- 从参数创建的带时间的日期。 DateTime。
示例
结果:
YYYYMMDDhhmmssToDateTime64
与 YYYYMMDDhhmmssToDate()
函数类似,但生成一个 DateTime64。
在 timezone
参数后接受一个额外的可选 precision
参数。
changeYear
更改日期或带时间日期的年份组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的年份值。 Integer。
返回值
- 与
date_or_datetime
相同的类型。
示例
结果:
changeMonth
更改日期或带时间日期的月份组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的月份值。 Integer。
返回值
- 返回与
date_or_datetime
相同类型的值。
示例
结果:
changeDay
更改日期或带时间日期的日期组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的日期值。 Integer。
返回值
- 返回与
date_or_datetime
相同类型的值。
示例
结果:
changeHour
更改日期或带时间日期的小时组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的小时值。 Integer。
返回值
- 返回与
date_or_datetime
相同类型的值。如果输入是 Date,返回 DateTime。如果输入是 Date32,返回 DateTime64。
示例
结果:
changeMinute
更改日期或带时间日期的分钟组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的分钟值。 Integer。
返回值
- 返回与
date_or_datetime
相同类型的值。如果输入是 Date,返回 DateTime。如果输入是 Date32,返回 DateTime64。
示例
结果:
changeSecond
更改日期或带时间日期的秒组件。
语法
参数
date_or_datetime
- 一个 Date、Date32、DateTime 或 DateTime64value
- 新的秒值。 Integer。
返回值
- 返回与
date_or_datetime
相同类型的值。如果输入是 Date,返回 DateTime。如果输入是 Date32,返回 DateTime64。
示例
结果:
addYears
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的年份。
语法
参数
返回值
- 返回
date
加上num
年。 Date/Date32/DateTime/DateTime64。
示例
addQuarters
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的季度。
语法
参数
返回值
- 返回
date
加上num
季度。 Date/Date32/DateTime/DateTime64。
示例
addMonths
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的月份。
语法
参数
返回值
- 返回
date
加上num
月份。 Date/Date32/DateTime/DateTime64。
示例
addWeeks
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的周。
语法
参数
返回值
- 返回
date
加上num
周。 Date/Date32/DateTime/DateTime64。
示例
addDays
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的天。
语法
参数
返回值
- 返回
date
加上num
天。 Date/Date32/DateTime/DateTime64。
示例
addHours
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的小时。
语法
参数
返回值 o
- 返回
date
加上num
小时。 Date/Date32/DateTime/DateTime64。
示例
addMinutes
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的分钟。
语法
参数
返回值
- 返回
date
加上num
分钟。 Date/Date32/DateTime/DateTime64。
示例
addSeconds
向日期、带时间的日期或字符串编码的日期/带时间的日期添加指定数量的秒。
语法
参数
返回值
- 返回
date
加上num
秒。 Date/Date32/DateTime/DateTime64。
示例
addMilliseconds
向带时间的日期或字符串编码的带时间的日期添加指定数量的毫秒。
语法
参数
date_time
: 带时间的日期,增加指定数量的毫秒。 DateTime/DateTime64、String。num
: 要添加的毫秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
加上num
毫秒。 DateTime64。
示例
addMicroseconds
向带时间的日期或字符串编码的带时间的日期添加指定数量的微秒。
语法
参数
date_time
: 带时间的日期,增加指定数量的微秒。 DateTime/DateTime64、String。num
: 要添加的微秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
加上num
微秒。 DateTime64。
示例
addNanoseconds
向带时间的日期或字符串编码的带时间的日期添加指定数量的纳秒。
语法
参数
date_time
: 带时间的日期,增加指定数量的纳秒。 DateTime/DateTime64、String。num
: 要添加的纳秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
加上num
纳秒。 DateTime64。
示例
addInterval
将一个区间添加到另一个区间或区间的元组中。
语法
参数
返回值
同类型的区间将被组合成单个区间。例如,如果传递了 toIntervalDay(1)
和 toIntervalDay(2)
,则结果将是 (3)
而不是 (1,1)
。
示例
查询:
结果:
addTupleOfIntervals
将一个区间的元组连续地添加到 Date 或 DateTime。
语法
参数
返回值
- 返回加上
intervals
的date
。 date/date32/datetime/datetime64。
示例
查询:
结果:
subtractYears
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的年份。
语法
参数
返回值
- 返回
date
减去num
年。 Date/Date32/DateTime/DateTime64。
示例
subtractQuarters
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的季度。
语法
参数
返回值
- 返回
date
减去num
季度。 Date/Date32/DateTime/DateTime64。
示例
subtractMonths
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的月份。
语法
参数
返回值
- 返回
date
减去num
月份。 Date/Date32/DateTime/DateTime64。
示例
subtractWeeks
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的周。
语法
参数
返回值
- 返回
date
减去num
周。 Date/Date32/DateTime/DateTime64。
示例
subtractDays
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的天。
语法
参数
返回值
- 返回
date
减去num
天。 Date/Date32/DateTime/DateTime64。
示例
subtractHours
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的小时。
语法
参数
返回值
- 返回
date
减去num
小时。 Date/Date32/Datetime/DateTime64。
示例
结果:
subtractMinutes
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的分钟。
语法
参数
返回值
- 返回
date
减去num
分钟。 Date/Date32/DateTime/DateTime64。
示例
结果:
subtractSeconds
从日期、带时间的日期或字符串编码的日期/带时间的日期中减去指定数量的秒。
语法
参数
返回值
- 返回
date
减去num
秒。 Date/Date32/DateTime/DateTime64。
示例
结果:
subtractMilliseconds
从带时间的日期或字符串编码的带时间的日期中减去指定数量的毫秒。
语法
参数
date_time
: 带时间的日期,从中减去指定数量的毫秒。 DateTime/DateTime64、String。num
: 要减去的毫秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
减去num
毫秒。 DateTime64。
示例
结果:
subtractMicroseconds
从带时间的日期或字符串编码的带时间的日期中减去指定数量的微秒。
语法
参数
date_time
: 带时间的日期,从中减去指定数量的微秒。 DateTime/DateTime64、String。num
: 要减去的微秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
减去num
微秒。 DateTime64。
示例
结果:
subtractNanoseconds
从带时间的日期或字符串编码的带时间的日期中减去指定数量的纳秒。
语法
参数
date_time
: 带时间的日期,从中减去指定数量的纳秒。 DateTime/DateTime64、String。num
: 要减去的纳秒数。 (U)Int*、Float*。
返回值
- 返回
date_time
减去num
纳秒。 DateTime64。
示例
结果:
subtractInterval
将负的区间添加到另一个区间或区间的元组中。
语法
参数
返回值
同类型的区间将被组合成单个区间。例如,如果传递了 toIntervalDay(2)
和 toIntervalDay(1)
,则结果将是 (1)
而不是 (2,1)
示例
查询:
结果:
subtractTupleOfIntervals
连续地从 Date 或 DateTime 中减去区间的元组。
语法
参数
返回值
- 返回减去
intervals
的date
。 Date/Date32/DateTime/DateTime64。
示例
查询:
结果:
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 | 简写的月份名称(1月-12月) | Jan |
%c | 作为整数(01-12)表示的月份,参见下面的“注释 4” | 01 |
%C | 年份除以 100 后向下取整(00-99) | 20 |
%d | 零填充的月份中的日期(01-31) | 02 |
%D | 短格式 MM/DD/YY 日期,相当于 %m/%d/%y | 01/02/18 |
%e | 零填充的月份中的日期( 1-31),参见下面的“注释 5” | 2 |
%f | 小数秒,参见下面的“注释 1”和“注释 2” | 123456 |
%F | 短格式 YYYY-MM-DD 日期,相当于 %Y-%m-%d | 2018-01-02 |
%g | 两位数字的年份格式,符合 ISO 8601,缩写自四位数字表示法 | 18 |
%G | ISO 周号的四位数字年份格式,按照 ISO 8601 标准计算的基于周的年份,通常仅与 %V 一起使用 | 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),参见下面的“注释 4” | 14 |
%l | 12 小时制格式的小时(01-12),参见下面的“注释 4” | 09 |
%m | 作为整数(01-12)表示的月份 | 01 |
%M | 完整的月份名称(1月-12月),参见下面的“注释 3” | 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 |
%y | 年,最后两位数字(00-99) | 18 |
%Y | 年 | 2018 |
%z | 相对于 UTC 的时间偏移,格式为 +HHMM 或 -HHMM | -0500 |
%% | 一个 % 符号 | % |
注释 1:在 ClickHouse v23.4 之前的版本中,如果格式化值为 Date,Date32 或 DateTime(没有小数秒)或 DateTime64 的精度为 0,则 %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)而不是完整的月份名称(1月-12月)。可以通过设置 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
返回月份名称。
语法
参数
date
— 日期或带时间的日期。日期, DateTime 或 DateTime64。
返回值
- 月份名称。字符串
示例
结果:
fromUnixTimestamp
此函数将 Unix 时间戳转换为日历日期和一天的时间。
它可以以两种方式调用:
当给定一个类型为 整数 的单个参数时,返回一个类型为 DateTime 的值,即表现得像是 toDateTime。
别名:FROM_UNIXTIME
。
示例:
结果:
当给定两个或三个参数时,第一个参数是类型为 整数、日期、Date32、DateTime 或 DateTime64 的值,第二个参数是常量格式字符串,第三个参数是一个可选的常量时区字符串,该函数返回一个类型为 字符串 的值,即它的表现像 formatDateTime。在这种情况下,使用 MySQL 的日期时间格式样式。
示例:
结果:
另请参见
fromUnixTimestampInJodaSyntax
与 fromUnixTimestamp 相同,但当以第二种方式调用(两个或三个参数)时,格式化使用 Joda 风格,而不是 MySQL 风格。
示例:
结果:
toModifiedJulianDay
将文本形式的 先历格里历 日期 YYYY-MM-DD
转换为 Int32 的 修订过的 Julian Day 数字。此函数支持从 0000-01-01
到 9999-12-31
的日期。如果参数无法解析为日期,或者该日期无效,则会引发异常。
语法
参数
返回值
- 修订过的 Julian Day 数字。Int32。
示例
结果:
toModifiedJulianDayOrNull
类似于 toModifiedJulianDay(),但不引发异常,而是返回 NULL
。
语法
参数
返回值
- 修订过的 Julian Day 数字。Nullable(Int32)。
示例
结果:
fromModifiedJulianDay
将 修订过的 Julian Day 数字转换为文本形式的 先历格里历 日期 YYYY-MM-DD
。此函数支持从 -678941
到 2973483
的天数(分别对应于 0000-01-01 和 9999-12-31)。如果天数超出支持的范围,则会引发异常。
语法
参数
day
— 修订过的 Julian Day 数字。任何整型。
返回值
- 文本形式的日期。字符串
示例
结果:
fromModifiedJulianDayOrNull
类似于 fromModifiedJulianDayOrNull(),但不引发异常,而是返回 NULL
。
语法
参数
day
— 修订过的 Julian Day 数字。任何整型。
返回值
- 文本形式的日期。Nullable(String)
示例
结果:
toUTCTimestamp
将 DateTime/DateTime64 类型的值从其他时区转换为 UTC 时区的时间戳。此函数主要用于与 Apache Spark 和类似框架的兼容性。
语法
参数
time_val
— DateTime/DateTime64 类型的常量值或表达式。DateTime/DateTime64 类型time_zone
— 字符串类型的常量值或表示时区的表达式。字符串类型
返回值
- 文本形式的 DateTime/DateTime64
示例
结果:
fromUTCTimestamp
将 DateTime/DateTime64 类型的值从 UTC 时区转换为其他时区的时间戳。此函数主要用于与 Apache Spark 和类似框架的兼容性。
语法
参数
time_val
— DateTime/DateTime64 类型的常量值或表达式。DateTime/DateTime64 类型time_zone
— 字符串类型的常量值或表示时区的表达式。字符串类型
返回值
- 文本形式的 DateTime/DateTime64
示例
结果:
UTCTimestamp
返回查询分析时的当前日期和时间。该函数是常量表达式。
此函数提供的结果与 now('UTC')
相同。它仅为了支持 MySQL 而添加,而 now
是首选用法。
语法
别名:UTC_timestamp
。
返回值
- 返回查询分析时的当前日期和时间。DateTime。
示例
查询:
结果:
timeDiff
返回两个日期或日期时间值之间的差值。差值以秒为单位计算。它与 dateDiff
相同,仅用于支持 MySQL。dateDiff
更受欢迎。
语法
参数
first_datetime
— DateTime/DateTime64 类型的常量值或表达式。DateTime/DateTime64 类型second_datetime
— DateTime/DateTime64 类型的常量值或表达式。DateTime/DateTime64 类型
返回值
两个日期或日期时间值之间的差值(以秒为单位)。
示例
查询:
结果: