create_hypertable() (旧接口)

警告

此页面描述了 TimescaleDB v2.13 之前支持的超表 API。最佳实践是使用新的 create_hypertable 接口。

从 PostgreSQL 表创建 TimescaleDB 超表（替换后者），按时间分区，并可选择按一个或多个其他列分区。PostgreSQL 表不能是已分区的表（声明式分区或继承）。对于非空表，可以在超表创建期间使用 migrate_data 选项迁移数据，但这可能需要很长时间，并且当表包含外键约束时存在某些限制（见下文）。

创建后，所有操作（例如 ALTER TABLE、SELECT 等）仍然在生成的超表上工作。

有关使用超表的更多信息，包括数据块大小分区，请参阅超表部分。

注意

如果您使用 SELECT * FROM create_hypertable(...)，您将获得返回值为表格格式，带有列标题。

使用 migrate_data 参数转换非空表可能会锁定表相当长的时间，具体取决于表中的数据量。如果存在对外键约束的其他表，也可能导致死锁。

将普通 SQL 表转换为超表时，请注意如何处理约束。超表可以包含指向普通 SQL 表列的外键，但不允许反向操作。UNIQUE 和 PRIMARY 约束必须包含分区键。

当并发事务同时尝试将数据插入到外键约束中引用的表以及正在转换的表本身时，很可能发生死锁。可以通过在同一事务中调用 create_hypertable 之前手动获取对引用表的 SHARE ROW EXCLUSIVE 锁来防止死锁，请参阅 PostgreSQL 文档 以了解语法。

time 列支持以下数据类型

注意

“time”列的类型灵活性允许使用非基于时间的值作为主数据块分区列，只要这些值可以递增。

对于不兼容的数据类型（例如，jsonb），您可以为 time_partitioning_func 参数指定一个函数，该函数可以提取兼容的数据类型。

chunk_time_interval 的单位应按如下方式设置

• 对于具有时间戳或 DATE 类型的 time 列，chunk_time_interval 应指定为 interval 类型或微秒为单位的整数值。
• 对于整数类型，chunk_time_interval 必须 显式设置，因为数据库无法理解每个整数值代表的语义（秒、毫秒、纳秒等）。因此，如果您的时间列是自 UNIX 纪元以来的毫秒数，并且您希望每个数据块覆盖 1 天，则应指定 chunk_time_interval => 86400000。

在哈希分区的情况下（换句话说，如果 number_partitions 大于零），可以选择指定自定义分区函数。如果未指定自定义分区函数，则使用默认分区函数。默认分区函数为给定的类型调用 PostgreSQL 的内部哈希函数（如果存在）。因此，自定义分区函数可用于没有本机 PostgreSQL 哈希函数的值类型。分区函数应接受单个 anyelement 类型参数并返回正 integer 哈希值。请注意，此哈希值不是分区 ID，而是插入值在维度键空间中的位置，然后将其分配到各个分区。

注意

create_hypertable 中的 time 列必须定义为 NOT NULL。如果在表创建时未指定此项，则 create_hypertable 在执行时会自动在表上添加此约束。

将表 conditions 转换为超表，仅按列 time 进行时间分区

SELECT create_hypertable('conditions', 'time');

复制

将表 conditions 转换为超表，将 chunk_time_interval 设置为 24 小时。

SELECT create_hypertable('conditions', 'time', chunk_time_interval => 86400000000);
SELECT create_hypertable('conditions', 'time', chunk_time_interval => INTERVAL '1 day');

复制

将表 conditions 转换为超表。如果 conditions 已经是超表，则不发出警告

SELECT create_hypertable('conditions', 'time', if_not_exists => TRUE);

复制

使用时间分区函数对复合列类型 report 的表 measurements 进行时间分区。需要一个不可变函数，可以将列值转换为受支持的列值

CREATE TYPE report AS (reported timestamp with time zone, contents jsonb);

CREATE FUNCTION report_reported(report)
  RETURNS timestamptz
  LANGUAGE SQL
  IMMUTABLE AS
  'SELECT $1.reported';

SELECT create_hypertable('measurements', 'report', time_partitioning_func => 'report_reported');

复制

对列类型为 jsonb (event) 的表 events 进行时间分区，该列类型具有包含 ISO 8601 格式时间戳的顶级键 (started)

CREATE FUNCTION event_started(jsonb)
  RETURNS timestamptz
  LANGUAGE SQL
  IMMUTABLE AS
  $func$SELECT ($1->>'started')::timestamptz$func$;

SELECT create_hypertable('events', 'event', time_partitioning_func => 'event_started');

复制