时间日期函数

更新时间：2026-10-23

本页是 SQL 查询中可用的时间日期标量函数参考，涵盖当前时间获取、时间分桶、日期构造、timestamp 格式转换与解析等操作。时序场景专用的扩展函数（date_bin_gapfill、date_bin_wallclock、tz、覆盖版 to_timestamp 等）见本页末尾的时序扩展函数章节。

函数	别名	说明
`current_date`	`today`	返回当前 UTC 日期
`current_time`	—	返回当前 UTC 时间
`date_bin`	—	按指定间隔分桶，返回 timestamp 所在区间的起点
`date_part`	`datepart`	以整数形式返回日期的指定部分
`date_trunc`	`datetrunc`	将 timestamp 截断到指定精度
`from_unixtime`	—	将整数转换为 RFC3339 timestamp
`make_date`	—	由年 / 月 / 日构造日期
`make_time`	—	由时 / 分 / 秒构造时间
`now`	`current_timestamp`	返回当前时刻的 UTC timestamp（不带时区）
`to_char`	`date_format`	按 Chrono 格式输出日期时间的字符串表示
`to_date`	—	将值转换为日期
`to_local_time`	—	将带时区的 timestamp 转换为不带时区的 timestamp
`to_timestamp_micros`	—	将值转换为微秒精度 timestamp
`to_timestamp_millis`	—	将值转换为毫秒精度 timestamp
`to_timestamp_nanos`	—	将值转换为纳秒精度 timestamp
`to_timestamp_seconds`	—	将值转换为秒精度 timestamp
`to_time`	—	将值转换为一天之内的时间
`to_unixtime`	—	将值转换为自 unix epoch 起的秒数

`current_date`

返回当前 UTC 日期。

current_date() 的返回值在查询开始时即确定，无论该函数在查询计划的哪个阶段执行，返回的都是同一个日期。

语法：current_date()

别名：today

示例：

SQL

1> SELECT current_date();
2+----------------+
3| current_date() |
4+----------------+
5| 2026-07-21     |
6+----------------+

结果为查询开始时刻的值，随执行时间变化。

`current_time`

返回当前 UTC 时间。

current_time() 的返回值在查询开始时即确定，无论该函数在查询计划的哪个阶段执行，返回的都是同一个时间。

语法：current_time()

示例：

SQL

1> SELECT current_time();
2+--------------------+
3| current_time()     |
4+--------------------+
5| 09:28:52.326720808 |
6+--------------------+

结果为查询开始时刻的值，随执行时间变化。

`date_bin`

计算时间区间，并返回距指定 timestamp 最近的区间起点。使用 date_bin 可以对时序数据降采样：把行按时间分组到「桶」（bin）或「窗口」（window）中，再对每个窗口应用聚合函数或选择器函数。

例如，把数据按 15 分钟为间隔分桶时，输入 timestamp 2023-01-01T18:18:18Z 会被归到它所在的 15 分钟桶的起始时间：2023-01-01T18:15:00Z。

语法：date_bin(interval, expression, origin-timestamp)

参数：

interval：分桶间隔。
expression：要处理的时间表达式，可以是常量、列或函数。
origin-timestamp：可选。用于确定桶边界的起始点。未指定时默认为 1970-01-01T00:00:00Z（UTC 下的 UNIX epoch）。

支持以下 interval：

nanoseconds
microseconds
milliseconds
seconds
minutes
hours
days
weeks
months
years
century

示例：

SQL

1-- 将 timestamp 按 1 天间隔分桶
2> SELECT date_bin(interval '1 day', time) as bin
3FROM VALUES ('2023-01-01T18:18:18Z'), ('2023-01-03T19:00:03Z')  t(time);
4+---------------------+
5| bin                 |
6+---------------------+
7| 2023-01-01T00:00:00 |
8| 2023-01-03T00:00:00 |
9+---------------------+
10
11-- 将 timestamp 按 1 天间隔分桶，桶边界起点为 2023-01-01 的 03:00
12> SELECT date_bin(interval '1 day', time,  '2023-01-01T03:00:00') as bin
13FROM VALUES ('2023-01-01T18:18:18Z'), ('2023-01-03T19:00:03Z')  t(time);
14+---------------------+
15| bin                 |
16+---------------------+
17| 2023-01-01T03:00:00 |
18| 2023-01-03T03:00:00 |
19+---------------------+

