处理日期和时间的函数
本节中的大多数函数接受一个可选的时区参数,例如 Europe/Amsterdam
。在这种情况下,时区是指定的,而不是本地(默认)时区。
示例
UTCTimestamp
引入于:v22.11
返回查询分析时的当前日期和时间。该函数是一个常量表达式。
这个函数给出的结果与 now('UTC')
相同。该函数仅为支持 MySQL 而添加。now
是推荐的用法。
语法
参数
- 无。 返回值
返回查询分析时的当前日期和时间。 DateTime
示例
获取当前 UTC 时间戳
YYYYMMDDToDate
引入于:v23.9
将包含年份、月份和日期的数字转换为一个 Date
。
此函数是函数 toYYYYMMDD()
的反向操作。
如果输入不编码有效的日期值,则输出未定义。
语法
参数
返回值
根据提供的参数返回一个 Date
值 Date
示例
示例
YYYYMMDDToDate32
引入于:v23.9
将包含年份、月份和日期的数字转换为一个 Date32
。
此函数是函数 toYYYYMMDD()
的反向操作。
如果输入不编码有效的 Date32
值,则输出未定义。
语法
参数
返回值
根据提供的参数返回一个 Date32
值 Date32
示例
示例
YYYYMMDDhhmmssToDateTime
引入于:v23.9
将包含年份、月份、日期、小时、分钟和秒的数字转换为一个 DateTime
。
此函数是函数 toYYYYMMDDhhmmss()
的反向操作。
如果输入不编码有效的 DateTime
值,则输出未定义。
语法
参数
返回值
根据提供的参数返回一个 DateTime
值 DateTime
示例
示例
YYYYMMDDhhmmssToDateTime64
引入于:v23.9
将包含年份、月份、日期、小时、分钟和秒的数字转换为一个 DateTime64
。
此函数是函数 toYYYYMMDDhhmmss()
的反向操作。
如果输入不编码有效的 DateTime64
值,则输出未定义。
语法
参数
YYYYMMDDhhmmss
— 包含年份、月份、日期、小时、分钟和秒的数字。(U)Int*
或Float*
或Decimal
precision
— 小数部分的精度(0-9)。UInt8
timezone
— 时区名称。String
返回值
根据提供的参数返回一个 DateTime64
值 DateTime64
示例
示例
addDate
引入于:v23.9
将时间间隔添加到指定的日期、日期和时间或字符串编码的日期或日期和时间中。 如果添加的结果超出数据类型的边界,则结果未定义。
语法
参数
datetime
— 将要添加interval
的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
interval
— 要添加的时间间隔。Interval
返回值
返回通过将 interval
添加到 datetime
得到的日期或带时间的日期。 Date
或 Date32
或 DateTime
或 DateTime64
示例
向日期添加时间间隔
addDays
引入于:v1.1
将指定数量的天数添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定天数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的天数。(U)Int*
或Float*
返回值
返回 datetime
加 num
天后的结果。 Date
或 Date32
或 DateTime
或 DateTime64
示例
向不同日期类型添加天数
使用替代的 INTERVAL 语法
addHours
引入于:v1.1
将指定数量的小时添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定小时数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的小时数。(U)Int*
或Float*
返回值
返回 datetime
加 num
小时后的结果 DateTime
或 DateTime64(3)
示例
向不同日期类型添加小时
使用替代的 INTERVAL 语法
addInterval
引入于:v22.11
将一个间隔添加到另一个间隔或间隔元组中。
相同类型的间隔将组合成一个单一的间隔。例如,如果传入 toIntervalDay(1)
和 toIntervalDay(2)
,则结果将是 (3)
而不是 (1,1)
。
语法
参数
interval_1
— 第一个间隔或间隔元组。Interval
或Tuple(Interval)
interval_2
— 要添加的第二个间隔。Interval
返回值
返回一个间隔元组 Tuple(Interval)
示例
添加间隔
addMicroseconds
引入于:v22.6
将指定数量的微秒添加到带时间的日期或字符串编码的带时间的日期中。
语法
参数
datetime
— 要添加指定数量微秒的带时间的日期。DateTime
或DateTime64
或String
num
— 要添加的微秒数。(U)Int*
或Float*
返回值
返回 date_time
加 num
微秒后的结果 DateTime64
示例
向不同的日期时间类型添加微秒
使用替代的 INTERVAL 语法
addMilliseconds
引入于:v22.6
将指定数量的毫秒添加到带时间的日期或字符串编码的带时间的日期中。
语法
参数
datetime
— 要添加指定数量毫秒的带时间的日期。DateTime
或DateTime64
或String
num
— 要添加的毫秒数。(U)Int*
或Float*
返回值
返回 datetime
加 num
毫秒后的结果 DateTime64
示例
向不同的日期时间类型添加毫秒
使用替代的 INTERVAL 语法
addMinutes
引入于:v1.1
将指定数量的分钟添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定分钟数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的分钟数。(U)Int*
或Float*
返回值
返回 datetime
加 num
分钟后的结果 DateTime
或 DateTime64(3)
示例
向不同日期类型添加分钟
使用替代的 INTERVAL 语法
addMonths
引入于:v1.1
将指定数量的月份添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定月份数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的月份数。(U)Int*
或Float*
返回值
返回 datetime
加 num
月份后的结果 Date
或 Date32
或 DateTime
或 DateTime64
示例
向不同日期类型添加月份
使用替代的 INTERVAL 语法
addNanoseconds
引入于:v22.6
将指定数量的纳秒添加到带时间的日期或字符串编码的带时间的日期中。
语法
参数
datetime
— 要添加指定数量纳秒的带时间的日期。DateTime
或DateTime64
或String
num
— 要添加的纳秒数。(U)Int*
或Float*
返回值
返回 datetime
加 num
纳秒后的结果 DateTime64
示例
向不同的日期时间类型添加纳秒
使用替代的 INTERVAL 语法
addQuarters
引入于:v20.1
将指定数量的季度添加到日期、带时间的日期或字符串编码的带时间的日期中。
语法
参数
datetime
— 要添加指定季度数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的季度数。(U)Int*
或Float*
返回值
返回 datetime
加 num
季度后的结果 Date
或 Date32
或 DateTime
或 DateTime64
示例
向不同日期类型添加季度
使用替代的 INTERVAL 语法
addSeconds
引入于:v1.1
将指定数量的秒添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定秒数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的秒数。(U)Int*
或Float*
返回值
返回 datetime
加 num
秒后的结果 DateTime
或 DateTime64(3)
示例
向不同日期类型添加秒数
使用替代的 INTERVAL 语法
addTupleOfIntervals
引入于:v22.11
连续将一组间隔添加到一个日期或带时间的日期中。
语法
参数
datetime
— 要添加间隔的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
intervals
— 要添加到datetime
的间隔元组。Tuple(Interval)
返回值
返回添加了 intervals
的日期 Date
或 Date32
或 DateTime
或 DateTime64
示例
向日期添加间隔元组
addWeeks
引入于:v1.1
将指定数量的周数添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定周数的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的周数。(U)Int*
或Float*
返回值
返回 datetime
加 num
周后的结果 Date
或 Date32
或 DateTime
或 DateTime64
示例
向不同日期类型添加周数
使用替代的 INTERVAL 语法
addYears
引入于:v1.1
将指定数量的年份添加到日期、带时间的日期或字符串编码的日期或带时间的日期中。
语法
参数
datetime
— 要添加指定年份的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要添加的年份数。(U)Int*
或Float*
返回值
返回 datetime
加 num
年后的结果 Date
或 Date32
或 DateTime
或 DateTime64
示例
向不同日期类型添加年份
使用替代的 INTERVAL 语法
age
引入于:v23.1
返回 startdate
和 enddate
之间的单位组件差异。
差异通过 1 纳秒的精度进行计算。
例如,2021-12-29 和 2022-01-01 之间的差异在天单位上是 3 天, 在月单位上是 0 个月,在年单位上是 0 年。
有关 age 的替代方法,请参见函数 timeDiff
。
语法
参数
unit
— 结果的间隔类型。
单位 | 可能值 |
---|---|
纳秒 | 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
返回值
返回以单位表示的 enddate
和 startdate
之间的差异。 Int32
示例
计算小时数的年龄
计算不同单位的年龄
changeDay
引入于:v24.7
更改日期或日期时间的日部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其日部分已修改。 Date
或 Date32
或 DateTime
或 DateTime64
示例
用法示例
changeHour
引入于:v24.7
更改日期或日期时间的小时部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其小时部分已修改。 DateTime
或 DateTime64
示例
用法示例
changeMinute
引入于:v24.7
更改 date or date time
的分钟部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其分钟部分已修改。 DateTime
或 DateTime64
示例
用法示例
changeMonth
引入于:v24.7
更改日期或日期时间的月份部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其月份部分已修改。 Date
或 Date32
或 DateTime
或 DateTime64
示例
用法示例
changeSecond
引入于:v24.7
更改日期或日期时间的秒部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其秒部分已修改。 DateTime
或 DateTime64
示例
用法示例
changeYear
引入于:v24.7
更改日期或日期时间的年份部分。
语法
参数
date_or_datetime
— 要更改的值。Date
或Date32
或DateTime
或DateTime64
value
— 新值。(U)Int*
返回值
返回与 date_or_datetime
同类型的值,其年份部分已修改。 Date
或 Date32
或 DateTime
或 DateTime64
示例
用法示例
dateName
引入于:v21.7
返回指定的日期部分。
可能值:
- 'year'
- 'quarter'
- 'month'
- 'week'
- 'dayofyear'
- 'day'
- 'weekday'
- 'hour'
- 'minute'
- 'second'
语法
参数
date_part
— 要提取的日期部分。String
datetime
— 日期或带时间的日期值。Date
或Date32
或DateTime
或DateTime64
timezone
— 可选。时区。String
返回值
返回指定的日期部分。 String
示例
提取不同的日期部分
dateTrunc
引入于:v20.8
将日期和时间值截断到指定的日期部分。
语法
参数
unit
— 截断结果的间隔类型。unit
参数不区分大小写。 | 单位 | 兼容性 | |--------------|-----------------------------| |nanosecond
| 仅与 DateTime64 兼容 | |microsecond
| 仅与 DateTime64 兼容 | |millisecond
| 仅与 DateTime64 兼容 | |second
| | |minute
| | |hour
| | |day
| | |week
| | |month
| | |quarter
| | |year
| |String
datetime
— 日期和时间。Date
或Date32
或DateTime
或DateTime64
timezone
— 可选。返回 datetime 的时区名称。如果未指定,函数将使用datetime
参数的时区。String
返回值
返回截断后的日期和时间值。
单位参数 | datetime 参数 | 返回类型 |
---|---|---|
年、季度、月、周 | Date32 或 DateTime64 或 Date 或 DateTime | Date32 或 Date |
天、小时、分钟、秒 | Date32 、DateTime64 、Date 或DateTime | DateTime64 或 DateTime |
毫秒、微秒、 | 任何 | DateTime64 |
纳秒 | 精度为 3、6 或 9 |
示例
无时区截断
带指定时区的截断
formatDateTime
引入于:v1.1
根据给定的格式字符串格式化日期或带时间的日期。format
是一个常量表达式,因此你不能为单个结果列使用多个格式。
formatDateTime
使用 MySQL 的日期时间格式风格,详情请参阅 mysql docs。
此函数的反向操作是 parseDateTime
。
使用替换字段,你可以定义结果字符串的模式。
下表中的示例列显示 2018-01-02 22:33:44
的格式化结果。
替换字段:
占位符 | 描述 | 示例 |
---|---|---|
%a | 缩写的星期几名称(周一-周日) | Mon |
%b | 缩写的月份名称(1月-12月) | 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 | 完整的月份名称(1月-12月) | 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 |
%% | 百分号 | % |
- 在 v23.4 之前的 ClickHouse 版本中,如果格式化值为 Date,Date32 或 DateTime(没有小数秒)或 DateTime64 的精度为 0,则
%f
会打印一个零(0)。 - 在 v25.1 之前的 ClickHouse 版本中,
%f
将打印 DateTime64 指定的位数而不是固定的 6 位数字。 - 在 v23.4 之前的 ClickHouse 版本中,
%M
打印分钟(00-59),而不是完整的月份名称(1月-12月)。
语法
参数
datetime
— 要格式化的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
format
— 带替换字段的格式字符串。String
timezone
— 可选。 格式化时间的时区名称。String
返回值
根据确定的格式返回时间和日期值。 String
示例
用年份占位符格式化日期
用小数秒格式化 DateTime64
带时区格式
formatDateTimeInJodaSyntax
引入于:v20.1
类似于 formatDateTime
,不同的是它以 Joda 风格格式化日期时间,而不是 MySQL 风格。请参阅 Joda Time documentation。
此函数的反向操作是 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 |
' | 文本的转义字符 | 分隔符 | |
'' | 单引号 | 文本 | ' |
语法
参数
datetime
— 要格式化的日期或带时间的日期。DateTime
或Date
或Date32
或DateTime64
format
— 带 Joda 风格替换字段的格式字符串。String
timezone
— 可选。 格式化时间的时区名称。String
返回值
根据确定的格式返回时间和日期值。 String
示例
使用 Joda 语法格式化日期时间
fromDaysSinceYearZero
引入于:v23.11
对于自 公元0000年1月1日 以来经过的天数,返回 ISO 8601 定义的前瞻性格里高尔日历 中相应的日期。
该计算与 MySQL 的 FROM_DAYS()
函数相同。如果在 Date 类型的范围内不能表示,结果是未定义的。
语法
参数
days
— 自公元零年起经过的天数。UInt32
返回值
返回自公元零年起经过的天数对应的日期。 Date
示例
将自公元零年起的天数转换为日期
fromDaysSinceYearZero32
引入于:v23.11
对于自 公元0000年1月1日 以来经过的天数,返回 ISO 8601 定义的前瞻性格里高尔日历 中相应的日期。
该计算与 MySQL 的 FROM_DAYS()
函数相同。如果在 Date32
类型的范围内不能表示,结果是未定义的。
语法
参数
days
— 自公元零年起经过的天数。UInt32
返回值
返回自公元零年起经过的天数对应的日期。 Date32
示例
将自公元零年起的天数转换为日期
fromModifiedJulianDay
引入于:v21.1
将修订过的儒略日数字转换为文本形式的前瞻性格里高尔日历 日期 YYYY-MM-DD
。此函数支持的天数范围为 -678941
到 2973483
(分别代表 0000-01-01 和 9999-12-31)。如果天数超出支持范围,将引发异常。
语法
参数
day
— 修订的儒略日数字。(U)Int*
返回值
返回文本形式的日期。 String
示例
将修订的儒略日转换为日期
fromModifiedJulianDayOrNull
引入于:v21.1
类似于 fromModifiedJulianDay()
,但不引发异常,而是返回 NULL
。
语法
参数
day
— 修订的儒略日数字。(U)Int*
返回值
对于有效的 day
参数,返回文本形式的日期;否则返回 null
。 Nullable(String)
示例
在处理 null 时将修订的儒略日转换为日期
fromUTCTimestamp
引入于:v22.1
将来自 UTC 时区的日期或带时间的值转换为指定时区的日期或带时间的值。此函数主要是为了与 Apache Spark 等框架的兼容性而包含。
语法
参数
datetime
— 常量值或表达式中的日期或带时间的日期。DateTime
或DateTime64
time_zone
— 表示时区的常量字符串类型值或表达式。String
返回值
返回指定时区的 DateTime/DateTime64。 DateTime
或 DateTime64
示例
将 UTC 时区转换为指定时区
fromUnixTimestamp
引入于:v20.8
此函数将 Unix 时间戳转换为日历日期和一天中的时间。
它可以以两种方式调用:
- 当给定一个类型为
Integer
的单一参数时,它返回类型为DateTime
的值,即行为类似于toDateTime
。 - 当给定两个或三个参数时,第一个参数是类型为
Integer
、Date
、Date32
、DateTime
或DateTime64
的值,第二个参数是常量格式字符串,第三个参数是可选的常量时区字符串,该函数返回类型为String
的值,即其行为类似于formatDateTime
。 在这种情况下,使用 MySQL 的日期时间格式风格。
语法
参数
timestamp
— Unix 时间戳或日期/带时间的值。(U)Int*
或Date
或Date32
或DateTime
或DateTime64
format
— 可选。 输出格式的常量格式字符串。String
timezone
— 可选。 常量时区字符串。String
返回值
当以一个参数调用时返回时间戳的 DateTime
,或以两个或三个参数调用时返回字符串。 DateTime
或 String
示例
将 Unix 时间戳转换为 DateTime
带格式的 Unix 时间戳转换
fromUnixTimestampInJodaSyntax
引入于:v23.1
此函数将 Unix 时间戳转换为日历日期和一天中的时间。
它可以以两种方式调用:
当给定一个类型为 Integer
的单一参数时,它返回类型为 DateTime
的值,即行为类似于 toDateTime
。
当给定两个或三个参数时,第一个参数是类型为 Integer
、Date
、Date32
、DateTime
或 DateTime64
的值,第二个参数是常量格式字符串,第三个参数是可选的常量时区字符串,该函数返回类型为 String
的值,即其行为类似于 formatDateTimeInJodaSyntax
。在这种情况下,使用 Joda 日期时间格式风格。
语法
参数
timestamp
— Unix 时间戳或日期/时间值。(U)Int*
或Date
或Date32
或DateTime
或DateTime64
format
— 可选。 使用 Joda 语法的输出格式常量字符串。String
timezone
— 可选。 常量时区字符串。String
返回值
在以一个参数调用时返回带时间的日期,或在以两个或三个参数调用时返回字符串。 DateTime
或 String
示例
以 Joda 格式转换 Unix 时间戳
makeDate
引入于:v22.6
从以下任一项创建 Date
:
- 一年、一个月和一天
- 一年和一年中的第几天
语法
参数
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
示例
从年份、月份和日期创建日期
从年份和一年中的第几天创建日期
makeDate32
引入于:v22.6
从以下任一项创建 Date32
:
- 一年、一个月和一天
- 一年和一年中的第几天
语法
参数
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
从年份和一年中的第几天创建 Date32
makeDateTime
引入于:v22.6
从年份、月份、日期、小时、分钟和秒创建 DateTime
,可选的时区。
语法
参数
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
示例
从年份、月份、日期、小时、分钟、秒创建 DateTime
makeDateTime64
引入于:v22.6
从年份、月份、日期、小时、分钟、秒创建 DateTime64
,可选的小数部分、精度和时区。
语法
参数
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
示例
从年份、月份、日期、小时、分钟、秒创建 DateTime64
monthName
引入于:v22.1
从日期或带时间的日期中返回月份名称作为字符串。
语法
参数
datetime
— 日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回月份的名称。 String
示例
从日期中获取月份名称
now
引入于:v1.1
在查询分析的瞬间返回当前日期和时间。此函数为常量表达式。
语法
参数
timezone
— 可选。 返回值的时区名称。String
返回值
返回当前日期和时间。 DateTime
示例
没有时区的查询
带指定时区的查询
now64
引入于:v20.1
在查询分析的瞬间返回当前日期和时间,具有亚秒级精度。此函数为常量表达式。
语法
参数
scale
— 可选。 Tick 大小(精度): 10^-precision 秒。有效范围:[0 : 9]。通常使用 - 3(默认)(毫秒),6(微秒),9(纳秒)。UInt8
timezone
— 可选。 返回值的时区名称。String
返回值
返回带有亚秒级精度的当前日期和时间。 DateTime64
示例
使用默认和自定义精度的查询
nowInBlock
引入于:v22.8
在处理每个数据块的瞬间返回当前日期和时间。与函数 now
不同,它不是常量表达式,因此对于长时间运行的查询,不同数据块的返回值将不同。
在长时间运行的 INSERT SELECT
查询中使用此函数生成当前时间是有意义的。
语法
参数
timezone
— 可选。 返回值的时区名称。String
返回值
在处理每个数据块的瞬间返回当前日期和时间。 DateTime
示例
与 now() 函数的区别
nowInBlock64
引入于:v25.8
在处理每个数据块的瞬间返回当前日期和时间,单位为毫秒。与函数 now64 不同,它不是常量表达式,因此对于长时间运行的查询,不同数据块的返回值将不同。
在长时间运行的 INSERT SELECT
查询中使用此函数生成当前时间是有意义的。
语法
参数
scale
— 可选。 Tick 大小(精度): 10^-precision 秒。有效范围:[0 : 9]。通常使用 - 3(默认)(毫秒),6(微秒),9(纳秒)。UInt8
timezone
— 可选。 返回值的时区名称。String
返回值
在处理每个数据块的瞬间返回带有亚秒级精度的当前日期和时间。 DateTime64
示例
与 now64() 函数的区别
serverTimezone
引入于:v23.6
返回服务器的时区,即 timezone
设置的值。
如果在分布式表的上下文中执行此函数,则会生成与每个分片相关的正常列的值。否则则生成一个常量值。
语法
参数
- 无 返回值
返回服务器时区,类型为 String
示例
使用示例
subDate
引入于:v23.9
从提供的日期、带时间的日期或字符串编码的日期或带时间中减去时间间隔。 如果减法结果超出数据类型的边界,结果是未定义的。
语法
参数
datetime
— 要减去interval
的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
interval
— 要减去的间隔。Interval
返回值
返回通过从 datetime
中减去 interval
获得的日期或带时间的日期。 Date
或 Date32
或 DateTime
或 DateTime64
示例
从日期中减去间隔
subtractDays
引入于:v1.1
从日期、带时间的日期或字符串编码的日期或带时间中减去指定的天数。
语法
参数
datetime
— 要从中减去指定天数的日期或带时间的日期。Date
或Date32
或DateTime
或 [DateTime64
](/sql-reference/data-types/datetime64)或String
num
— 要减去的天数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
天 Date
或 Date32
或 DateTime
或 DateTime64
示例
从不同日期类型减去天数
使用替代的 INTERVAL 语法
subtractHours
引入于:v1.1
从日期、带时间的日期或字符串编码的日期或带时间中减去指定的小时数。
语法
参数
datetime
— 要从中减去指定小时的日期或带时间的日期。Date
或 [Date32
](/sql-reference/data-types/date32)或DateTime
或 [DateTime64
](/sql-reference/data-types/datetime64)或String
num
— 要减去的小时数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
小时 DateTime
或 DateTime64(3)
示例
从不同日期类型减去小时数
使用替代的 INTERVAL 语法
subtractInterval
引入于:v22.11
将一个间隔的负值添加到另一个间隔或间隔元组中。
注意:相同类型的间隔将合并为一个单一的间隔。例如,如果传入 toIntervalDay(2)
和 toIntervalDay(1)
,则结果将是 (1)
而不是 (2,1)
。
语法
参数
interval_1
— 第一个间隔或间隔元组。Interval
或Tuple(Interval)
interval_2
— 第二个间隔,将被取负。Interval
返回值
返回间隔元组 Tuple(T)
示例
减去间隔
subtractMicroseconds
引入于:v22.6
从带时间的日期或字符串编码的带时间的日期中减去指定的微秒数。
语法
参数
datetime
— 带时间的日期,减去指定的微秒数。DateTime
或 [DateTime64
](/sql-reference/data-types/datetime64)或String
num
— 要减去的微秒数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
微秒 DateTime64
示例
从不同日期时间类型减去微秒
使用替代的 INTERVAL 语法
subtractMilliseconds
引入于:v22.6
从带有时间的日期或字符串编码的带有时间的日期中减去指定数量的毫秒。
语法
参数
datetime
— 要减去指定毫秒数的带有时间的日期。DateTime
或DateTime64
或String
num
— 要减去的毫秒数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
毫秒后的值 DateTime64
示例
从不同日期时间类型中减去毫秒
使用替代的 INTERVAL 语法
subtractMinutes
引入于:v1.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的分钟。
语法
参数
datetime
— 要减去指定分钟数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的分钟数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
分钟后的值 DateTime
或 DateTime64(3)
示例
从不同日期类型中减去分钟
使用替代的 INTERVAL 语法
subtractMonths
引入于:v1.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的月份。
语法
参数
datetime
— 要减去指定月份数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的月份数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
个月后的值 Date
或 Date32
或 DateTime
或 DateTime64
示例
从不同日期类型中减去月份
使用替代的 INTERVAL 语法
subtractNanoseconds
引入于:v20.1
从带有时间的日期或字符串编码的带有时间的日期中减去指定数量的纳秒。
语法
参数
datetime
— 要减去指定纳秒数的带有时间的日期。DateTime
或DateTime64
或String
num
— 要减去的纳秒数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
纳秒后的值 DateTime64
示例
从不同日期时间类型中减去纳秒
使用替代的 INTERVAL 语法
subtractQuarters
引入于:v20.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的季度。
语法
参数
datetime
— 要减去指定季度数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的季度数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
季度后的值 Date
或 Date32
或 DateTime
或 DateTime64
示例
从不同日期类型中减去季度
使用替代的 INTERVAL 语法
subtractSeconds
引入于:v1.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的秒。
语法
参数
datetime
— 要减去指定秒数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的秒数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
秒后的值 DateTime
或 DateTime64(3)
示例
从不同日期类型中减去秒
使用替代的 INTERVAL 语法
subtractTupleOfIntervals
引入于:v22.11
连续地从日期或带有时间的日期中减去一组间隔。
语法
参数
datetime
— 要减去间隔的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
intervals
— 要从datetime
中减去的间隔元组。Tuple(Interval)
返回值
返回减去 intervals
后的日期 Date
或 Date32
或 DateTime
或 DateTime64
示例
从日期中减去间隔元组
subtractWeeks
引入于:v1.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的周。
语法
参数
datetime
— 要减去指定周数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的周数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
周后的值 Date
或 Date32
或 DateTime
或 DateTime64
示例
从不同日期类型中减去周
使用替代的 INTERVAL 语法
subtractYears
引入于:v1.1
从日期、带有时间的日期或字符串编码的日期或带有时间的日期中减去指定数量的年。
语法
参数
datetime
— 要减去指定年数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
或String
num
— 要减去的年数。(U)Int*
或Float*
返回值
返回 datetime
减去 num
年后的值 Date
或 Date32
或 DateTime
或 DateTime64
示例
从不同日期类型中减去年
使用替代的 INTERVAL 语法
timeDiff
引入于:v23.4
返回 startdate
和 enddate
之间跨越的指定 unit
边界的数量。差异通过相对单位计算。例如,2021-12-29 和 2022-01-01 之间的差异为3天,单位为天(参见 [toRelativeDayNum
](#toRelativeDayNum)),单位为月为1个月(参见 [toRelativeMonthNum
](#toRelativeMonthNum)),单位为年为1年(参见 [toRelativeYearNum
](#toRelativeYearNum))。
如果指定了单位 week
,则 timeDiff
假定周从星期一开始。请注意,此行为与 toWeek()
函数的行为不同,后者默认周从星期天开始。
关于 [timeDiff
](#timeDiff)的替代方案,请参见函数 [age
](#age)。
语法
参数
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
之间的差异。Int64
示例
计算以小时为单位的日期差异
计算不同单位的日期差异
timeSlot
引入于:v1.1
将时间四舍五入到半小时长度间隔的开始。
虽然这个函数可以接收扩展类型 Date32
和 DateTime64
的值作为参数,但将其传递一个超出正常范围(1970 年至 2149 年的年份对于 Date
/ 2106 年对于 DateTime
)的时间将产生错误结果。
语法
参数
time
— 要四舍五入到半小时长度间隔开始的时间。DateTime
或Date32
或DateTime64
time_zone
— 可选。一个字符串类型常量或表示时区的表达式。String
返回值
返回四舍五入到半小时长度间隔开始的时间。DateTime
示例
将时间四舍五入到半小时间隔
timeSlots
引入于:v1.1
对于从 StartTime
开始并持续 Duration
秒的时间间隔,返回一组时间点,该点由从此间隔中向下取整到 Size
秒生成。Size
是一个可选参数,默认为 1800(30 分钟)。
这在例如搜索对应会话中的页面视图时是必要的。
对于 DateTime64
,返回值的比例可能与 StartTime
的比例不同。会取所有给定参数中最高的比例。
语法
参数
StartTime
— 时间间隔的开始时间。DateTime
或DateTime64
Duration
— 以秒为单位的时间间隔的持续时间。UInt32
或DateTime64
Size
— 可选。时间段大小,单位为秒。默认值为 1800(30 分钟)。UInt32
或DateTime64
返回值
返回一个 DateTime/DateTime64 数组(返回类型与 StartTime
的类型匹配)。对于 DateTime64,返回值的比例可能与 StartTime
的比例不同 - 取所有给定参数中最高的比例。Array(DateTime)
或 Array(DateTime64)
示例
生成时间段数组
timestamp
引入于:v23.9
将第一个参数 expr
转换为 DateTime64(6)
。如果提供了第二个参数 expr_time
,则将指定的时间添加到转换后的值中。
语法
参数
返回值
返回转换后的 expr
值,或添加时间后的 expr
DateTime64(6)
示例
将日期字符串转换为 DateTime64(6)
将时间添加到日期字符串
timezone
引入于:v21.4
返回当前会话的时区名称或将时区偏移或名称转换为规范时区名称。
语法
参数
- 无。
返回值
返回规格化的时区名称,作为 String
示例
用法示例
timezoneOf
引入于:v21.4
返回 DateTime
或 DateTime64
值的时区名称。
语法
参数
datetime
— 类型值。DateTime
或DateTime64
timezone
— 可选。要转换datetime
值时区的时区名称。String
返回值
返回 datetime
的时区名称 String
示例
用法示例
timezoneOffset
引入于:v21.6
返回与 UTC 的时区偏移(以秒为单位)。该函数考虑了在指定日期和时间的夏令时和历史时区变化。
语法
参数
datetime
— 要获取时区偏移的DateTime
值。DateTime
或DateTime64
返回值
返回与 UTC 的偏移,单位为秒 Int32
示例
用法示例
toDayOfMonth
引入于:v1.1
返回 Date
或 DateTime
的月份天数(1-31)。
语法
参数
datetime
— 要获取月份天数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期/时间的月份日期 UInt8
示例
用法示例
toDayOfWeek
引入于:v1.1
返回 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 |
语法
参数
datetime
— 要获取星期几的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
mode
— 可选。指定周模式的整数(0-3)。默认值为 0。如果省略,默认为 0。UInt8
timezone
— 可选。用于转换的时区。String
返回值
返回给定 Date
或 DateTime
的星期几 UInt8
示例
用法示例
toDayOfYear
引入于:v18.4
返回 Date
或 DateTime
值在一年中的日期号(1-366)。
语法
参数
datetime
— 要获取年份天数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或 DateTime 的年份天数 UInt16
示例
用法示例
toDaysSinceYearZero
引入于:v23.9
对于给定日期,返回自 公元 0000 年 1 月 1 日 以来的天数,使用 ISO 8601 定义的历法 计算。
计算方法与 MySQL 的 TO_DAYS
函数相同。
语法
参数
date
— 要计算自公元零年起天数的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
time_zone
— 时区。String
返回值
返回自日期 0000-01-01
以来的天数。UInt32
示例
计算自公元零年起的天数
toHour
引入于:v1.1
返回 DateTime
或 DateTime64
值的小时部分(0-23)。
语法
参数
datetime
— 要获取小时的带有时间的日期。DateTime
或DateTime64
返回值
返回 datetime
的小时(0-23)。UInt8
示例
用法示例
toISOYear
引入于:v18.4
将日期或带有时间的日期转换为 ISO 年号。
语法
参数
datetime
— 带有日期或时间的值。Date
或Date32
或DateTime
或DateTime64
返回值
返回输入值转换为ISO年号。UInt16
示例
从日期值获取ISO年
toLastDayOfMonth
引入于:v1.1
将日期或带有时间的日期四舍五入到该月的最后一天。
返回类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要四舍五入到该月最后一天的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或带有时间的日期的该月最后一天的日期。Date
示例
四舍五入到该月的最后一天
toLastDayOfWeek
引入于:v23.5
将日期或带有时间的日期四舍五入到最近的星期六或星期天。
返回类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 要转换的日期或带有时间的日期。Date
或DateTime
或Date32
或DateTime64
mode
— 确定一周的第一天,如toWeek()
函数中所述。默认值为0
。UInt8
timezone
— 可选。用于转换的时区。如果未指定,则使用服务器的时区。String
返回值
返回给定日期之后最近的星期六或星期天的日期,具体取决于模式 Date
或 Date32
或 DateTime
或 DateTime64
示例
四舍五入到最近的星期六或星期天
toMillisecond
引入于:v24.2
返回 DateTime
或 DateTime64
值的毫秒部分(0-999)。
语法
参数
datetime
— 要获取毫秒的带有时间的日期。DateTime
或DateTime64
返回值
返回 datetime
中的毫秒(0 - 999)。UInt16
示例
用法示例
toMinute
引入于:v1.1
返回 Date
或 DateTime
值的分钟部分(0-59)。
语法
参数
datetime
— 要获取分钟的带有时间的日期。DateTime
或DateTime64
返回值
返回 datetime
的分钟数(0 - 59)。UInt8
示例
用法示例
toModifiedJulianDay
引入于:v21.1
将 Proleptic Gregorian calendar 形式的日期 YYYY-MM-DD
转换为 Modified Julian Day 编号(Int32
)。此函数支持的日期范围从 0000-01-01
到 9999-12-31
。如果参数无法解析为日期或日期无效,则会引发异常。
语法
参数
date
— 字符串形式的日期。String
或FixedString
返回值
返回修改后的朱利安日编号。Int32
示例
将日期转换为修改后的朱利安日
toModifiedJulianDayOrNull
引入于:v21.1
类似于 toModifiedJulianDay()
,但不再引发异常,而是返回 NULL
。
语法
参数
date
— 字符串形式的日期。String
或FixedString
返回值
对于有效的 date
,返回修改后的朱利安日编号,否则返回 null
。Nullable(Int32)
示例
将日期转换为修改后的朱利安日,并处理 null
toMonday
引入于:v1.1
将日期或带有时间的日期向下取整到同一周的星期一。返回该日期。
返回类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要向下取整到本周星期一的日期或带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或带有时间的日期的同一周的星期一的日期。Date
示例
向下取整到本周的星期一
toMonth
引入于:v1.1
返回 Date
或 DateTime
值的月份部分(1-12)。
语法
参数
datetime
— 要获取月份的带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期/时间的月份 UInt8
示例
用法示例
toMonthNumSinceEpoch
引入于:v25.3
返回自 1970 年以来经历的月份数。
语法
参数
date
— 日期或带有时间的日期。Date
或DateTime
或DateTime64
返回值
正整数
示例
示例
toQuarter
引入于:v1.1
返回给定 Date
或 DateTime
值的季度(1-4)。
语法
参数
datetime
— 要获取季度的带有时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期/时间的季度 UInt8
示例
用法示例
toRelativeDayNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的天数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的天数差,例如 toRelativeDayNum(dt1) - toRelativeDayNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的天数。 UInt32
示例
获取相对日期数
toRelativeHourNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的小时数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的小时差,例如 toRelativeHourNum(dt1) - toRelativeHourNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的小时数。 UInt32
示例
获取相对小时数
toRelativeMinuteNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的分钟数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的分钟差,例如 toRelativeMinuteNum(dt1) - toRelativeMinuteNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的分钟数。 UInt32
示例
获取相对分钟数
toRelativeMonthNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的月份数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的月份差,例如 toRelativeMonthNum(dt1) - toRelativeMonthNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的月份数。 UInt32
示例
获取相对月份数
toRelativeQuarterNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的季度数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的季度差,例如 toRelativeQuarterNum(dt1) - toRelativeQuarterNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的季度数。 UInt32
示例
获取相对季度数
toRelativeSecondNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的秒数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的秒数差,例如 toRelativeSecondNum(dt1) - toRelativeSecondNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的秒数。 UInt32
示例
获取相对秒数
toRelativeWeekNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的周数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的周数差,例如 toRelativeWeekNum(dt1) - toRelativeWeekNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的周数。 UInt32
示例
获取相对周数
toRelativeYearNum
引入于:v1.1
将日期或带时间的日期转换为自过去某个固定点以来经过的年数。
确切的时间点是实现细节,因此此函数不打算单独使用。
该函数的主要目的在于计算两个日期或带时间的日期之间的年数差,例如 toRelativeYearNum(dt1) - toRelativeYearNum(dt2)
。
语法
参数
date
— 日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
返回自过去某个固定参考点以来的年数。 UInt16
示例
获取相对年份数
toSecond
引入于:v1.1
返回 DateTime
或 DateTime64
值的秒部分(0-59)。
语法
参数
datetime
— 从中获取秒的带时间日期。DateTime
或DateTime64
返回值
返回 datetime
中的秒(0 - 59)。 UInt8
示例
用法示例
toStartOfDay
引入于:v1.1
将带时间的日期向下舍入到一天的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
返回值
返回向下舍入到一天开始的带时间的日期。 Date
或 DateTime
或 Date32
或 DateTime64
示例
舍入到一天的开始
toStartOfFifteenMinutes
引入于:v1.1
将带时间的日期向下舍入到十五分钟间隔的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 要舍入的日期或带时间的日期。DateTime
或DateTime64
返回值
返回向下舍入到最近的十五分钟间隔的带时间的日期 DateTime
或 DateTime64
示例
示例
toStartOfFiveMinutes
引入于:v22.6
将带时间的日期向下舍入到最近的五分钟间隔的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 带时间的日期。DateTime
或DateTime64
返回值
返回向下舍入到最近的五分钟间隔的带时间的日期 DateTime
或 DateTime64
示例
示例
toStartOfHour
引入于:v1.1
将带时间的日期向下舍入到小时的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 带时间的日期。DateTime
或DateTime64
返回值
返回向下舍入到小时开始的带时间的日期。 DateTime
或 DateTime64
示例
舍入到小时的开始
toStartOfISOYear
引入于:v1.1
将日期或带时间的日期向下舍入到ISO年第一天,ISO年可能与常规年份不同。请参见 ISO week date。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要向下舍入到ISO年第一天的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或带时间的日期的ISO年第一天。 Date
示例
向下舍入到ISO年第一天
toStartOfInterval
引入于:v20.1
此函数通过 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 Q1 |
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之间的小时值是有用的。 |
如果指定了单位 WEEK
,toStartOfInterval
假定周从星期一开始。请注意,该行为不同于默认从星期日开始的 toStartOfWeek
函数。
第二个重载模拟了 TimescaleDB 的 time_bucket()
函数,以及 PostgreSQL 的 date_bin()
函数。
语法
参数
value
— 要向下舍入的日期或带时间的日期。Date
或DateTime
或DateTime64
x
— 间隔长度数。 -unit
— 间隔单位:YEAR, QUARTER, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND, MILLISECOND, MICROSECOND, NANOSECOND。 -time_zone
— 可选。作为字符串的时区名称。 -origin
— 可选。用于计算的起点(仅适用于第二个重载)。
返回值
返回包含输入值的间隔开始。 DateTime
示例
基本间隔舍入
使用起点
toStartOfMicrosecond
引入于:v22.6
将带时间的日期向下舍入到微秒的开始。
语法
参数
datetime
— 日期和时间。DateTime64
timezone
— 可选。返回值的时区。如果未指定,函数将使用value
参数的时区。String
返回值
输入值的微秒部分 DateTime64
示例
无时区的查询
带时区的查询
toStartOfMillisecond
引入于:v22.6
将带时间的日期向下舍入到毫秒的开始。
语法
参数
datetime
— 日期和时间。DateTime64
timezone
— 可选。返回值的时区。如果未指定,函数将使用value
参数的时区。String
返回值
输入值的毫秒部分。 DateTime64
示例
无时区的查询
带时区的查询
toStartOfMinute
引入于:v1.1
将带时间的日期向下舍入到分钟的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 要舍入的带时间日期。DateTime
或DateTime64
返回值
返回向下舍入到分钟开始的带时间日期。 DateTime
或 DateTime64
示例
舍入到分钟的开始
toStartOfMonth
引入于:v1.1
将日期或带时间的日期向下舍入到本月的第一天。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要向下舍入到本月第一天的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或带时间的日期的本月第一天。 Date
示例
向下舍入到本月的第一天
toStartOfNanosecond
引入于:v22.6
将带时间的日期向下舍入到纳秒的开始。
语法
参数
datetime
— 日期和时间。DateTime64
timezone
— 可选。返回值的时区。如果未指定,函数将使用value
参数的时区。String
返回值
输入值的纳秒部分。 DateTime64
示例
无时区的查询
带时区的查询
toStartOfQuarter
引入于:v1.1
将日期或带时间的日期向下舍入到季度的第一天。季度的第一天是每年的1月1日、4月1日、7月1日或10月1日。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要向下舍入到季度第一天的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或带时间的日期的季度第一天。 Date
示例
向下舍入到季度的第一天
toStartOfSecond
引入于:v20.5
将带时间的日期向下舍入到秒的开始。
语法
参数
datetime
— 日期和时间以截断亚秒。DateTime64
timezone
— 可选。返回值的时区。如果未指定,函数将使用value
参数的时区。String
返回值
返回输入值,而没有亚秒部分。 DateTime64
示例
无时区的查询
带时区的查询
toStartOfTenMinutes
引入于:v20.1
将带时间的日期向下舍入到最近的十分钟间隔的开始。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 带时间的日期。DateTime
或DateTime64
返回值
返回向下舍入到最近的十分钟间隔的带时间的日期 DateTime
或 DateTime64
示例
示例
toStartOfWeek
引入于:v20.1
将日期或带时间的日期舍入到最近的星期日或星期一。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
datetime
— 要转换的日期或带时间的日期。Date
或DateTime
或Date32
或DateTime64
mode
— 确定一周的第一天,如toWeek()
函数中所述。 默认值为0
。UInt8
timezone
— 用于转换的时区。如果未指定,将使用服务器的时区。String
返回值
返回在给定日期之前或最近的星期日或星期一的日期,具体取决于模式 Date
或 Date32
或 DateTime
或 DateTime64
示例
舍入到最近的星期日或星期一
toStartOfYear
引入于:v1.1
将日期或带时间的日期向下舍入到这一年的第一天。返回的日期为 Date
对象。
返回值类型可以通过设置 enable_extended_results_for_datetime_functions
来配置。
语法
参数
value
— 要舍入的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期/时间的这一年的第一天 Date
示例
向下舍入到这一年的第一天
toTimeWithFixedDate
引入于:v1.1
提取日期或带时间的日期的时间部分。
返回的结果是相对于固定时间点的偏移量,目前为 1970-01-02
,
但确切的时间点是实现细节,将来可能会改变。
因此,toTime
不应单独使用。
该函数的主要目的是计算两个日期或带时间的日期之间的时间差,例如 toTime(dt1) - toTime(dt2)
。
语法
参数
date
— 要转换为时间的日期。Date
或DateTime
或DateTime64
timezone
— 可选。返回值的时区。String
返回值
以偏移量的形式返回日期或带时间的日期的时间部分(选定为1970-01-02) DateTime
示例
计算两个日期之间的时间差
toTimezone
引入于:v1.1
将 DateTime
或 DateTime64
转换为指定的时区。
数据的内部值(unix秒数)不会改变。
只有值的时区属性和字符串表示发生变化。
语法
参数
date
— 要转换的值。DateTime
或DateTime64
timezone
— 目标时区名称。String
返回值
返回与输入相同的时间戳,但时区为指定的时区 DateTime
或 DateTime64
示例
用法示例
toUTCTimestamp
引入于:v23.8
将日期或带时间的值从一个时区转换为 UTC 时区时间戳。此函数主要是为了与 Apache Spark 和类似框架的兼容性。
语法
参数
datetime
— 日期或带时间类型的常量值或表达式。DateTime
或DateTime64
time_zone
— 字符串类型常量值或表示时区的表达式。String
返回值
返回 UTC 时区中的日期或带时间的日期。 DateTime
或 DateTime64
示例
将时区转换为 UTC
toUnixTimestamp
引入于:v1.1
将 String
、Date
或 DateTime
转换为 Unix 时间戳(自 1970-01-01 00:00:00 UTC
起的秒数),返回类型为 UInt32
。
语法
参数
date
— 要转换的值。Date
或Date32
或DateTime
或DateTime64
或String
timezone
— 可选。用于转换的时区。如果未指定,将使用服务器的时区。String
返回值
返回 Unix 时间戳。 UInt32
示例
用法示例
toWeek
引入于:v20.1
该函数返回日期或日期时间的周数。toWeek()
的两个参数形式使您能够指定一周的起始日
为星期日或星期一,以及返回值是否应该在 0
到 53
的范围内,还是在 1
到 53
的范围内。
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日,则该周将是下一年的第1周。
第一个参数也可以指定为 String
格式,该格式受到 parseDateTime64BestEffort()
支持。字符串参数的支持仅出于与某些第三方工具的兼容性的目的。由于字符串参数的解析通常很慢,因此建议不要使用它。
语法
参数
datetime
— 要获取周数的日期或带时间的日期。Date
或DateTime
mode
— 可选。模式0
到9
决定一周的第一天和周数的范围。默认值0
。 -time_zone
— 可选。时区。String
返回值
根据指定模式返回周数。 UInt32
示例
使用不同模式获取周数
toYYYYMM
引入于:v1.1
将日期或带时间的日期转换为一个包含年份和月份的 UInt32
数字(YYYY * 100 + MM)。接受第二个可选的时区参数。如果提供,时区必须是一个字符串常量。
该函数是函数 YYYYMMDDToDate()
的反函数。
语法
参数
datetime
— 要转换的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
timezone
— 可选。用于转换的时区。如果提供,时区必须是一个字符串常量。String
返回值
返回一个包含年份和月份的 UInt32 数字(YYYY * 100 + MM)。 UInt32
示例
将当前日期转换为 YYYYMM 格式
toYYYYMMDD
引入于:v1.1
将日期或带时间的日期转换为一个包含年份、月份和日期的 UInt32
数字(YYYY * 10000 + MM * 100 + DD)。接受第二个可选的时区参数。如果提供,时区必须是一个字符串常量。
语法
参数
datetime
— 要转换的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
timezone
— 可选。用于转换的时区。如果提供,时区必须是一个字符串常量。String
返回值
返回一个 UInt32
数字,包含年份、月份和日期(YYYY * 10000 + MM * 100 + DD)。 UInt32
示例
将当前日期转换为 YYYYMMDD 格式
toYYYYMMDDhhmmss
引入于:v1.1
将日期或带时间的日期转换为一个包含年份、月份、日期、小时、分钟和秒的 UInt64
数字(YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss)。接受第二个可选的时区参数。如果提供,时区必须是一个字符串常量。
语法
参数
datetime
— 要转换的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
timezone
— 可选。用于转换的时区。如果提供,时区必须是一个字符串常量。String
返回值
返回一个 UInt64
数字,包含年份、月份、日期、小时、分钟和秒(YYYY * 10000000000 + MM * 100000000 + DD * 1000000 + hh * 10000 + mm * 100 + ss)。 UInt64
示例
将当前日期和时间转换为 YYYYMMDDhhmmss 格式
toYear
引入于:v1.1
返回 Date
或 DateTime
值的年份组成部分(公元年)。
语法
参数
datetime
— 要提取年份的日期或带时间的日期。Date
或Date32
或DateTime
或DateTime64
返回值
返回给定日期或日期时间的年份 UInt16
示例
用法示例
toYearNumSinceEpoch
引入于:v25.3
返回从1970年起经过的年份数。
语法
参数
date
— 要转换的日期或带时间的日期。Date
或DateTime
或DateTime64
返回值
正整数
示例
示例
toYearWeek
引入于:v20.1
返回日期的年份和周数。结果中的年份可能与日期参数中的年份不同,适用于年初和年末的第一周和最后一周。
mode
参数的作用与toWeek()
的 mode
参数相同。
警告:toYearWeek()
返回的周数可能与 toWeek()
返回的不同。toWeek()
总是返回给定年份上下文中的周数,如果 toWeek()
返回 0
,toYearWeek()
返回对应于前一年最后一周的值。请参见下面示例中的 prev_yearWeek
。
第一个参数也可以作为 String
以 parseDateTime64BestEffort()
支持的格式指定。字符串参数的支持仅因兼容某些第三方工具的 MySQL 而存在。由于字符串参数支持未来可能依赖于新的 MySQL 兼容设置,并且字符串解析通常较慢,因此不推荐使用。
语法
参数
datetime
— 要获取年份和周数的日期或带时间的日期。Date
或DateTime
mode
— 可选。模式0
到9
决定每周的第一天和周数范围。默认0
。 -timezone
— 可选。时区。String
返回值
以组合整数值返回年份和周数。 UInt32
示例
获取具有不同模式的年-周组合
today
引入于:v1.1
返回查询分析时的当前日期。与 toDate(now())
相同。
语法
参数
- 无。 返回值
返回当前日期 Date
示例
用法示例
yesterday
引入于:v1.1
接受零个参数,并返回查询分析时的昨天日期。
语法
参数
- 无。 返回值
返回昨天的日期。 Date
示例
获取昨天的日期