增量物化视图

创建 DIMV 和 mlog

使用CREATE MATERIALIZED VIEW ... REFRESH FAST ON DEMAND ... WITH NO DATA创建DIMV时，系统会为涉及的基表自动创建mlog，并加入查询所需的列。推荐始终使用WITH NO DATA，由系统自动创建和补全mlog。

CREATE MATERIALIZED VIEW dimv_name
REFRESH FAST ON DEMAND
AS query
WITH NO DATA;

每张基表只需要一个mlog，多个DIMV可以共享。如果已有mlog缺少新DIMV依赖的列，使用WITH NO DATA创建新DIMV时系统会自动补全。如果不使用WITH NO DATA，则需要提前创建mlog，否则创建DIMV会失败。

首次全量刷新建立基线

使用WITH NO DATA创建DIMV后，DIMV上没有数据，且尚未建立“增量刷新基线”（即尚未记录一个可信的起点事务ID）。此时如果直接调用polar_matview.incremental_refresh_mv()做增量刷新，会报错：

ERROR:  No refresh snapshot found for incremental materialized view mv_name
ERROR:  materialized view "mv_name" has not been populated
HINT:  Use the REFRESH MATERIALIZED VIEW command.

正确的启动流程是：先执行一次全量REFRESH MATERIALIZED VIEW建立增量基线，之后就可以正常调用polar_matview.incremental_refresh_mv()做按需增量刷新。

-- 1. 建基表并写入初始数据
CREATE TABLE t_dimv(id INT PRIMARY KEY, cat TEXT, amount NUMERIC);
INSERT INTO t_dimv VALUES(1,'a',10),(2,'a',20),(3,'b',30);

-- 2. 用 WITH NO DATA 创建 DIMV(系统自动为 t_dimv 创建 mlog)
CREATE MATERIALIZED VIEW mv_dimv
REFRESH FAST ON DEMAND
AS SELECT cat, SUM(amount) FROM t_dimv GROUP BY cat
WITH NO DATA;

-- 3. 首次全量刷新,建立增量基线
REFRESH MATERIALIZED VIEW mv_dimv;

SELECT * FROM mv_dimv ORDER BY cat;
-- 输出:
-- cat | sum
-- ----+-----
-- a   |  30
-- b   |  30

-- 4. 追加变更数据到基表
INSERT INTO t_dimv VALUES(4,'b',40),(5,'a',50);

-- 5. 按需增量刷新(仅应用增量数据,不重算全表)
SELECT polar_matview.incremental_refresh_mv('mv_dimv'::regclass::oid);
-- 返回 t 表示增量刷新成功

SELECT * FROM mv_dimv ORDER BY cat;
-- 输出:
-- cat | sum
-- ----+-----
-- a   |  80
-- b   |  70

配置自动刷新与清理

DIMV 默认不会自动刷新。通过pg_cron扩展在数据库启动后拉起若干个长期运行的DIMV worker，再为需要自动刷新的DIMV配置刷新间隔，worker即可在后台自动完成增量刷新和mlog清理。

-- 1. 安装 pg_cron 扩展(如尚未安装)
CREATE EXTENSION IF NOT EXISTS pg_cron;

-- 2. 通过 pg_cron 在集群启动时后台拉起 DIMV 刷新 worker
-- 每个 cron.schedule 对应一个 worker,worker 数量按业务刷新压力配置
SELECT cron.schedule(
    'dimv-auto-refresh-worker-1',
    '@restart',
    $$CALL polar_matview.auto_refresh_worker_main()$$
);

SELECT cron.schedule(
    'dimv-auto-refresh-worker-2',
    '@restart',
    $$CALL polar_matview.auto_refresh_worker_main()$$
);

-- 建一个专用角色,并将两项超时参数置 0
CREATE ROLE dimv_worker LOGIN;
ALTER ROLE dimv_worker SET statement_timeout = 0;
ALTER ROLE dimv_worker SET polar_transaction_timeout = 0;

-- 用该角色调度 worker(通过 pg_cron 后台运行)
SELECT cron.schedule_in_database(
    'dimv-auto-refresh-worker-1',
    '@restart',
    $$CALL polar_matview.auto_refresh_worker_main()$$,
    'postgres',       -- 目标数据库
    'dimv_worker'     -- 以该专用角色执行
);

-- 设置某 DIMV 的自动刷新间隔为 1 秒
SELECT polar_matview.set_refresh_interval('dimv_name'::regclass::oid, '1 seconds'::interval);