`date_part`

以整数形式返回日期的指定部分。

语法：date_part(part, expression)

也可写作：extract(field FROM source)

参数：

part：要返回的日期部分。支持以下取值：
- year
- quarter（按日期所在的季度返回 [1, 4] 闭区间内的值）
- month
- week（一年中的第几周）
- day（一月中的第几天）
- hour
- minute
- second
- millisecond
- microsecond
- nanosecond
- dow（一周中的第几天）
- doy（一年中的第几天）
- epoch（自 Unix epoch 起的秒数）
expression：要处理的时间表达式，可以是常量、列或函数。

别名：datepart

示例：

SQL

1> SELECT date_part('hour', TIMESTAMP '2024-05-01 08:30:00');
2+-----------------------------------------------------+
3| date_part(Utf8("hour"),Utf8("2024-05-01 08:30:00")) |
4+-----------------------------------------------------+
5| 8                                                   |
6+-----------------------------------------------------+

`date_trunc`

将 timestamp 值截断到指定精度。

语法：date_trunc(precision, expression)

参数：

precision：截断到的时间精度。支持以下精度：
- year / YEAR
- quarter / QUARTER
- month / MONTH
- week / WEEK
- day / DAY
- hour / HOUR
- minute / MINUTE
- second / SECOND
expression：要处理的时间表达式，可以是常量、列或函数。

别名：datetrunc

示例：

SQL

1> SELECT date_trunc('hour', TIMESTAMP '2024-05-01 08:30:45');
2+------------------------------------------------------+
3| date_trunc(Utf8("hour"),Utf8("2024-05-01 08:30:45")) |
4+------------------------------------------------------+
5| 2024-05-01T08:00:00                                  |
6+------------------------------------------------------+

`from_unixtime`

将整数转换为 RFC3339 timestamp 格式（YYYY-MM-DDT00:00:00.000000000Z）。整数与无符号整数被解释为自 unix epoch（1970-01-01T00:00:00Z）起的秒数，返回对应的 timestamp。

语法：from_unixtime(expression[, timezone])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意运算符组合。
timezone：可选。将整数转换为 timestamp 时使用的时区，未提供时默认时区为 UTC。

示例：

SQL

1> select from_unixtime(1599572549, 'America/New_York');
2+-----------------------------------------------------------+
3| from_unixtime(Int64(1599572549),Utf8("America/New_York")) |
4+-----------------------------------------------------------+
5| 2020-09-08T09:42:29-04:00                                 |
6+-----------------------------------------------------------+

`make_date`

由年 / 月 / 日各组成部分构造日期。

语法：make_date(year, month, day)

参数：

year：构造日期所用的年份。可以是常量、列或函数，以及任意算术运算符组合。
month：构造日期所用的月份。可以是常量、列或函数，以及任意算术运算符组合。
day：构造日期所用的日。可以是常量、列或函数，以及任意算术运算符组合。

示例：

SQL

1> select make_date(2023, 1, 31);
2+-------------------------------------------+
3| make_date(Int64(2023),Int64(1),Int64(31)) |
4+-------------------------------------------+
5| 2023-01-31                                |
6+-------------------------------------------+
7> select make_date('2023', '01', '31');
8+-----------------------------------------------+
9| make_date(Utf8("2023"),Utf8("01"),Utf8("31")) |
10+-----------------------------------------------+
11| 2023-01-31                                    |
12+-----------------------------------------------+

`make_time`

由时 / 分 / 秒各组成部分构造时间。

语法：make_time(hour, minute, second)

参数：

hour：构造时间所用的小时。可以是常量、列或函数，以及任意算术运算符组合。
minute：构造时间所用的分钟。可以是常量、列或函数，以及任意算术运算符组合。
second：构造时间所用的秒。可以是常量、列或函数，以及任意算术运算符组合。

示例：

SQL

1> select make_time(13, 23, 1) AS make_time;
2+-----------+
3| make_time |
4+-----------+
5| 13:23:01  |
6+-----------+
7> select make_time('23', '01', '31') AS make_time;
8+-----------+
9| make_time |
10+-----------+
11| 23:01:31  |
12+-----------+

`now`

返回当前时刻的 timestamp，取值为 UTC，类型与 time 列相同（Timestamp(ns)，不带时区）。

now() 的返回值在查询开始时即确定，无论该函数在查询计划的哪个阶段执行，返回的都是同一个 timestamp。

语法：now()

别名：current_timestamp

示例：

SQL

1> SELECT now();
2+----------------------------+
3| now()                      |
4+----------------------------+
5| 2026-10-16T10:01:02.448509 |
6+----------------------------+

结果为查询开始时刻的值，随执行时间变化。

返回值不带时区，对它使用 AT TIME ZONE 与对 time 列一样是把墙上时间标注为目标时区，不做换算（见操作符的 AT TIME ZONE）。要得到当前时刻在某个时区的本地时间，先把它转换成带 UTC 时区的 timestamp：

SQL

1> SELECT arrow_cast(now(), 'Timestamp(Nanosecond, Some("UTC"))') AT TIME ZONE 'Asia/Shanghai' AS shanghai, now() AS n;
2+----------------------------------+----------------------------+
3| shanghai                         | n                          |
4+----------------------------------+----------------------------+
5| 2026-10-16T18:01:02.451711+08:00 | 2026-10-16T10:01:02.451711 |
6+----------------------------------+----------------------------+

`to_char`

按 Chrono 格式返回 date、time、timestamp 或 duration 的字符串表示。与 PostgreSQL 的同名函数不同，本函数不支持数值格式化。

语法：to_char(expression, format)

参数：

expression：要处理的表达式，可以是结果为 date、time、timestamp 或 duration 的常量、列或函数。
format：用于转换该表达式的 Chrono 格式字符串。

别名：date_format

示例：

SQL

1> select to_char('2023-03-01'::date, '%d-%m-%Y');
2+----------------------------------------------+
3| to_char(Utf8("2023-03-01"),Utf8("%d-%m-%Y")) |
4+----------------------------------------------+
5| 01-03-2023                                   |
6+----------------------------------------------+

`to_date`

将值转换为日期（YYYY-MM-DD）。支持字符串、整数和双精度浮点类型作为输入。未提供 Chrono 格式时，字符串按 YYYY-MM-DD 解析（如 '2023-07-20'）。整数和双精度数被解释为自 unix epoch（1970-01-01T00:00:00Z）起的天数。返回对应的日期。

注意：to_date 返回 Date32 类型，其值以带符号 32 位整数存储自 unix epoch（1970-01-01）起的天数。支持的最大日期值为 9999-12-31。

语法：to_date('2017-05-31', '%Y-%m-%d')

参数：

expression：要处理的字符串表达式，可以是常量、列或函数，以及任意运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_date('2023-01-31');
2+-----------------------------+
3| to_date(Utf8("2023-01-31")) |
4+-----------------------------+
5| 2023-01-31                  |
6+-----------------------------+
7> select to_date('2023/01/31', '%Y-%m-%d', '%Y/%m/%d');
8+---------------------------------------------------------------+
9| to_date(Utf8("2023/01/31"),Utf8("%Y-%m-%d"),Utf8("%Y/%m/%d")) |
10+---------------------------------------------------------------+
11| 2023-01-31                                                    |
12+---------------------------------------------------------------+

`to_local_time`

将带时区的 timestamp 转换为不带时区的 timestamp（不含偏移量或时区信息）。该函数会处理夏令时切换。

语法：to_local_time(expression)

参数：

expression：要处理的时间表达式，可以是常量、列或函数。

示例：

SQL

1> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp);
2+---------------------------------------------+
3| to_local_time(Utf8("2024-04-01T00:00:20Z")) |
4+---------------------------------------------+
5| 2024-04-01T00:00:20                         |
6+---------------------------------------------+
7
8> SELECT to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels');
9+---------------------------------------------+
10| to_local_time(Utf8("2024-04-01T00:00:20Z")) |
11+---------------------------------------------+
12| 2024-04-01T00:00:20                         |
13+---------------------------------------------+
14
15> SELECT
16  time,
17  arrow_typeof(time) as type,
18  to_local_time(time) as to_local_time,
19  arrow_typeof(to_local_time(time)) as to_local_time_type
20FROM (
21  SELECT '2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels' AS time
22);
23+---------------------------+----------------------------------+---------------------+--------------------+
24| time                      | type                             | to_local_time       | to_local_time_type |
25+---------------------------+----------------------------------+---------------------+--------------------+
26| 2024-04-01T00:00:20+02:00 | Timestamp(ns, "Europe/Brussels") | 2024-04-01T00:00:20 | Timestamp(ns)      |
27+---------------------------+----------------------------------+---------------------+--------------------+
28
29-- 将 to_local_time() 与 date_bin() 结合，按时区本地边界分桶，而非 UTC 边界
30
31> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AS date_bin;
32+---------------------+
33| date_bin            |
34+---------------------+
35| 2024-04-01T00:00:00 |
36+---------------------+
37
38> SELECT date_bin(interval '1 day', to_local_time('2024-04-01T00:00:20Z'::timestamp AT TIME ZONE 'Europe/Brussels')) AT TIME ZONE 'Europe/Brussels' AS date_bin_with_timezone;
39+---------------------------+
40| date_bin_with_timezone    |
41+---------------------------+
42| 2024-04-01T00:00:00+02:00 |
43+---------------------------+

`to_timestamp_micros`

将值转换为 timestamp（YYYY-MM-DDT00:00:00.000000Z）。支持字符串、整数和无符号整数类型作为输入。未提供 Chrono 格式时，字符串按 RFC3339 解析（如 '2023-07-20T05:44:00'）。整数和无符号整数被解释为自 unix epoch（1970-01-01T00:00:00Z）起的微秒数。返回对应的 timestamp。

