timescaledb_experimental.time_bucket_ng()

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

Timescale Cloud：性能、扩展、企业级

自托管产品

MST

time_bucket_ng() 函数是 time_bucket() 函数的一个实验性版本。它引入了一些新功能，例如按月分桶和时区支持。这些功能现已成为常规 time_bucket() 函数的一部分。

弃用

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

警告

time_bucket() 和 time_bucket_ng() 函数相似，但并非完全兼容。它们主要有以下两点不同。

首先，time_bucket_ng() 不支持 origin 之前的 timestamp，而 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 小时的时间桶，此参数是必需的。

如果您调用该函数的 TIMESTAMPTZ 版本时未提供 timezone 参数，则时区将默认为会话的时区，因此该函数无法与连续聚合一起使用。最佳实践是使用 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
指定自定义 origin	✅	2.7.0 - 2.14.2

timescaledb_experimental.time_bucket_ng()

弃用

警告

必需参数

可选参数

返回

示例用法

注意

重要

相关内容