企业官网建设流程全解析

StarRocks information_schema.materialized_views 系统表：物化视图全量状态与刷新元数据详解

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

materialized_views是 StarRocksinformation_schema库中一张描述集群内**所有物化视图（Materialized View）**的元数据系统表，覆盖同步物化视图（rollup）与异步物化视图（ASYNC）两类对象，是 DBA 与平台开发者做物化视图资产盘点、刷新任务排障、查询改写（Query Rewrite）状态审计的核心入口。本文以官方文档为骨架，结合 FE 侧源码（MaterializedViewsSystemTable.java、ShowMaterializedViewStatus.java 等）逐字段讲解其含义、取值与底层生成逻辑，帮助你熟练用一条 SQL 掌握全部物化视图的健康度与刷新历史。

一、表是什么：一张表、两类物化视图、三种关键状态

从源码看，materialized_views是一张由 FE 端驱动的 Schema 系统表（SystemTable），通过 thrift 接口SCH_MATERIALIZED_VIEWS对外暴露。查询时 FE 会遍历本地元数据（LocalMetastore）中的数据库与表，并按对象类型分两条路径收集状态：

• 异步物化视图（表类型为MATERIALIZED_VIEW）：读取MaterializedView对象的刷新方案、活动状态、查询改写校验结果，并结合调度器（TaskManager）的历史任务运行记录（TaskRunStatus）汇总出最近一次刷新任务的完整信息；
• 同步物化视图（表类型为OLAP表上的MaterializedIndexMeta）：仅填充少量字段（见下文“同步物化视图”小节）。

因此这张表天然适合回答三类问题：

1. 有哪些物化视图、属于哪个库、由谁创建、定义 SQL 是什么（资产盘点）；
2. 最近一次刷新是否成功、耗时多久、刷了哪些分区、报了什么错（任务排障）；
3. 物化视图是否可用于查询改写、为什么不能改写（优化器诊断）。

二、完整字段清单与含义（官方文档全量继承）

下表完整列出materialized_views提供的全部字段。其中与刷新相关的字段仅在存在最近一次刷新任务记录时才有值，同步物化视图大多为空。

2.1 同步物化视图的特殊性

对于同步（rollup 型）物化视图，源码中通过ShowMaterializedViewStatus.of(dbName, olapTable, indexMeta)单独构造状态，关键字段固定取值：

• REFRESH_TYPE恒为SYNC，IS_ACTIVE恒为true；
• REFRESH_TRIGGER、REFRESH_POLICY均为NONE（对应文档“所有与激活状态和刷新相关的字段均为空”）；
• WAREHOUSE、REFRESH_MODE为空，RESOURCE_GROUP固定为默认资源组；
• 分区字段与刷新任务相关字段不适用。

实现见 ShowMaterializedViewStatus.java。

三、基本查询：全量与按库/按名过滤

materialized_views位于information_schema库，可通过标准的SELECT查询，并支持在TABLE_SCHEMA、TABLE_NAME列上使用等值过滤条件下推给 FE 求值（源码中SUPPORTED_EQUAL_COLUMNS仅包含这两列，见 MaterializedViewsSystemTable.java），从而避免全量扫描、提升大集群下的查询效率。

-- 1. 查看集群内所有物化视图的基本信息 SELECT TABLE_SCHEMA, TABLE_NAME, REFRESH_TYPE, IS_ACTIVE, PARTITION_TYPE, TABLE_ROWS FROM information_schema.materialized_views; -- 2. 查看某个数据库中所有物化视图的刷新策略 SELECT TABLE_NAME, REFRESH_TYPE, REFRESH_TRIGGER, REFRESH_POLICY, REFRESH_MODE, WAREHOUSE, RESOURCE_GROUP FROM information_schema.materialized_views WHERE TABLE_SCHEMA = 'dwd'; -- 3. 按物化视图名精确过滤 SELECT * FROM information_schema.materialized_views WHERE TABLE_SCHEMA = 'dwd' AND TABLE_NAME = 'mv_order_daily';

四、刷新诊断：最近一次刷新任务的完整画像

刷新相关字段是这张表最有排障价值的部分，它们由 FE 将同一刷新 Job 下的一次或多次任务运行（TaskRunStatus）按创建时间排序后聚合而成（ShowMaterializedViewStatus.fromTaskRuns）。典型用法：

