create_hypertable()

将标准 PostgreSQL 关系表替换为在单个维度上分区的超表。

超表是一个 PostgreSQL 表，它可以按时间自动分区您的数据。维度定义了数据分区的方式。所有操作都在生成的超表上进行。例如，ALTER TABLE 和 SELECT。

如果要转换的表已包含数据，请将 migrate_data 设置为 TRUE。但是，这可能需要很长时间，并且当表包含外键约束时会存在限制。

您无法在已使用声明式分区或继承分区的表上运行 create_hypertable()。时间列必须定义为 NOT NULL。如果在表创建时未指定此项，则 create_hypertable 会在执行时自动在表上添加此约束。

此页面描述了 TimescaleDB v2.13 中引入的通用超表 API。create_hypertable 的旧接口也可用。

本节中的示例向您展示如何

• 按时间范围对超表进行时间分区
• 使用复合列和不可变函数对超表进行时间分区
• 使用 ISO 格式对超表进行时间分区

以下示例展示了将 conditions 关系表转换为超表的不同方法

• 使用 time 列上的范围分区进行转换

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

  复制

• 使用 24 小时的 chunk_time_interval 进行转换：任一方式

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

  复制

  或

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

  复制

• 如果 conditions 已经是超表，则在使用 time 列上的范围分区时，不要引发警告

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

  复制

注意

如果您调用 SELECT * FROM create_hypertable(...)，则返回值将格式化为带有列标题的表。

以下示例展示了如何使用范围分区函数在复合列类型上对 measurements 关系表进行时间分区。

1. 创建报告类型，然后创建一个不可变函数，将列值转换为受支持的列值

   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', by_range('report', partition_func => 'report_reported'));

   复制

2. 使用不可变函数创建超表

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

   复制

以下示例展示了如何对 events 表的 jsonb (event) 列类型进行时间分区，该列类型具有包含 ISO 8601 格式时间戳的顶级 started 键

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

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

复制

要创建 _timescaledb_internal.dimension_info 实例，您可以调用
当您创建超表时，或当您向现有超表添加维度时，调用 by_range 和 by_hash。

超表必须始终具有主范围维度，后跟任意数量的附加维度，这些维度可以是范围或哈希，通常只有一个哈希。例如

SELECT create_hypertable('conditions', by_range('time'));
SELECT add_dimension('conditions', by_hash('location', 2));

复制

对于不兼容的数据类型（如 jsonb），您可以为维度构建的 partition_func 参数指定一个函数，以提取兼容的数据类型。请查看下面的示例部分。

默认情况下，TimescaleDB 为给定类型调用 PostgreSQL 的内部哈希函数。对于没有原生 PostgreSQL 哈希函数的值类型，您可以使用自定义分区函数。

您可以为范围分区和哈希分区指定自定义分区函数。分区函数应接受 anyelement 参数作为唯一参数，并返回正 integer 哈希值。此哈希值不是分区标识符，而是插入值在维度键空间中的位置，然后将其分配到各个分区。

创建一个按范围维度构建器。您可以单独对 by_range 进行分区。

示例

最简单的用法是在时间列上进行分区

SELECT create_hypertable('my_table', by_range('time'));

复制

这是默认分区，您无需显式添加它。

如果您的表具有包含时间的非时间列（例如 JSON 列），请添加一个分区函数来提取时间。

CREATE TABLE my_table (
   metric_id serial not null,
   data jsonb,
);

CREATE FUNCTION get_time(jsonb) RETURNS timestamptz AS $$
  SELECT ($1->>'time')::timestamptz
$$ LANGUAGE sql IMMUTABLE;

SELECT create_hypertable('my_table', by_range('data', '1 day', 'get_time'));

复制

参数

如果要分区的列是

• TIMESTAMP、TIMESTAMPTZ 或 DATE：将 partition_interval 指定为 INTERVAL 类型或微秒为单位的整数值。

• 另一种整数类型：将 partition_interval 指定为反映列的底层语义的整数。例如，如果此列以 UNIX 时间为单位，请以毫秒为单位指定 partition_interval。

分区类型和默认值取决于列类型

哈希分区的主要目的是在同一时间间隔内在多个磁盘上实现并行化。哈希分区中的每个不同项都哈希到 N 个存储桶之一。默认情况下，TimescaleDB 使用灵活的范围间隔来管理数据块大小。

在以下情况下使用并行 I/O

• 两个或多个并发查询应该能够并行地从不同的磁盘读取。
• 单个查询应该能够使用查询并行化来并行地从多个磁盘读取。

对于以下选项

• RAID：在多个物理磁盘上使用 RAID 设置，并将单个逻辑磁盘公开给超表。也就是说，使用单个表空间。

  最佳实践是在可能的情况下使用 RAID，因为您无需在数据库中手动管理表空间。

• 多个表空间：对于每个物理磁盘，向数据库添加单独的表空间。TimescaleDB 允许您向单个超表添加多个表空间。但是，尽管在底层，超表的数据块分布在与该超表关联的表空间中。

  使用多个表空间时，最佳实践是还向超表添加第二个哈希分区维度，并在每个磁盘上至少有一个哈希分区。虽然单个时间维度也有效，但这将意味着第一个数据块写入一个表空间，第二个数据块写入另一个表空间，依此类推，因此只有当查询的时间范围超过单个数据块时才会并行化。

添加哈希分区维度时，将分区数设置为磁盘数的倍数。例如，分区数 P=N*Pd，其中 N 是磁盘数，Pd 是每个磁盘的分区数。这使您以后可以添加更多磁盘，并将分区从其他磁盘移动到新磁盘。

TimescaleDB 不会从非常大量的哈希分区中受益，例如您在分区字段中期望的唯一项的数量。大量的哈希分区会导致每个分区的负载平衡效果较差（使用哈希将项映射到分区），以及某些类型的查询的计划延迟大大增加。

示例

SELECT create_hypertable('conditions', by_range('time'));
SELECT add_dimension('conditions', by_hash('location', 2));
SELECT add_dimension('conditions', by_range('time_received', INTERVAL '1 day'));

复制

参数

by_range 和 by_hash 返回一个不透明的 _timescaledb_internal.dimension_info 实例，其中包含此函数使用的维度信息。