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 类型的列，chunk_time_interval 应指定为 interval 类型或以微秒为单位的整数值。
• 对于整数类型，**必须**显式设置 chunk_time_interval，因为数据库不了解每个整数值表示的语义（秒、毫秒、纳秒等）。因此，如果您的时间列是自 UNIX 纪元以来的毫秒数，并且您希望每个数据块覆盖 1 天，则应指定 chunk_time_interval => 86400000。

如果是哈希分区（换句话说，如果 number_partitions 大于零），可以选择指定自定义分区函数。如果未指定自定义分区函数，则使用默认分区函数。默认分区函数会调用 PostgreSQL 针对给定类型（如果存在）的内部哈希函数。因此，自定义分区函数可用于没有原生 PostgreSQL 哈希函数的值类型。分区函数应接受单个 anyelement 类型参数，并返回一个正 integer 哈希值。请注意，此哈希值不是分区 ID，而是插入值在维度键空间中的位置，该位置随后在分区之间进行划分。

注意

create_hypertable 中的时间列必须定义为 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');

复制

对表 events 进行时间分区，在 jsonb (event) 列类型上，其中包含一个顶级键 (started)，该键包含 ISO 8601 格式的时间戳。

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');

复制