citus_columnar

Citus 列式存储引擎
仓库
citusdata/citus
https://github.com/citusdata/citus
源码
citus-14.0.0.tar.gz
citus-14.0.0.tar.gz

概览

扩展包名版本分类许可证语言
citus14.0.0OLAPAGPL-3.0C
ID扩展名BinLibLoadCreateTrustReloc模式
2400citus否是是是否否pg_catalog
2401citus_columnar否是否是否否pg_catalog
相关扩展columnar pg_parquet timescaledb pg_analytics pg_mooncake pg_duckdb duckdb_fdw orioledb

conflict with hydra columnar, no pg18

版本

类型仓库版本PG 大版本包名依赖
EXTPIGSTY14.0.01817161514citus-
RPMPIGSTY14.0.01817161514citus_$v-
DEBPIGSTY14.0.01817161514postgresql-$v-citus-
OS / PGPG18PG17PG16PG15PG14
el8.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
el8.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
el9.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
el9.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
el10.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY MISS
el10.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY MISS
d12.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
d12.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
d13.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY MISS
d13.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY MISS
u22.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
u22.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
u24.x86_64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0
u24.aarch64PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 14.0.0PIGSTY 13.2.0PIGSTY 13.0.0

构建

您可以使用 pig build 命令构建 citus 扩展的 RPM / DEB 包：

pig build pkg citus         # 构建 RPM / DEB 包

安装

您可以直接安装 citus 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install citus;          # 当前活跃 PG 版本安装

pig ext install -y citus -v 18  # PG 18
pig ext install -y citus -v 17  # PG 17
pig ext install -y citus -v 16  # PG 16

dnf install -y citus_18       # PG 18
dnf install -y citus_17       # PG 17
dnf install -y citus_16       # PG 16

apt install -y postgresql-18-citus   # PG 18
apt install -y postgresql-17-citus   # PG 17
apt install -y postgresql-16-citus   # PG 16

创建扩展：

CREATE EXTENSION citus_columnar;

用法

citus_columnar: PostgreSQL 的列式存储访问方法

Citus Columnar 为 PostgreSQL 提供列式存储引擎。它以列式格式存储数据并自动压缩，非常适合在仅追加数据上执行分析工作负载，这类查询通常只读取部分列。

核心文档：

创建列式表

创建表时使用 USING columnar 子句：

CREATE TABLE events (
    event_id    BIGINT,
    event_time  TIMESTAMPTZ,
    event_type  TEXT,
    user_id     INT,
    payload     JSONB
) USING columnar;

压缩选项

可按表配置压缩方式。支持的方法：zstd（默认）、lz4、pglz、none。

ALTER TABLE events SET (
    columnar.compression = zstd,
    columnar.compression_level = 3
);

块组和条带设置

列式存储将数据组织为条带（stripe），每个条带包含多个块组（chunk group）。调整这些参数会影响压缩率和查询性能。

ALTER TABLE events SET (
    columnar.stripe_row_limit = 150000,    -- 每个条带的最大行数（默认 150000）
    columnar.chunk_group_row_limit = 10000 -- 每个块组的行数（默认 10000）
);

适用场景

列式存储最适合以下场景：

  • 分析和报表：查询只读取宽表中的少数列
  • 仅追加工作负载（如日志、事件、时序归档）
  • 大型事实表：需要批量扫描和聚合
  • 冷数据归档：高压缩率非常有价值

限制

  • 不支持 UPDATE 或 DELETE：列式表仅支持追加
  • 不支持索引：仅支持顺序/列式扫描
  • 不支持 TOAST：大值内联存储
  • 不支持作为发布端的逻辑复制
  • 不支持 tid 扫描

列投影和块组跳过

列式存储自动仅读取查询中引用的列（列投影），并跳过 min/max 元数据与查询条件不匹配的块组：

-- 仅读取 event_type 和 event_time 列；跳过不相关的块组
SELECT event_type, count(*)
FROM events
WHERE event_time > '2025-01-01'
GROUP BY event_type;

监控列式存储

查看条带和块组的元数据：

-- 查看列式表的条带信息
SELECT * FROM columnar.stripe WHERE relation = 'events'::regclass;

-- 查看块组详情
SELECT * FROM columnar.chunk_group WHERE relation = 'events'::regclass;

-- 检查存储大小和压缩率
SELECT pg_size_pretty(pg_total_relation_size('events')) AS total_size;

堆表和列式表之间的转换

将现有堆表转换为列式表：

-- 创建列式副本
CREATE TABLE events_columnar (LIKE events) USING columnar;
INSERT INTO events_columnar SELECT * FROM events;

-- 或使用 ALTER TABLE（Citus 11+）
SELECT alter_table_set_access_method('events', 'columnar');

将列式表转换回堆表：

SELECT alter_table_set_access_method('events', 'heap');

与分区结合使用

将列式存储与分区结合，保持近期数据在堆表中（支持更新/索引），将较旧的分区归档为列式存储：

CREATE TABLE events (
    event_time TIMESTAMPTZ,
    data       JSONB
) PARTITION BY RANGE (event_time);

-- 近期数据：堆表（支持索引和更新）
CREATE TABLE events_current PARTITION OF events
    FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

-- 归档数据：列式表（压缩存储，读取优化）
CREATE TABLE events_archive PARTITION OF events
    FOR VALUES FROM ('2024-01-01') TO ('2025-01-01')
    USING columnar;

最后修改 2026-03-14: update extension metadata (953cbd0)