实时物化视图 MCP 使用指南

监控诊断（只读）

元数据查询（只读）

IMV 生命周期（写操作）

DDL 相关操作（写操作）

创建一个 IMV

用户指令：给出建视图的 SQL 和目标 IMV 名称

Agent 会自动调用一系列创建相关 Tool，不仅可完成创建，也可以主动完成对分布键等配置的通用优化。

┌─ 用户 ───────────────────────────────────────────────
│ 帮我创建一个 IMV，名字叫 imv_order_summary，SQL 如下：
│
│ SELECT
│   o.order_id,
│   o.customer_id,
│   o.order_date,
│   SUM(l.quantity * l.price) AS total_amount
│ FROM orders o
│ JOIN lineitem l ON o.order_id = l.order_id
│ GROUP BY o.order_id, o.customer_id, o.order_date
└──────────────────────────────────────────────────────

┌─ Agent ──────────────────────────────────────────────
│ 我来为您创建这个 IMV。首先初始化 DDL 环境，然后创建视图。
│
│ ⚙ 调用工具: imv_init_ddl
│ ✓ DDL 环境已就绪。
│
│ ⚙ 调用工具: imv_create
│   参数: name=imv_order_summary, sql=SELECT o.order_id, ...
│ ✓ 创建任务已下发，正在等待就绪...
│
│ ⚙ 调用工具: imv_is_ready
│   参数: name=imv_order_summary
│ ✓ IMV 已就绪，可正常查询。
│
│ ⚙ 调用工具: imv_optimize
│   参数: name=imv_order_summary
│ → 建议将分布键从默认随机分布调整为 (order_id)，可提升增量
│   维护的 JOIN 本地性。
│
│  调用工具: adbpg_relation_alter_distributed
│   参数: name=imv_order_summary, distributed_by=order_id
│ ✓ 分布键已调整为 (order_id)。
│
│ 总结：IMV imv_order_summary 已成功创建并完成分布键优化。
└──────────────────────────────────────────────────────

查看当前库中有哪些 IMV

用户指令：列出当前库中所有的 IMV

Agent 会自动解析您的意图，调用 imv_list_all 工具，按创建时间倒序返回当前绑定数据库中的全部 IMV 名称。

┌─ 用户 ───────────────────────────────────────────────
│ 列出当前库中所有的 IMV
──────────────────────────────────────────────────────

┌─ Agent ──────────────────────────────────────────────
│ ⚙ 调用工具: imv_list_all
│
│ 当前数据库共有 4 个 IMV（按创建时间倒序）：
│
│  #   名称                        创建时间
│  1   imv_order_summary           2025-06-15 14:30:00
│  2   imv_daily_revenue           2025-05-20 09:15:00
│  3   imv_customer_stats          2025-04-10 16:45:00
│  4   imv_product_inventory       2025-03-01 11:00:00
──────────────────────────────────────────────────────

查看单个 IMV 的运行状态

用户指令：看一下 imv_order_summary 这个视图多大、最近什么时候刷新的、访问频率

Agent 会调用 imv_stat_single 工具，返回该 IMV 的总大小、估算行数、创建时间、最近全量刷新时间及访问扫描次数。

┌─ 用户 ───────────────────────────────────────────────
│ 看一下 imv_order_summary 这个视图多大、最近什么时候
│ 刷新的、访问频率怎么样
└──────────────────────────────────────────────────────

┌─ Agent ──────────────────────────────────────────────
│ ⚙ 调用工具: imv_stat_single
│   参数: name=imv_order_summary
│
│ imv_order_summary 的运行状态如下：
│
│   总大小:           256 MB
│   估算行数:         1,820,000 行
│   存储引擎:         heap
│   创建时间:         2025-06-15 14:30:00
│   最近全量刷新:     2025-07-01 02:00:00
│   访问扫描次数:     3,472 次
│
│ 该视图体积适中，访问频率较高，增量维护正常运行中。
└──────────────────────────────────────────────────────

诊断 IMV 刷新报错

用户指令：为什么我的 IMV 最近不刷新了

Agent 会调用 imv_error_log 获取最近的增量维护报错记录，并结合 imv_incremental_stat 的计算/应用时长统计定位瓶颈，以下是一个脏数据导致类型转换报错、阻塞增量维护的常见例子。

┌─ 用户 ──────────────────────────────────────────────
│ 为什么我的 imv_daily_revenue 最近不刷新了？
└──────────────────────────────────────────────────────

┌─ Agent ──────────────────────────────────────────────
│ 我来查一下报错日志和维护统计。
│
│ ⚙ 调用工具: imv_error_log
│   参数: name=imv_daily_revenue
│
│ 发现最近的报错记录：
│
│   时间:   2025-07-10 03:15:22
│   错误:   ERROR: invalid input syntax for type numeric:
│           "N/A" (基表 sales, 列 amount)
│   影响:   增量维护管道自该时刻起阻塞
│
│ ⚙ 调用工具: imv_incremental_stat
│   参数: name=imv_daily_revenue
│
│   最近一次成功维护:  2025-07-10 03:00:05
│   当前积压 delta:    48,350 行
│
│ 原因分析：基表 sales 的 amount 列写入了非法值 "N/A"，
│ 导致增量维护在类型转换时报错并阻塞。建议修复脏数据后，
│ 使用 imv_refresh_self 全量刷新以恢复增量管道。
──────────────────────────────────────────────────────

检查 IMV 数据是否延迟并优化

用户指令：帮我看看（某个或所有）IMV 的数据有没有延迟

Agent 会调用 imv_latency 工具，返回各基表增量维护管道的延迟秒数和未消费的增量积压行数；对于探测到延迟的 IMV，Agent 会先通过 imv_dependency 展开整棵依赖树（含嵌套子 IMV），再对树上每个 IMV 调用 imv_optimize 做诊断。诊断会按视图体积自动分流：小体积视图（单 segment 数据量 < 1GB）Agent 可自主完成候选索引的精确评估并直接给出推荐，此场景下索引与分布键的落地调整（imv_alter_maintain_index / adbpg_relation_alter_distributed）可由 Agent 直接执行；大体积视图会列出候选方案、告知评估耗时并征求您确认后才执行评估，落地调整同样必须经您同意。

┌─ 用户 ───────────────────────────────────────────────
│ 帮我看看所有 IMV 的数据有没有延迟
└──────────────────────────────────────────────────────

┌─ Agent ──────────────────────────────────────────────
│ ⚙ 调用工具: imv_latency
│
│ 检测到以下 IMV 存在延迟：
│
│   IMV 名称              基表        延迟     积压行数
│   imv_customer_stats    customers   45s      12,300
│   imv_customer_stats    orders      128s     85,600
│
│ 其余 IMV 延迟均在正常范围内（< 5s）。
│
│ 我来对 imv_customer_stats 做进一步诊断。
│
│ ⚙ 调用工具: imv_dependency
│   参数: name=imv_customer_stats, depth=2
│ → 依赖树：
│   imv_customer_stats
│     ├── 基表: customers
│     ├── 基表: orders
│     └── 嵌套 IMV: imv_order_agg (子视图)
│           ── 基表: lineitem
│
│ ⚙ 调用工具: imv_optimize
│   参数: name=imv_customer_stats
│ → 该视图单 segment 数据量 420 MB（< 1GB），自动进行
│   精确评估...
│
│ 诊断结果：
│   当前增量维护索引为 (customer_id)，但增量 JOIN 关联键
│   为 (order_id)，导致每次维护全表扫描 orders 侧 delta。
│   建议：将增量维护索引改为 (order_id)，预计维护耗时降低
│   约 70%。
│
│ ⚙ 调用工具: imv_alter_maintain_index
│   参数: name=imv_customer_stats, columns=order_id
│ ✓ 增量维护索引已替换为 (order_id)。
│
│ ⚙ 调用工具: imv_optimize
│   参数: name=imv_order_agg
│ → 子视图 imv_order_agg 当前配置已为最优，无需调整。
│
│ 总结：imv_customer_stats 的延迟根因是增量维护索引未对齐
│ JOIN 键，已完成优化。后续维护延迟预计恢复至正常水平。
└──────────────────────────────────────────────────────

优势

IMV MCP 为数据开发者带来以下价值：

• 聚焦业务开发：从繁琐的巡检 SQL 中解放出来，专注于业务逻辑。

• 简化工作流：将跨多个工具的巡检与诊断，简化为 IDE 内的几轮自然语言对话。

• 杜绝误操作：只读与写操作分离，删除等破坏性操作必须经用户确认，保障业务连续性。

• 加速问题定位：延迟、报错、性能统计一站式获取，避免人工拼凑多条诊断 SQL 的结果。

常见问题