-- 找出最近一次刷新失败或尚未完成的物化视图 SELECT TABLE_SCHEMA, TABLE_NAME, TASK_ID, TASK_NAME, LAST_REFRESH_START_TIME, LAST_REFRESH_FINISHED_TIME, LAST_REFRESH_DURATION, LAST_REFRESH_STATE, LAST_REFRESH_ERROR_CODE, LAST_REFRESH_ERROR_MESSAGE FROM information_schema.materialized_views WHERE REFRESH_TYPE = 'ASYNC' AND LAST_REFRESH_STATE NOT IN ('SUCCESS', 'MERGED');

4.1 几个需要区分的“时间”字段

• LAST_REFRESH_START_TIME：Job 中首次任务运行的创建时间；
• LAST_REFRESH_PROCESS_TIME：Job 中首次任务运行的处理开始时间（真正进入执行阶段的时刻）；
• LAST_REFRESH_FINISHED_TIME：Job 中末次任务运行的完成时间（仅在整次刷新结束时填充）；
• LAST_REFRESH_DURATION：末次运行完成时间减去首次运行处理开始时间的墙钟秒数（当处理开始时间未知时回退到提交时间，并对时钟偏差做非负钳制），由getRefreshJobWallClockDurationMs计算，与materialized_view_refresh_jobs.DURATION_TIME严格一致（源码注释明确二者共享同一口径，见 ShowMaterializedViewStatus.java）；
• LAST_REFRESH_TIME：物化视图所反映的基础表数据版本时间（新鲜度判断基准），与墙钟时间无关；
• LAST_FRESHNESS_CONFIRMED_AT：最近一次成功刷新（全部任务运行完成）的墙钟开始时间，用于确认“物化视图反映的是这一时刻之前的基础表数据”。

4.2 分区级刷新的痕迹

当异步物化视图按分区刷新时，LAST_REFRESH_START_PARTITION与LAST_REFRESH_END_PARTITION记录本次刷新的分区范围，LAST_REFRESH_BASE_REFRESH_PARTITIONS与LAST_REFRESH_MV_REFRESH_PARTITIONS则分别记录基础表侧与物化视图侧实际参与/被刷新的分区。一次刷新产生多次任务运行时，这些多值字段在 thrift 侧以|（MULTI_TASK_RUN_SEPARATOR）连接。配合REFRESH_MODE（PCT或INCREMENTAL）即可确认分区变更追踪是否按预期只刷新了增量分区。

4.3 强制刷新与错误码

LAST_REFRESH_FORCE_REFRESH标记最近一次刷新是否为REFRESH MATERIALIZED VIEW ... FORCE式强制刷新；LAST_REFRESH_ERROR_CODE与LAST_REFRESH_ERROR_MESSAGE仅在刷新结束后填充，前者是最后一次任务运行的错误码，后者是对应的错误信息。若刷新为挂起（PENDING）状态且被清理机制标记失败，源码会回退取批次内各子运行完成时间的最大值，避免已完成的子任务耗时被丢失（见 ShowMaterializedViewStatus.java）。

五、查询改写状态：从 QUERY_REWRITE_STATUS 到原因

物化视图的核心价值之一是透明改写加速查询。QUERY_REWRITE_STATUS与QUERY_REWRITE_STATUS_REASON由 FE 对物化视图定义查询计划（Query Plan）做校验后得出，二者共享同一次校验结果（源码中特意“只计算一次”，避免状态与原因出现不一致，见 ShowMaterializedViewStatus.java）。对应枚举定义在 MVPlanValidationResult.java：

结合IS_ACTIVE与INACTIVE_REASON，可以定位“物化视图建好了却不生效”的问题：

-- 找出所有当前不可用（无法刷新/查询/改写）的物化视图 SELECT TABLE_SCHEMA, TABLE_NAME, IS_ACTIVE, INACTIVE_REASON, QUERY_REWRITE_STATUS, QUERY_REWRITE_STATUS_REASON FROM information_schema.materialized_views WHERE IS_ACTIVE = 'false' OR QUERY_REWRITE_STATUS_REASON <> 'OK';

需要注意的是，IS_ACTIVE = false的对象无法被刷新或查询，这通常是定义依赖的表被删除、表结构变更或刷新连续失败等场景导致；QUERY_REWRITE_DISABLED则属于“配置层面关闭”而非对象损坏。

六、刷新策略的底层生成逻辑

REFRESH_TRIGGER与REFRESH_POLICY并非独立存储，而是由 FE 依据物化视图的刷新方案（MvRefreshScheme）与异步刷新上下文（AsyncRefreshContext）动态推导，实现在 MaterializedView.java：

