处理日期和时间的函数
本节中的大多数函数接受一个可选的时区参数,例如 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
— 返回值的 时区(可选)。
返回值
- 从参数创建的日期和时间。 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
更改列的时区(时区是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
- 可选参数,它的行为类似于其他转换函数。
第一个参数也可以指定为支持 parseDateTime64BestEffort() 的格式的 String。出于与期望某些第三方工具的 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 - 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 对于Date
/ 2106 对于DateTime
)将产生错误的结果。
- 函数
- 当
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
如果其参数是Date
或DateTime
,则返回DateTime
,如果其参数是Date32
或DateTime64
,则返回DateTime64
。
- 函数
toStartOfYear
将日期或带时间的日期向下取整到该年的第一天。返回的日期为 Date
对象。
语法
参数
value
- 一个 Date、Date32、DateTime 或 DateTime64
返回值
- 输入的日期/时间的第一天。 Date。
示例
结果:
toStartOfISOYear
将日期或带时间的日期向下取整到 ISO 年的第一天,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
将日期或带时间的日期向下取整到最近的星期天或星期一。返回日期。mode 参数的工作方式与函数 toWeek()
中的 mode 参数完全相同。如果未指定模式,则默认为 0。
语法
参数
t
- 一个 Date、Date32、DateTime 或 DateTime64mode
- 确定星期的第一天,如 toWeek() 函数所述timezone
- 可选参数,其行为类似于其他转换函数
返回值
- 最近的星期天或星期一的日期,具体取决于模式。Date。
示例
结果:
toLastDayOfWeek
将日期或带时间的日期向上取整到最近的星期六或星期天。返回日期。
mode 参数的工作方式与函数 toWeek()
中的 mode 参数完全相同。如果未指定模式,则假定模式为 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
— 返回值的 时区(可选)。如果未指定,则函数使用value
参数的时区。String。
返回值
- 输入值不带子秒。DateTime64。
示例
没有时区的查询:
结果:
带时区的查询:
结果:
另见
- 时区 服务器配置参数。
toStartOfMillisecond
将带时间的日期向下取整到毫秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— 返回值的 时区(可选)。如果未指定,则函数使用value
参数的时区。String。
返回值
- 输入值带子毫秒。DateTime64。
示例
没有时区的查询:
结果:
带时区的查询:
结果:
另见
- 时区 服务器配置参数。
toStartOfMicrosecond
将带时间的日期向下取整到微秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— 返回值的 时区(可选)。如果未指定,则函数使用value
参数的时区。String。
返回值
- 输入值带子微秒。DateTime64。
示例
没有时区的查询:
结果:
带时区的查询:
结果:
另见
- 时区 服务器配置参数。
toStartOfNanosecond
将带时间的日期向下取整到纳秒的开始。
语法
参数
value
— 日期和时间。 DateTime64。timezone
— 返回值的 时区(可选)。如果未指定,则函数使用value
参数的时区。String。
返回值
- 输入值带纳秒。DateTime64。
示例
没有时区的查询:
结果:
带时区的查询:
结果:
另见
- 时区 服务器配置参数。
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)
相同。
计算是相对于特定时间点进行的:
间隔 | 开始 |
---|---|
YEAR | 年 0 |
QUARTER | 1900 年第一季度 |
MONTH | 1900 年一月 |
WEEK | 1970 年第一周 (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 参数的工作方式。
模式 | 一周的第一天 | 范围 | 第 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 | 包含一月一日 |
9 | 星期一 | 1-53 | 包含一月一日 |
对于含有“包含本年 4 天或更多的日子”的模式值,周数根据 ISO 8601:1988 编号:
-
如果包含一月一日的那一周在新年中有 4 天或更多,则它为第 1 周。
-
否则,它是前一年的最后一周,下一周为第 1 周。
对于“包含一月一日”的模式值,包含一月一日的那一周即为第 1 周。 无论该周在新年中包含多少天,即使只包含一天。 例如,如果 12 月的最后一周包含下一年的一月一日,那么它将成为下一年的第 1 周。
语法
别名:WEEK
参数
t
– 日期或日期时间。mode
– 可选参数,取值范围为 [0,9],默认为 0。timezone
– 可选参数,其行为类似于其他转换函数。
第一个参数也可以作为 String 指定,格式为 parseDateTime64BestEffort() 所支持的格式。字符串参数的支持仅出于与 MySQL 的兼容性,特定第三方工具期望使用此格式。由于字符串参数的支持可能在未来依赖新的 MySQL 兼容性设置,并且字符串解析通常较慢,因此不建议使用它。
示例
toYearWeek
返回日期的年份和周数。结果中的年份可能与日期参数中的年份不同,特别是在年初和年末的第一周和最后一周。
mode 参数与 toWeek()
的 mode 参数工作方式相同。对于单参数语法,使用模式值 0。
toISOYear()
是一个兼容性函数,相当于 intDiv(toYearWeek(date,3),100)
。
toYearWeek()
返回的周数可能与 toWeek()
返回的周数不同。toWeek()
总是返回给定年份中的周数,如果 toWeek()
返回 0
,则 toYearWeek()
返回对应于上一年的最后一周的值。请参见下面示例中的 prev_yearWeek
。
语法
别名:YEARWEEK
第一个参数也可以作为 String 指定,格式为 parseDateTime64BestEffort() 所支持的格式。字符串参数的支持仅出于与 MySQL 的兼容性,特定第三方工具期望使用此格式。由于字符串参数的支持可能在未来依赖新的 MySQL 兼容性设置,并且字符串解析通常较慢,因此不建议使用它。
示例
toDaysSinceYearZero
返回给定日期以来,自 公元 1 年 1 月 1 日 在 ISO 8601 定义的前瞻性公历 中经过的天数。计算与 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](#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
— 截断结果的间隔类型。 字符串字面值。 可能的值:nanosecond
- 仅与 DateTime64 兼容microsecond
- 仅与 DateTime64 兼容milisecond
- 仅与 DateTime64 兼容second
minute
hour
day
week
month
quarter
year
unit
参数不区分大小写。 -
value
— 日期和时间。 Date、Date32、DateTime 或 DateTime64。
返回值
- 被截断为指定日期部分的值。 DateTime。
示例
没有时区查询:
结果:
指定时区的查询:
结果:
参见
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。
返回值
通过从 date
中减去以 unit
表示的 value
获得的日期或日期时间。 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
表示的指定 value
添加到 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。
返回值
通过从 date
中减去以 unit
表示的 value
获得的日期或日期时间。Date、Date32、DateTime 或 DateTime64。
示例
结果:
addDate
将时间间隔添加到提供的日期、日期时间或字符串编码的日期/日期时间。
如果添加的结果超出数据类型的范围,结果未定义。
语法
参数
返回值
通过将 interval
添加到 date
获得的日期或日期时间。Date、Date32、DateTime 或 DateTime64。
示例
结果:
别名: ADDDATE
参见
subDate
从提供的日期、日期时间或字符串编码的日期/日期时间中减去时间间隔。
如果减去的结果超出数据类型的范围,结果未定义。
语法
参数
date
— 要从中减去interval
的日期或日期时间。Date、Date32、DateTime、DateTime64 或 String。interval
— 要减去的间隔。Interval。
返回值
通过从 date
中减去 interval
获得的日期或日期时间。Date、Date32、DateTime 或 DateTime64。
示例
结果:
别名: SUBDATE
参见
now
返回查询分析时的当前日期和时间。该函数是常量表达式。
别名: current_timestamp
。
语法
参数
返回值
- 当前日期和时间。 DateTime。
示例
没有时区的查询:
结果:
指定时区的查询:
结果:
now64
返回查询分析时当前日期和时间的亚秒精度。该函数是常量表达式。
语法
参数
scale
- Tick 大小(精度):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。
如果输入不编码有效的日期值,则输出未定义。
语法
参数
返回值
- 从参数中创建的日期。 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
向日期、日期时间或字符串编码的日期/日期时间添加指定数量的小时。
语法
参数
返回值
- 返回
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
逐个将间隔元组添加到日期或日期时间。
语法
参数
返回值
- 返回添加了
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
连续地从一个日期或一个带时间的日期中减去一组间隔。
语法
参数
返回值
- 返回减去
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) | 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 | 新行字符 ('\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') | |
%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 时,如果格式化值是日期、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),而不是完整的月份名称(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
来更改。
示例
结果:
结果:
此外,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'。 String。date
— 日期。 Date、Date32、DateTime 或 DateTime64。timezone
— 时区。可选。 String。
返回值
- 返回日期的指定部分。 String
示例
结果:
monthName
返回月份的名称。
语法
参数
date
— 日期或带时间的日期。 Date、DateTime 或 DateTime64。
返回值
- 返回月份的名称。 String
示例
结果:
fromUnixTimestamp
这个函数将 Unix 时间戳转换为日历日期和一天中的时间。
它可以通过两种方式调用:
当给定一个类型为 Integer 的单一参数时,它返回一个类型为 DateTime 的值,行为类似于 toDateTime。
别名: FROM_UNIXTIME
。
示例:
结果:
当给定两个或三个参数时,第一个参数是类型为 Integer、Date、Date32、DateTime 或 DateTime64 的值,第二个参数是常量格式字符串,第三个参数是可选的常量时区字符串,函数返回一个类型为 String 的值,即它的行为类似于 formatDateTime。在这种情况下,使用的是 MySQL 的datetime格式样式。
示例:
结果:
另请参见
fromUnixTimestampInJodaSyntax
与 fromUnixTimestamp 相同,但在调用第二种方式(两个或三个参数)时,格式化使用的是 Joda 风格,而不是 MySQL 风格。
示例:
结果:
toModifiedJulianDay
将文本形式的 Proleptic Gregorian calendar 日期 YYYY-MM-DD
转换为 Modified Julian Day 数字,类型为 Int32。此函数支持日期范围从 0000-01-01
到 9999-12-31
。如果参数无法解析为日期,或者日期无效,则会引发异常。
语法
参数
date
— 文本形式的日期。类型为 String 或 FixedString 的值。
返回值
- Modified Julian Day 数字。类型为 Int32。
示例
结果:
toModifiedJulianDayOrNull
类似于 toModifiedJulianDay(),但不会引发异常,而是返回 NULL
。
语法
参数
date
— 文本形式的日期。类型为 String 或 FixedString 的值。
返回值
- Modified Julian Day 数字。类型为 Nullable(Int32)。
示例
结果:
fromModifiedJulianDay
将 Modified Julian Day 数字转换为文本形式的 Proleptic Gregorian calendar 日期 YYYY-MM-DD
。此函数支持的天数范围从 -678941
到 2973483
(分别表示 0000-01-01 和 9999-12-31)。如果天数超出支持范围,则会引发异常。
语法
参数
day
— Modified Julian Day 数字。类型为 Any integral types。
返回值
- 文本形式的日期。类型为 String。
示例
结果:
fromModifiedJulianDayOrNull
类似于 fromModifiedJulianDayOrNull(),但不会引发异常,而是返回 NULL
。
语法
参数
day
— Modified Julian Day 数字。类型为 Any integral types。
返回值
- 文本形式的日期。类型为 Nullable(String)。
示例
结果:
toUTCTimestamp
将 DateTime/DateTime64 类型值从其他时区转换为 UTC 时区时间戳。此函数主要是为了与 Apache Spark 和类似框架的兼容性而包含。
语法
参数
time_val
— 常量的 DateTime/DateTime64 类型值或表达式。 DateTime/DateTime64 typestime_zone
— 字符串类型的常量值或表示时区的表达式。 String types
返回值
- 文本形式的 DateTime/DateTime64。
示例
结果:
fromUTCTimestamp
将 DateTime/DateTime64 类型值从 UTC 时区转换为其他时区时间戳。此函数主要是为了与 Apache Spark 和类似框架的兼容性而包含。
语法
参数
time_val
— 常量的 DateTime/DateTime64 类型值或表达式。 DateTime/DateTime64 typestime_zone
— 字符串类型的常量值或表示时区的表达式。 String types
返回值
- 文本形式的 DateTime/DateTime64。
示例
结果:
UTCTimestamp
返回查询分析时刻的当前日期和时间。该函数是一个常量表达式。
此函数的结果与 now('UTC')
给出的结果相同。它的添加只是为了支持 MySQL,而 now
是推荐的用法。
语法
别名: UTC_timestamp
。
返回值
- 返回查询分析时刻的当前日期和时间。 DateTime。
示例
查询:
结果:
timeDiff
返回两个日期或带有时间值的日期之间的差异。差异以秒为单位计算。它与 dateDiff
相同,并且仅为 MySQL 的支持而添加。推荐使用 dateDiff
。
语法
参数
first_datetime
— 常量的 DateTime/DateTime64 类型值或表达式。 DateTime/DateTime64 typessecond_datetime
— 常量的 DateTime/DateTime64 类型值或表达式。 DateTime/DateTime64 types
返回值
两个日期或带有时间值的日期之间的差异,以秒为单位。
示例
查询:
结果: