Timescale 文档 - TimescaleDB 时序数据库

timescaledb_experimental.time_bucket_ng()

实验性实验性功能不适用于生产环境。它们包含在 TimescaleDB experimental 模式下。点击了解更多。

time_bucket_ng() 函数是 time_bucket() 函数的实验版本。它引入了一些新功能，例如每月存储桶和时区支持。这些功能现在是常规 time_bucket() 函数的一部分。

弃用

本节介绍 Timescale 上已弃用的功能。我们强烈建议您不要在生产环境中使用此功能。如果您需要更多信息，请联系我们。

警告

time_bucket() 和 time_bucket_ng() 函数类似，但并非完全兼容。主要有两个区别。

首先，time_bucket_ng() 不适用于 origin 之前的的时间戳，而 time_bucket() 可以。

其次，默认的 origin 值不同。对于小于一个月的存储桶，time_bucket() 使用 2000 年 1 月 3 日的起始日期。对于所有存储桶大小，time_bucket_ng() 使用 2000 年 1 月 1 日的起始日期。

必需参数

名称	类型	描述
`bucket_width`	INTERVAL	PostgreSQL 时间间隔，表示每个存储桶的持续时间
`ts`	DATE、TIMESTAMP 或 TIMESTAMPTZ	要分桶的时间戳

可选参数

名称	类型	描述
`origin`	应与 `ts` 相同	存储桶相对于此时间戳对齐
`timezone`	TEXT	时区的名称。仅当 `ts` 的类型为 TIMESTAMPTZ 时，才能指定此参数

为了向后兼容 time_bucket()，timezone 参数是可选的。但是，对于小于 24 小时的时间桶，它是必需的。

如果您在不使用 timezone 参数的情况下调用函数的 TIMESTAMPTZ 版本，则时区默认为会话的时区，因此该函数不能与连续聚合一起使用。最佳实践是使用 time_bucket_ng(interval, timestamptz, text) 并指定时区。

返回值

该函数返回存储桶的开始时间。返回值类型与 ts 相同。

用法示例

在此示例中，time_bucket_ng() 用于创建三个月间隔的存储桶数据


SELECT timescaledb_experimental.time_bucket_ng('3 month', date '2021-08-01');
 time_bucket_ng
----------------
 2021-07-01
(1 row)

此示例使用 time_bucket_ng() 以一年为间隔对数据进行分桶


SELECT timescaledb_experimental.time_bucket_ng('1 year', date '2021-08-01');
 time_bucket_ng
----------------
 2021-01-01
(1 row)

为了将时间分成存储桶，time_bucket_ng() 使用一个称为 origin 的时间起点。默认的 origin 是 2000-01-01。time_bucket_ng 无法使用早于 origin 的时间戳


SELECT timescaledb_experimental.time_bucket_ng('100 years', timestamp '1988-05-08');
ERROR:  origin must be before the given date

从 origin 回溯时间通常是不可能的，尤其是在考虑时区和夏令时 (DST) 时。另请注意，没有合理的方法可以从任意 origin 中分割可变大小的存储桶（例如月份），因此 origin 默认为每月的第一天。

要绕过已命名的限制，您可以覆盖默认的 origin


-- working with timestamps before 2000-01-01
SELECT timescaledb_experimental.time_bucket_ng('100 years', timestamp '1988-05-08', origin => '1900-01-01');
   time_bucket_ng
---------------------
 1900-01-01 00:00:00

-- unlike the default origin, which is Saturday, 2000-01-03 is Monday
SELECT timescaledb_experimental.time_bucket_ng('1 week', timestamp '2021-08-26', origin => '2000-01-03');
   time_bucket_ng
---------------------
 2021-08-23 00:00:00

此示例显示了如何使用 time_bucket_ng() 按指定时区中的月份对数据进行分桶


-- note that timestamptz is displayed differently depending on the session parameters
SET TIME ZONE 'Europe/Moscow';
SET

SELECT timescaledb_experimental.time_bucket_ng('1 month', timestamptz '2001-02-03 12:34:56 MSK', timezone => 'Europe/Moscow');
     time_bucket_ng
------------------------
 2001-02-01 00:00:00+03

您可以将 time_bucket_ng() 与连续聚合一起使用。此示例跟踪莫斯科七天间隔的温度


CREATE TABLE conditions(
  day DATE NOT NULL,
  city text NOT NULL,
  temperature INT NOT NULL);

SELECT create_hypertable(
  'conditions', by_range('day', INTERVAL '1 day')
);

INSERT INTO conditions (day, city, temperature) VALUES
  ('2021-06-14', 'Moscow', 26),
  ('2021-06-15', 'Moscow', 22),
  ('2021-06-16', 'Moscow', 24),
  ('2021-06-17', 'Moscow', 24),
  ('2021-06-18', 'Moscow', 27),
  ('2021-06-19', 'Moscow', 28),
  ('2021-06-20', 'Moscow', 30),
  ('2021-06-21', 'Moscow', 31),
  ('2021-06-22', 'Moscow', 34),
  ('2021-06-23', 'Moscow', 34),
  ('2021-06-24', 'Moscow', 34),
  ('2021-06-25', 'Moscow', 32),
  ('2021-06-26', 'Moscow', 32),
  ('2021-06-27', 'Moscow', 31);

CREATE MATERIALIZED VIEW conditions_summary_weekly
WITH (timescaledb.continuous) AS
SELECT city,
       timescaledb_experimental.time_bucket_ng('7 days', day) AS bucket,
       MIN(temperature),
       MAX(temperature)
FROM conditions
GROUP BY city, bucket;

SELECT to_char(bucket, 'YYYY-MM-DD'), city, min, max
FROM conditions_summary_weekly
ORDER BY bucket;

  to_char   |  city  | min | max
------------+--------+-----+-----
 2021-06-12 | Moscow |  22 |  27
 2021-06-19 | Moscow |  28 |  34
 2021-06-26 | Moscow |  31 |  32
(3 rows)

注意

by_range 维度构建器是 TimescaleDB 2.13 的新增功能。对于更简单的情况（如本例），您也可以使用旧语法创建超表


SELECT create_hypertable('<table name>', '<time column name>');

有关更多信息，请参阅连续聚合文档。

重要提示

虽然 time_bucket_ng() 支持月份和时区，但连续聚合并非始终可以与每月存储桶或带时区的存储桶一起使用。

下表显示了哪些 time_bucket_ng() 函数可以在连续聚合中使用

函数	在连续聚合中可用	TimescaleDB 版本
按秒、分钟、小时、天和周分桶	✅	2.4.0 - 2.14.2
按月和年分桶	✅	2.6.0 - 2.14.2
时区支持	✅	2.6.0 - 2.14.2
指定自定义起始时间	✅	2.7.0 - 2.14.2

timescaledb_experimental.time_bucket_ng()

弃用

警告

必需参数

可选参数

返回值

用法示例

注意

重要提示

相关内容