-- 关闭某 DIMV 的自动刷新
SELECT polar_matview.reset_refresh_interval('dimv_name'::regclass::oid);

完整示例

下面是一个从安装扩展到配置自动刷新的端到端示例，覆盖 DIMV 常规使用的全流程。

-- 1. 安装扩展
CREATE EXTENSION IF NOT EXISTS polar_ivm;
CREATE EXTENSION IF NOT EXISTS pg_cron;

-- 2. 启动后台 worker(数据库重启后自动拉起)
SELECT cron.schedule(
    'dimv-auto-refresh-worker-1',
    '@restart',
    $$CALL polar_matview.auto_refresh_worker_main()$$
);

-- 3. 创建基表并写入初始数据
CREATE TABLE products (
    product_id  INT PRIMARY KEY,
    name        TEXT,
    category    TEXT,
    price       NUMERIC
);

CREATE TABLE order_items (
    item_id     BIGSERIAL PRIMARY KEY,
    product_id  INT,
    order_date  DATE,
    quantity    INT
);

INSERT INTO products VALUES
    (1, 'Widget A',  'Electronics', 100),
    (2, 'Widget B',  'Electronics', 150),
    (3, 'Gadget C',  'Home',         80);

INSERT INTO order_items (product_id, order_date, quantity) VALUES
    (1, '2024-01-01', 10),
    (2, '2024-01-02',  5),
    (1, '2024-01-03',  8);

-- 4. 使用 WITH NO DATA 创建 DIMV,系统自动创建并补全 mlog
CREATE MATERIALIZED VIEW mv_product_sales
REFRESH FAST ON DEMAND
AS
SELECT p.product_id,
       p.category,
       SUM(oi.quantity) AS total_qty,
       COUNT(*)         AS order_count,
       MAX(oi.order_date) AS latest_order
FROM products p
JOIN order_items oi ON p.product_id = oi.product_id
GROUP BY p.product_id, p.category
WITH NO DATA;

-- 5. 首次全量刷新,建立增量刷新基线
REFRESH MATERIALIZED VIEW mv_product_sales;

-- 6. 配置每秒自动刷新;mlog 的自动清理间隔由系统一并维护
SELECT polar_matview.set_refresh_interval(
    'mv_product_sales'::regclass::oid,
    '1 second'::interval
);

-- 7. 后续基表的变更由后台 worker 自动增量刷新到物化视图,并自动清理 mlog
INSERT INTO order_items (product_id, order_date, quantity) VALUES (3, '2024-01-04', 20);
UPDATE order_items SET quantity = quantity + 1 WHERE item_id = 1;
DELETE FROM order_items WHERE item_id = 2;

-- 等待一个刷新周期后查询,即可看到最新结果
SELECT * FROM mv_product_sales ORDER BY product_id;

手动创建与调整 mlog

推荐使用WITH NO DATA创建 DIMV 并让系统自动管理 mlog。如果需要在创建 DIMV 前手动创建 mlog，或者需要为已存在的 mlog 增加/删除列，可使用polar_ivmschema 提供的以下函数。

SELECT polar_ivm.create_matview_log('base_table'::regclass);

-- 为 mlog 补列
SELECT polar_ivm.matview_log_add_column('base_table'::regclass, 'new_col');

-- 从 mlog 删列
SELECT polar_ivm.matview_log_drop_column('base_table'::regclass, 'old_col');

SELECT polar_ivm.drop_matview_log('base_table'::regclass);

手动刷新

基表发生变更后，调用polar_matview.incremental_refresh_mv()执行按需增量刷新（参数为物化视图 OID）：

-- 基表 DML
INSERT INTO users VALUES (1, 'Alice');
UPDATE users SET name = 'Alice A.' WHERE userid = 1;
INSERT INTO sales VALUES (100, 1, '2023-01-01', 500);

-- 增量刷新依赖这两张基表的 DIMV
SELECT polar_matview.incremental_refresh_mv('mv_sales_summary'::regclass::oid);

增量刷新有以下事务约束：

• 必须在READ COMMITTED隔离级别下执行。

• 最小约束单位是事务。同一事务中，如果某个基表已经执行了会写入 mlog 的 DML，则不能再刷新依赖该表的 DIMV，反过来也一样。

• 该限制按基表判断。修改无关表或刷新不依赖该基表的 DIMV 不受影响。

• 可以多次刷新同一个或不同 DIMV，也可以多次修改同一基表。

也可以执行全量刷新。全量刷新会更新增量刷新基线，之后的增量刷新从新基线开始计算：

REFRESH MATERIALIZED VIEW mv_sales_summary;

手动清理

通过polar_matview.matview_log_purge()手动清理指定基表的 mlog：

SELECT polar_matview.matview_log_purge('base_table'::regclass);

DIMV 刷新统计

通过监控视图polar_matview_monitor.dimv_stat_refresh查看DIMV刷新执行情况：

SELECT * FROM polar_matview_monitor.dimv_stat_refresh;

各字段含义如下：

mlog 清理统计

通过监控视图polar_matview_monitor.mlog_stat_purge查看mlog清理执行情况：

SELECT * FROM polar_matview_monitor.mlog_stat_purge;

各字段含义如下：

mlog 失效与恢复

当满足以下任一条件时，mlog会被标记为失效，依赖它的DIMV在增量刷新（polar_matview.incremental_refresh_mv()）时会收到警告并返回false：

• mlog的事务ID跨度超过polar_mlog_xid_max_limit（默认20亿）。事务ID接近回卷时，日志记录的新旧顺序无法可靠判断。

• 距上次清理的时间超过polar_mlog_purge_max_interval（默认18000秒）。长时间未清理时，timestamp维度的兜底判断也无法继续保证日志可识别。

正常情况下不会触发这两个条件。只要mlog被worker持续清理，其事务ID跨度就会随清理不断收窄，不会逼近20亿。因此这两个条件实际上只是一道兜底保护：通常只有在放弃自动清理、改用手动purge，且长时间疏于清理（这段时间内消费的事务ID已超过20亿）的情况下才可能被触发。

可通过监控视图polar_matview_monitor.mlog_stat_purge的valid、age、valid_lifecycle字段检测mlog状态。

恢复方式是清空并重新验证mlog，再对依赖它的DIMV重建基线：

SELECT polar_ivm.matview_log_truncate_and_validate('base_table_name'::regclass);

DIMV 失效与恢复

DIMV失效指物化视图本身变为不可增量刷新（元数据polar_ivm.imatview_metadata.is_incrementally_updatable置为false），主要由以下操作触发：

• 对基表执行TRUNCATE：会使依赖该基表且已填充数据的DIMV全部失效。

• 对作为其他DIMV基表的嵌套DIMV执行非并发的全量REFRESH MATERIALIZED VIEW：会重置其mlog并级联使下游DIMV失效。

• 基表mlog被重置（如上文polar_ivm.matview_log_truncate_and_validate()）：级联使依赖该基表的DIMV失效。

其他会破坏增量基线的不兼容DDL（如删除、修改被依赖的列）默认会被直接阻止，而非使DIMV静默失效，具体请参见基表 DDL 操作的影响。

支持的聚合函数

除常见聚合（SUM、AVG、COUNT、MIN、MAX）外，DIMV 还支持以下聚合：

• 字符串/数组聚合：string_agg、array_agg。

• 有序集聚合：如percentile_disc、percentile_cont等。

• 您自定义聚合：您通过CREATE AGGREGATE定义的聚合函数。

示例：使用string_agg和array_agg：

CREATE MATERIALIZED VIEW mv_agg
REFRESH FAST ON DEMAND
AS
SELECT cat,
       string_agg(name, ',') AS names,
       array_agg(id ORDER BY id) AS ids
FROM t_dimv
GROUP BY cat
WITH NO DATA;

任意聚合的限制

• 必须带GROUP BY，不支持没有GROUP BY的全表任意聚合。

• 支持NULL分组键和多列分组键。

• 发生变更的group会整体重算，刷新复杂度约为O(delta group)。

• 常见聚合可按基表变化粒度刷新，通常比任意聚合路径轻量。

窗口函数的限制

PolarDB PostgreSQL版当前支持的窗口函数包括ROW_NUMBER()、RANK()、DENSE_RANK()、LEAD()、LAG()、FIRST_VALUE()、LAST_VALUE()、NTH_VALUE()和窗口聚合。限制如下：

• 每个窗口函数都必须指定PARTITION BY，不支持全表窗口。

• 多个窗口函数的PARTITION BY key必须形成兼容的子集链。

• PARTITION BY可以使用列或不可变函数表达式。

• 窗口函数不能与GROUP BY或聚合函数组合。

• 窗口函数不能与外连接或EXISTS子链接组合。

• 窗口函数不能位于子查询中。