语法：to_timestamp_micros(expression[, ..., format_n])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意算术运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_timestamp_micros('2023-01-31T09:26:56.123456789-05:00');
2+------------------------------------------------------------------+
3| to_timestamp_micros(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
4+------------------------------------------------------------------+
5| 2023-01-31T14:26:56.123456                                       |
6+------------------------------------------------------------------+
7> select to_timestamp_micros('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y');
8+---------------------------------------------------------------------------------------------------------------+
9| to_timestamp_micros(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
10+---------------------------------------------------------------------------------------------------------------+
11| 2023-05-17T03:59:00.123456                                                                                    |
12+---------------------------------------------------------------------------------------------------------------+

`to_timestamp_millis`

将值转换为 timestamp（YYYY-MM-DDT00:00:00.000Z）。支持字符串、整数和无符号整数类型作为输入。未提供 Chrono 格式时，字符串按 RFC3339 解析（如 '2023-07-20T05:44:00'）。整数和无符号整数被解释为自 unix epoch（1970-01-01T00:00:00Z）起的毫秒数。返回对应的 timestamp。

语法：to_timestamp_millis(expression[, ..., format_n])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意算术运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_timestamp_millis('2023-01-31T09:26:56.123456789-05:00');
2+------------------------------------------------------------------+
3| to_timestamp_millis(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
4+------------------------------------------------------------------+
5| 2023-01-31T14:26:56.123                                          |
6+------------------------------------------------------------------+
7> select to_timestamp_millis('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y');
8+---------------------------------------------------------------------------------------------------------------+
9| to_timestamp_millis(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
10+---------------------------------------------------------------------------------------------------------------+
11| 2023-05-17T03:59:00.123                                                                                       |
12+---------------------------------------------------------------------------------------------------------------+

`to_timestamp_nanos`

将值转换为 timestamp（YYYY-MM-DDT00:00:00.000000000Z）。支持字符串、整数和无符号整数类型作为输入。未提供 Chrono 格式时，字符串按 RFC3339 解析（如 '2023-07-20T05:44:00'）。整数和无符号整数被解释为自 unix epoch（1970-01-01T00:00:00Z）起的纳秒数。返回对应的 timestamp。

语法：to_timestamp_nanos(expression[, ..., format_n])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意算术运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_timestamp_nanos('2023-01-31T09:26:56.123456789-05:00');
2+-----------------------------------------------------------------+
3| to_timestamp_nanos(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
4+-----------------------------------------------------------------+
5| 2023-01-31T14:26:56.123456789                                   |
6+-----------------------------------------------------------------+
7> select to_timestamp_nanos('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y');
8+--------------------------------------------------------------------------------------------------------------+
9| to_timestamp_nanos(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
10+--------------------------------------------------------------------------------------------------------------+
11| 2023-05-17T03:59:00.123456789                                                                                |
12+---------------------------------------------------------------------------------------------------------------+

`to_timestamp_seconds`

语法：to_timestamp_seconds(expression[, ..., format_n])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意算术运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_timestamp_seconds('2023-01-31T09:26:56.123456789-05:00');
2+-------------------------------------------------------------------+
3| to_timestamp_seconds(Utf8("2023-01-31T09:26:56.123456789-05:00")) |
4+-------------------------------------------------------------------+
5| 2023-01-31T14:26:56                                               |
6+-------------------------------------------------------------------+
7> select to_timestamp_seconds('03:59:00.123456789 05-17-2023', '%c', '%+', '%H:%M:%S%.f %m-%d-%Y');
8+----------------------------------------------------------------------------------------------------------------+
9| to_timestamp_seconds(Utf8("03:59:00.123456789 05-17-2023"),Utf8("%c"),Utf8("%+"),Utf8("%H:%M:%S%.f %m-%d-%Y")) |
10+----------------------------------------------------------------------------------------------------------------+
11| 2023-05-17T03:59:00                                                                                            |
12+----------------------------------------------------------------------------------------------------------------+

`to_time`

将值转换为一天之内的时间（HH:MM:SS.nnnnnnnnn）。支持字符串和 timestamp 作为输入：未提供 Chrono 格式时，字符串按 HH:MM:SS、HH:MM:SS.nnnnnnnnn 或 HH:MM 解析；timestamp 取其中的时间部分。返回 Time64(ns) 类型，即自午夜起的纳秒数。

语法：to_time(expression[, ..., format_n])

参数：

expression：要处理的字符串或 timestamp 表达式，可以是常量、列或函数，以及任意运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_time('12:30:45') AS to_time;
2+----------+
3| to_time  |
4+----------+
5| 12:30:45 |
6+----------+
7> select to_time('12-30-45', '%H-%M-%S') AS to_time;
8+----------+
9| to_time  |
10+----------+
11| 12:30:45 |
12+----------+
13> select to_time('2024-04-01T12:30:45Z'::timestamp) AS to_time;
14+----------+
15| to_time  |
16+----------+
17| 12:30:45 |
18+----------+

`to_unixtime`

将值转换为自 unix epoch（1970-01-01T00:00:00Z）起的秒数。支持字符串、日期、timestamp、整数、无符号整数和浮点类型作为输入。未提供 Chrono 格式时，字符串按 RFC3339 解析（如 '2023-07-20T05:44:00'）；整数、无符号整数和浮点数被解释为自 unix epoch 起的秒数。

语法：to_unixtime(expression[, ..., format_n])

参数：

expression：要处理的表达式，可以是常量、列或函数，以及任意算术运算符组合。
format_n：可选。用于解析表达式的 Chrono 格式字符串，按出现顺序依次尝试，返回第一个成功解析的结果；若所有格式都无法解析该表达式，则返回错误。

示例：

SQL

1> select to_unixtime('2020-09-08T12:00:00+00:00');
2+------------------------------------------------+
3| to_unixtime(Utf8("2020-09-08T12:00:00+00:00")) |
4+------------------------------------------------+
5| 1599566400                                     |
6+------------------------------------------------+
7> select to_unixtime('01-14-2023 01:01:30+05:30', '%q', '%d-%m-%Y %H/%M/%S', '%+', '%m-%d-%Y %H:%M:%S%#z');
8+-----------------------------------------------------------------------------------------------------------------------------+
9| to_unixtime(Utf8("01-14-2023 01:01:30+05:30"),Utf8("%q"),Utf8("%d-%m-%Y %H/%M/%S"),Utf8("%+"),Utf8("%m-%d-%Y %H:%M:%S%#z")) |
10+-----------------------------------------------------------------------------------------------------------------------------+
11| 1673638290                                                                                                                  |
12+-----------------------------------------------------------------------------------------------------------------------------+

时序扩展函数

以下函数是时序场景专用扩展，语义以本节为准。补齐缺口（gap filling）示例统一基于下面这份带缺口的样例数据（temps 表，每分钟一个点，缺 00:02 与 00:03 两分钟）：

Plain Text

1+---------------------+------+
2| time                | temp |
3+---------------------+------+
4| 2024-01-01T00:00:00 | 20.0 |
5| 2024-01-01T00:01:00 | 21.0 |
6| 2024-01-01T00:04:00 | 24.0 |
7| 2024-01-01T00:05:00 | 25.0 |
8+---------------------+------+

`date_bin_gapfill`

参数与 date_bin 相同（expression 另有限制，见下），在按固定窗口分箱之外，还会为查询时间范围内没有数据的时间窗生成行。缺口行的聚合值默认为 NULL，可用 locf 或 interpolate 包裹聚合表达式改变填充策略。

语法：date_bin_gapfill(interval, expression[, origin-timestamp])

参数：

interval：分箱窗口宽度（interval 字面量）。
expression：timestamp 列，通常是 time。列可以先经 tz、AT TIME ZONE 或 arrow_cast 转到带时区的类型，分箱按转换后的取值进行，两类转换得到的取值不同：tz 按 UTC 解释 time 再换算到目标时区，表示的时刻不变，只是桶按该时区显示；对不带时区的 time 用 AT TIME ZONE（或用 arrow_cast 转到带时区的类型）是把墙上时间标注为目标时区，表示的时刻随之改变，例如 08:00Z 的数据经 tz(time, 'Asia/Shanghai') 落进 16:00+08:00 的桶，经 time AT TIME ZONE 'Asia/Shanghai' 落进 08:00+08:00（即 00:00Z）的桶。精度必须保持纳秒，转换到其他精度时查询报错。
origin：可选，分箱原点时间戳，缺省 1970-01-01T00:00:00Z。

用法约束：

必须出现在 SELECT 列表中，并同时作为 GROUP BY 的分组键。
为哪些时间窗生成行，由 WHERE 放行的该列取值范围决定，范围的上下界都必须给出，缺一时查询报错。范围取自该列与常量的比较：<、<=、>、>=、= 与 BETWEEN，列可以先经 tz（任意时区）、标注到固定偏移的 AT TIME ZONE（'+08:00'）或精度转换再比较；多个条件同时出现时取它们的交集，交集为空时结果为空。OR、IN、NOT 等写法照常过滤，但不决定范围。
比较的常量可以是字面量、查询参数（$1）、now() 及其运算，不能含 random() 这类每次求值结果不同的函数，否则查询报错。
把列标注到命名时区后再比较（time AT TIME ZONE 'Asia/Shanghai' >= …，或 time 直接与带命名时区的值比较）时范围无法确定，查询报错；改为把常量写成带偏移的字符串，例如 time >= '2024-01-01T08:00:00+08:00'。
该函数只能按上述形态使用，不能脱离这一形态单独调用。

示例：

SQL

1> SELECT date_bin_gapfill(INTERVAL '1 minute', time) AS minute, avg(temp) AS avg_temp FROM temps WHERE time >= '2024-01-01T00:00:00Z' AND time < '2024-01-01T00:06:00Z' GROUP BY minute ORDER BY minute;
2+---------------------+----------+
3| minute              | avg_temp |
4+---------------------+----------+
5| 2024-01-01T00:00:00 | 20.0     |
6| 2024-01-01T00:01:00 | 21.0     |
7| 2024-01-01T00:02:00 |          |
8| 2024-01-01T00:03:00 |          |
9| 2024-01-01T00:04:00 | 24.0     |
10| 2024-01-01T00:05:00 | 25.0     |
11+---------------------+----------+

相关函数：locf、interpolate、date_bin_wallclock_gapfill

`locf`

用于补缺口查询的填充策略函数（last observation carried forward）：缺口行的值沿用前一个有数据时间窗的观测值。只能在包含 date_bin_gapfill / date_bin_wallclock_gapfill 的查询里包裹聚合表达式使用，不能单独调用。

语法：locf(aggregate_expression)

参数：

aggregate_expression：要填充的聚合表达式，任意类型。

示例：

SQL

1> SELECT date_bin_gapfill(INTERVAL '1 minute', time) AS minute, locf(avg(temp)) AS avg_temp FROM temps WHERE time >= '2024-01-01T00:00:00Z' AND time < '2024-01-01T00:06:00Z' GROUP BY minute ORDER BY minute;
2+---------------------+----------+
3| minute              | avg_temp |
4+---------------------+----------+
5| 2024-01-01T00:00:00 | 20.0     |
6| 2024-01-01T00:01:00 | 21.0     |
7| 2024-01-01T00:02:00 | 21.0     |
8| 2024-01-01T00:03:00 | 21.0     |
9| 2024-01-01T00:04:00 | 24.0     |
10| 2024-01-01T00:05:00 | 25.0     |
11+---------------------+----------+

相关函数：date_bin_gapfill、interpolate

`interpolate`

用于补缺口查询的填充策略函数：缺口行的值由前后相邻观测值线性插值得出，参数必须是数值类型。只能在包含 date_bin_gapfill / date_bin_wallclock_gapfill 的查询里包裹聚合表达式使用，不能单独调用。

语法：interpolate(aggregate_expression)

参数：

aggregate_expression：要插值的聚合表达式，数值类型。

示例：

SQL

1> SELECT date_bin_gapfill(INTERVAL '1 minute', time) AS minute, interpolate(avg(temp)) AS avg_temp FROM temps WHERE time >= '2024-01-01T00:00:00Z' AND time < '2024-01-01T00:06:00Z' GROUP BY minute ORDER BY minute;
2+---------------------+----------+
3| minute              | avg_temp |
4+---------------------+----------+
5| 2024-01-01T00:00:00 | 20.0     |
6| 2024-01-01T00:01:00 | 21.0     |
7| 2024-01-01T00:02:00 | 22.0     |
8| 2024-01-01T00:03:00 | 23.0     |
9| 2024-01-01T00:04:00 | 24.0     |
10| 2024-01-01T00:05:00 | 25.0     |
11+---------------------+----------+

相关函数：date_bin_gapfill、locf

`date_bin_wallclock`

与 date_bin 类似，但按输入时间戳所属时区的墙上钟（wallclock）时间划分时间窗：时区取自 expression 参数的数据类型（可先用 tz 转换），结果保持相同类型（含时区）。interval 不支持月和年；origin 必须是不带时区的墙上钟时间，缺省 1970-01-01T00:00:00。

夏令时产生的不存在时间会顺延同等偏移；二义时间在窗口大于两个候选时刻之差时取较早者，否则按输入的 UTC 偏移对齐。数据为 UTC、或窗口远小于夏令时偏移时，建议直接用 date_bin。

语法：date_bin_wallclock(interval, expression[, origin-timestamp])

参数：

interval：分箱窗口宽度（interval 字面量），不支持月和年。
expression：timestamp 表达式，时区取自其数据类型。
origin：可选，不带时区的墙上钟原点，缺省 1970-01-01T00:00:00。

示例：

SQL

1> SELECT date_bin_wallclock(INTERVAL '1 day', tz(TIMESTAMP '2024-06-01 20:30:00', 'Asia/Shanghai'));
2+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
3| date_bin_wallclock(IntervalMonthDayNano("IntervalMonthDayNano { months: 0, days: 1, nanoseconds: 0 }"),tz(Utf8("2024-06-01 20:30:00"),Utf8("Asia/Shanghai"))) |
4+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
5| 2024-06-02T00:00:00+08:00                                                                                                                                     |
6+---------------------------------------------------------------------------------------------------------------------------------------------------------------+

按东八区墙上钟对齐到天边界（2024-06-02T00:00:00+08:00）；同一时刻用 date_bin 按 UTC 对齐，得到的是起点为 2024-06-01T00:00:00Z 的 UTC 天窗口（在东八区偏移下显示为 2024-06-01T08:00:00+08:00），两者边界不同。

相关函数：tz、date_bin_wallclock_gapfill

`date_bin_wallclock_gapfill`

date_bin_wallclock 的补缺口版本：参数与其相同，expression 的限制、行为与用法约束都同 date_bin_gapfill（缺口行默认 NULL，可配 locf / interpolate；必须同时作为 SELECT 列与 GROUP BY 分组键，时间窗由 WHERE 放行的取值范围决定）。

语法：date_bin_wallclock_gapfill(interval, expression[, origin-timestamp])

示例：

SQL

1> SELECT date_bin_wallclock_gapfill(INTERVAL '1 minute', time) AS minute, avg(temp) AS avg_temp FROM temps WHERE time >= '2024-01-01T00:00:00Z' AND time < '2024-01-01T00:06:00Z' GROUP BY minute ORDER BY minute;
2+---------------------+----------+
3| minute              | avg_temp |
4+---------------------+----------+
5| 2024-01-01T00:00:00 | 20.0     |
6| 2024-01-01T00:01:00 | 21.0     |
7| 2024-01-01T00:02:00 |          |
8| 2024-01-01T00:03:00 |          |
9| 2024-01-01T00:04:00 | 24.0     |
10| 2024-01-01T00:05:00 | 25.0     |
11+---------------------+----------+

相关函数：date_bin_wallclock、locf、interpolate

`tz`

把纳秒 timestamp 转换到指定时区：无时区输入按 UTC 解释，输出带上目标时区偏移。timezone 必须是字符串字面量，接受 IANA 时区名（如 'Asia/Shanghai'）或固定偏移（如 '+08:00'），缺省 'UTC'。通常与 date_bin_wallclock、date_trunc 配合做本地时间分析。

语法：tz(expression[, timezone])

参数：

expression：纳秒 timestamp 表达式，带或不带时区均可。
timezone：可选，目标时区字符串字面量，缺省 'UTC'。

示例：

SQL

1> SELECT tz(TIMESTAMP '2024-01-01 00:00:00', 'Asia/Shanghai');
2+-------------------------------------------------------+
3| tz(Utf8("2024-01-01 00:00:00"),Utf8("Asia/Shanghai")) |
4+-------------------------------------------------------+
5| 2024-01-01T08:00:00+08:00                             |
6+-------------------------------------------------------+

相关函数：date_bin_wallclock、to_local_time

`to_timestamp`

转换为纳秒 timestamp：整数参数按纳秒 Unix 时间解释；timestamp 参数转为纳秒精度；字符串参数按 RFC 3339 或给定的 Chrono 格式串解析。返回值始终为纳秒 timestamp。需要按秒转换时用 to_timestamp_seconds。

语法：to_timestamp(expression[, ..., format_n])

参数：

expression：整数（纳秒 Unix 时间）、timestamp 或字符串表达式。
format_n：可选，仅字符串输入时使用的 Chrono 格式串，按顺序尝试。

示例：

SQL

1> SELECT to_timestamp(1704067200000000000);
2+------------------------------------------+
3| to_timestamp(Int64(1704067200000000000)) |
4+------------------------------------------+
5| 2024-01-01T00:00:00                      |
6+------------------------------------------+

评价此篇文章

有帮助没帮助

窗口函数

数学函数

百度智能云

时序时空数据库 TSDB

时序时空数据库 TSDB

时间日期函数

`current_date`

`current_time`

`date_bin`

`date_part`

`date_trunc`

`from_unixtime`

`make_date`

`make_time`

`now`

`to_char`

`to_date`

`to_local_time`

`to_timestamp_micros`

`to_timestamp_millis`

`to_timestamp_nanos`

`to_timestamp_seconds`

`to_time`

`to_unixtime`

时序扩展函数

`date_bin_gapfill`

`locf`

`interpolate`

`date_bin_wallclock`

`date_bin_wallclock_gapfill`

`tz`

`to_timestamp`