add_dimension()

向 Timescale 超表添加额外的分区维度。您只能在空超表上执行此 add_dimension 命令。要将普通表转换为超表，请调用 create hypertable。

您选择作为维度的列可以使用：

• 范围分区：例如，用于第二个范围分区。
• 哈希分区：以实现跨多个磁盘的并行化。

这些说明适用于自托管 TimescaleDB 部署。

最佳实践是不使用额外的维度。然而，Timescale Cloud 在存储容量和可用存储 IOPS/带宽方面透明地提供了无缝存储扩展。

试用 Timescale Cloud

本页描述了 TimescaleDB v2.13.0 中引入的通用超表 API。有关已弃用接口的信息，请参阅 add_dimension()，已弃用接口。

首先将表 conditions 转换为仅在列 time 上进行范围分区的超表，然后添加一个在 location 上具有四个分区的额外分区键。

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

复制

注意

by_range 和 by_hash 维度构建器是 TimescaleDB 2.13 的新增功能。

将表 conditions 转换为超表，在 time 上进行范围分区，然后添加三个额外维度：一个在 location 上的哈希分区，一个在 time_received 上的范围分区，以及一个在 device_id 上的哈希分区。

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'));
SELECT add_dimension('conditions', by_hash('device_id', 2));
SELECT add_dimension('conditions', by_hash('device_id', 2), if_not_exists => true);

复制

要创建 _timescaledb_internal.dimension_info 实例，您需要调用 add_dimension 到现有超表。

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

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

复制

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

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

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

创建按范围的维度构建器。您可以单独使用 by_range 进行分区。

示例

• 使用 CREATE TABLE 按时间分区

  最简单的用法是按时间列分区

  CREATE TABLE conditions (
     time        TIMESTAMPTZ       NOT NULL,
     location    TEXT              NOT NULL,
     device      TEXT              NOT NULL,
     temperature DOUBLE PRECISION  NULL,
     humidity    DOUBLE PRECISION  NULL
  ) WITH (
     tsdb.hypertable,
     tsdb.partition_column='time'
  );

  复制

  如果您自托管 TimescaleDB v2.19.3 及以下版本，请创建一个 PostgreSQL 关系表，然后使用 create_hypertable 进行转换。之后通过调用 ALTER TABLE 启用 hypercore。

  这是默认分区，您无需明确添加。

• 使用 create_hypertable 从非时间列中提取时间

  如果您的表中包含一个非时间列（如 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 不会从非常大量的哈希分区中受益，例如您在分区字段中预期的唯一项数量。非常大量的哈希分区会导致每个分区的负载平衡不佳（将项映射到分区的哈希），以及某些类型查询的规划延迟大大增加。

示例

CREATE TABLE conditions (
   "time"      TIMESTAMPTZ       NOT NULL,
   location    TEXT              NOT NULL,
   device      TEXT              NOT NULL,
   temperature DOUBLE PRECISION  NULL,
   humidity    DOUBLE PRECISION  NULL
) WITH (
   tsdb.hypertable,
   tsdb.partition_column='time',
   tsdb.chunk_interval='1 day'
);

SELECT add_dimension('conditions', by_hash('location', 2));

复制

参数

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