• 刷新方案类型为SYNC→ 两者均为NONE；
• 类型为MANUAL→ 两者均为MANUAL（只接受REFRESH MATERIALIZED VIEW手动触发）；
• 类型为ASYNC且未定义时间步长与时间单位（step == 0 && timeUnit == null）→ 两者均为ON_BASE_TABLE_CHANGE（基础表数据加载/变更时自动触发，对应isLoadTriggeredRefresh()判定）；
• 其余异步场景 →REFRESH_TRIGGER为SCHEDULED，REFRESH_POLICY为人类可读的调度表达式，例如：

START("2025-01-01 00:00:00") EVERY(INTERVAL 1 HOUR)

其中START(...)子句仅在创建时定义了开始时间时出现，EVERY(INTERVAL n unit)直接来自异步刷新上下文中配置的步长与时间单位。因此用下面这条 SQL 就能一眼看出每个异步物化视图的自动刷新节奏：

SELECT TABLE_SCHEMA, TABLE_NAME, REFRESH_TRIGGER, REFRESH_POLICY FROM information_schema.materialized_views WHERE REFRESH_TYPE = 'ASYNC';

RESOURCE_GROUP字段同理，来自物化视图的resource_group表属性，未显式配置时回填默认资源组名default_mv_wg（见 MaterializedView.java）。WAREHOUSE仅在共享数据（shared-data）模式下、且物化视图配置了 Warehouse 时返回非空值。

七、与 SHOW MATERIALIZED VIEWS、materialized_view_refresh_jobs 的关系

information_schema.materialized_views与SHOW MATERIALIZED VIEWS命令共享同一套状态生成逻辑（ShowMaterializedViewStatus），二者字段顺序与口径一致；区别在于系统表可以用标准 SQL 做过滤、投影与关联，更适合被监控平台与自动化脚本消费。

此外，表中有两个字段与 materialized_view_refresh_jobs 系统表存在明确的对应关系：

• LAST_REFRESH_DURATION↔materialized_view_refresh_jobs.DURATION_TIME：同一刷新任务的耗时，口径完全一致，可用作两表交叉验证；
• LAST_REFRESH_JOB_ID↔materialized_view_refresh_jobs.JOB_ID：Job 级维度（StartTaskRunId），可按MATERIALIZED_VIEW_ID关联查询。

若要查看一个物化视图的多轮历史刷新记录（而非仅最近一次），应查询materialized_view_refresh_jobs；materialized_views只保留最近一次刷新的聚合结果。EXTRA_MESSAGE 字段则以 JSON 形式携带最近一次刷新的补充信息（如queryIds、是否手动触发isManual、是否同步执行isSync、任务优先级priority、末次任务运行状态lastTaskRunState等），可用于还原一次刷新的执行上下文。

八、典型实践：一条 SQL 完成物化视图健康巡检

将以上字段组合起来，即可构建一条物化视图健康巡检 SQL：

SELECT TABLE_SCHEMA, TABLE_NAME, REFRESH_TYPE, IS_ACTIVE, INACTIVE_REASON, QUERY_REWRITE_STATUS, QUERY_REWRITE_STATUS_REASON, LAST_REFRESH_STATE, LAST_REFRESH_FINISHED_TIME, ROUND(LAST_REFRESH_DURATION, 2) AS last_duration_sec, LAST_REFRESH_ERROR_MESSAGE FROM information_schema.materialized_views ORDER BY TABLE_SCHEMA, TABLE_NAME;

按输出逐项核对即可完成巡检：

1. 所有异步物化视图的IS_ACTIVE是否为true，INACTIVE_REASON是否有告警性内容；
2. QUERY_REWRITE_STATUS_REASON是否全部为OK，非OK项决定改写是否可用；
3. LAST_REFRESH_STATE是否为成功状态，失败项的LAST_REFRESH_ERROR_CODE/LAST_REFRESH_ERROR_MESSAGE指向具体原因；
4. REFRESH_TRIGGER/REFRESH_POLICY是否符合预期的自动刷新节奏，是否存在应配置自动刷新却仍为MANUAL的对象；
5. LAST_REFRESH_DURATION是否有异常长耗时，用于后续调优刷新窗口。

九、小结

information_schema.materialized_views是 StarRocks 物化视图运维中信息密度最高的一张系统表：35 个字段完整覆盖了对象身份、激活状态、分区策略、刷新任务画像、刷新策略推导、查询改写校验与新鲜度确认等维度。理解其字段语义与 FE 侧生成逻辑（同步/异步双路径收集、多任务运行聚合、改写状态单一校验来源），即可用它搭建可落地的物化视图资产盘点、刷新排障与改写可用性监控体系。更深入的历史任务分析，可结合materialized_view_refresh_jobs系统表与SHOW MATERIALIZED VIEWS命令交叉使用。

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks