大网数据广告活动
数据库部署与 SQL 参考

数据变更与增量消费概述

· 52CE 我爱测

从 5.0 版本开始,Doris 可以为内表记录行级变更日志(Changelog),并在此基础上提供两种读取变更的方式:

从 5.0 版本开始,Doris 可以为内表记录行级变更日志(Changelog),并在此基础上提供两种读取变更的方式:

  • Table Stream:一个有名字的消费对象,替你记住"消费到哪了",每次读取只返回上次消费之后的变化,读取和写入目标表在同一个事务里完成。
  • 增量查询(@incr):不建对象,直接指定时间窗口读取某张表在这段时间内的变化。

异步物化视图还可以使用上层能力 物化视图增量维护(IVM)。IVM 由 Doris 自动管理内部 Table Stream,根据行级变化维护物化视图。需要维护物化视图时,直接使用 IVM,不需要自行创建和消费 Stream。

该功能自 5.0.0 版本起提供,目前处于实验阶段,默认关闭。开启方式见本文 前置条件。

解决什么问题

在 Doris 内部做增量处理时,用户通常会遇到这些问题:

问题 没有变更记录时 有了 Changelog 之后
下游只想拿增量,拿不到 上游表每天有大量更新和删除,下游报表、宽表、聚合表只能定期全量重算,或者依赖业务方在数据里维护 update_time 字段 Table Stream 只返回两次消费之间的变化,下游按变化增量处理
更新和删除不可见 Unique Key 表的更新会直接覆盖旧值,删除的数据也会消失,事后无法知道"改了什么、删了什么" 每一行的新增、更新(含更新前后的值)、删除都被记录下来
多张表的增量口径对不齐 用增量数据关联维表时,维表是"现在"的状态,增量是"过去一段时间"的状态,两者口径不一致 用 <stream>@snapshot() 读取与消费位点对齐的维表镜像

Changelog 把每一行的新增、更新(含更新前后的值)、删除都记录下来,并带上全局单调递增的提交时间戳;Table Stream 和增量查询则以不同的方式读取这些记录。

两层能力

[图示请参阅官方原文]

能力 是否需要建对象 谁来记录读到哪 适合
Table Stream 需要 CREATE STREAM Doris 按分区维护消费位点 持续的增量 ETL、下游同步、消费必须不重不漏
增量查询 @incr 不需要 用户自己指定时间窗口 临时分析、外部调度系统自己管理位点

IVM 位于这两层能力之上。它使用 Changelog 记录的变化和 Doris 自动创建的内部 Table Stream,但用户入口仍是 CREATE MATERIALIZED VIEW 和 REFRESH MATERIALIZED VIEW。

典型场景

[图示请参阅官方原文]

场景 推荐方式 做法 详见
增量同步到下游表 Table Stream,min_delta 类型 订单表每天有大量状态更新。创建一个 min_delta 类型的 Table Stream,定时执行 INSERT INTO 下游表 SELECT ... FROM 订单表的 stream,每次只处理两次执行之间的净变化:新增的订单、状态变化的订单(带变更前后的值)、被删除的订单。读取变更和写入下游在一个事务内完成,失败自动回滚、不会漏消费或重复消费 Table Stream 基础
只追加的日志、事件表 Table Stream,append_only 类型 对于只有新增没有更新的明细表,每次只拿新写入的行,开销最小 消费类型
变更审计与回放 Table Stream detail 类型,或 @incr 的 DETAIL 模式 需要保留每一次修改的完整轨迹时,按时间窗口或按消费位点逐条导出变更,落到审计表 增量查询
增量数据关联维表时的口径对齐 <stream>@snapshot() 消费订单增量时需要关联用户表。用 用户表的 stream@snapshot() 读取与消费位点对齐的用户表镜像,避免"新订单关联到了旧用户信息"或者反过来 快照读取

能力一览

表模型支持

表模型 Changelog before 镜像 可用的变更类型
Duplicate Key 支持 不支持 仅 APPEND
Unique Key(Merge-on-Write,无 cluster key) 支持 支持(changelog.need_historical_value = true) APPEND / UPDATE_BEFORE / UPDATE_AFTER / DELETE
Unique Key(Merge-on-Read) 不支持 - -
Aggregate Key 不支持 - -

其它限制(auto-increment 列、VARIANT 列、schema change 范围等)见 Changelog。

消费类型选型

你需要 选择 说明
只要新增的行 append_only 更新、删除不输出;开销最小
两次消费之间每个 key 的净变化 min_delta(默认) 同一 key 多次修改折叠成一条 UPDATE_BEFORE + UPDATE_AFTER;插入后又删除的 key 不输出
每一次修改的完整记录 detail 逐条输出,不折叠

min_delta 和 detail 中的 UPDATE_BEFORE / DELETE 需要 before 镜像,因此基表必须是 MoW 表且开启 changelog.need_historical_value。

前置条件

  1. 版本:Doris 5.0.0 及以上。

  2. FE 配置:在 fe.conf 中开启以下两项并重启 FE(两项均为非动态配置):

    enable_feature_changelog = true
    enable_table_stream = true
    

    enable_feature_changelog 控制 Changelog 与提交时间戳(TSO)的分配;enable_feature_binlog 只控制 CCR binlog,这里不需要开启。enable_table_stream 控制 Table Stream 的 DDL,未开启时,创建 Stream 会报 Table Stream is experimental. Please set enable_table_stream=true to enable it.。

  3. 建表时开启 Changelog:Changelog 只能在建表时开启,已有表无法通过 ALTER TABLE 开启,需要重建表并导入数据。

  4. 部署模式:Changelog 与 Table Stream 在存算一体、存算分离模式下均可使用;@incr 增量查询目前请在存算一体模式下使用,存算分离模式的支持仍在完善中。

开启 Changelog 后,每次写入需要额外生成并持久化变更记录,对 MoW 表还需要读取旧值,导入吞吐会有可感知的下降。建议只对确实需要增量消费的表开启,并在上线前用真实负载评估。

常见问题

问题 回答
已有的表能否开启 Changelog? 不能。Changelog 只能在建表时开启,需要新建一张开启 Changelog 的表并导入数据,见 Changelog
Table Stream 和 @incr 怎么选? 持续的增量 ETL、要求不重不漏,用 Table Stream;临时分析、回溯某段时间的变更、外部系统已有自己的位点管理,用 @incr,见 与 Table Stream 的区别
创建 Stream 报 Table Stream is experimental. Please set enable_table_stream=true to enable it. FE 未开启 enable_table_stream,修改 fe.conf 后重启 FE
存算分离模式能用吗? Changelog 与 Table Stream 可以;@incr 请在存算一体模式下使用
开启 Changelog 对写入有什么影响? 每次写入要额外生成并持久化变更记录,MoW 表还要读取旧值,导入吞吐会有可感知的下降。只对需要增量消费的表开启,上线前用真实负载评估
变更记录会自动清理吗? 会。changelog.ttl_seconds 控制保留时长(默认一天);增量读取过滤过期记录,后台 compaction 回收其存储空间。请在保留窗口内完成消费,见 保留与清理

文档导读

文档 内容
快速上手 10 分钟走通建表、建 Stream、写入、查看变更、消费的完整流程
Changelog 开启方式、属性、支持范围、变更记录模型、对 DDL 的约束、开销与排查
增量查询 @incr 时间窗口查询、三种增量模式
Table Stream 基础 创建与管理、三种消费类型、初始数据、查询与消费的区别、虚拟列
Table Stream 进阶 分区级位点、快照与重置、一致性关联、并发消费、基表变更的影响、监控与故障恢复
物化视图增量维护(IVM) 基于 Changelog 和内部 Table Stream 按行维护异步物化视图

本文来自 Apache Doris 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
Apache Doris 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。