企业官网建设流程全解析

Metabase 瀑布图（Waterfall Chart）实战指南：数据形态、查询构建与图表配置

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase

瀑布图（Waterfall Chart）是 Metabase 中用于可视化"增量变化"的柱状图变体，适合展示一个起始值如何经过一系列增减最终到达总计值。本文基于官方文档 waterfall-chart.md 并结合仓库前端源码，完整讲解瀑布图的数据形态要求、基于Offset自定义表达式的查询构建方法、图表设置面板中的每个配置项，以及其实现原理与适用边界。读完本文，你将能够把"月度销售额变化""分类净收入"等业务数据快速转换为可交付的瀑布图，并理解为什么 Metabase 要求它"单一指标 + 单一维度"。

什么是瀑布图

瀑布图是柱状图的一种特殊形态，专门用于可视化同时包含正负值的数据。图中每一根柱子表示一次增加或减少，最右侧的一根深色柱子表示累计总计（running total）。

在 Metabase 中，瀑布图并非独立实现的渲染引擎，而是基于通用笛卡尔（Cartesian）图表体系扩展而来：组件文件 WaterfallChart.tsx 直接复用CartesianChart组件，仅通过 definition.ts 中identifier: "waterfall"的配置定义差异化行为。前端在 register.ts 中通过/* webpackChunkName: "viz-waterfall" */对该模块做按需懒加载。

什么时候使用瀑布图

瀑布图用于回答这类问题：一个起始值是如何通过一系列有增有减的变化，最终变成另一个值的？

典型的适用场景包括：

• 财务拆分（financial breakdowns）：从总收入出发，逐项减去成本、税费，得到净利润；
• 库存变化（inventory changes）：期初库存 + 入库 − 出库 − 损耗 = 期末库存；
• 任何需要"分步展示数值如何变化"的分析场景。

瀑布图的数据形态要求

创建瀑布图的问题必须满足：返回一个指标（metric），并按一个维度（dimension）分组，例如按时间或按类别分组。每个数据行代表某个值的"变化量"，而不是原始值本身。例如要绘制"销售额变化"，应使用"本月相对上月的销售额变化"，而非各月销售额的绝对值。

官方文档给出的示例数据形态如下（按月）：

绿色柱子表示销售额增加的月份，红色柱子表示销售额减少的月份，末尾的深色柱子表示六个月的净变化总量。

按类别分组的另一个示例：

上述形态约束在源码中有明确对应。查看 definition.ts 中的isSensible判断逻辑：要求行数大于 1（rows.length > 1）、至少两列（cols.length >= 2）、恰好一个维度列（dimensionCount === 1）且至少一个指标列（metricCount > 0）；同时通过maxMetricsSupported: 1与maxDimensionsSupported: 1明确限制最多支持 1 个指标、1 个维度。这就是文档中"不能添加分组（breakout）或显示多个序列"限制的底层来源。

为瀑布图构建查询

如果你的原始数据已经包含要绘制的正负变化值（例如带正负金额的逐笔交易），可以直接使用该数据创建图表，跳过本节。

但更常见的情况是：原始数据只有原始值（如各月销售额），并没有"相邻两行的变化量"：

此时需要用Offset自定义表达式来计算相邻行的差值。Offset可以返回结果集中另一行（更早或更晚）中某个表达式的值。

要计算"相对上月的销售额变化"：

1. 在查询构建器中点击Summarize（汇总）；
2. 按Created At: Month（创建时间：月）分组；
3. 添加一个Custom Expression（自定义表达式），公式为Sum([Sales]) - Offset(Sum([Sales]), -1)，并将列命名为 "Change in sales"。

结果查询就返回了瀑布图所需的数据形态。

关于Offset的细节，可参见 offset.md（亦被 expressions.md 索引），使用时需注意以下几点：

• 语法：Offset(expression, rowOffset)。expression是要从其他行取值的表达式；rowOffset是相对当前行的偏移量，-1表示上一行，1表示下一行。示例：Offset(Sum([Total]), -1)取上一行的Sum([Total])值。
• 使用范围：Offset只能在查询构建器的 Summarize 步骤中使用，不能用于创建自定义列。
• 数据库兼容性：Offset目前不适用于 MySQL/MariaDB、MongoDB 和 Druid。
• 分组顺序很重要：由于Offset引用其他行，分组（breakout）顺序会影响结果。Metabase 会先按第一个分组排序，再按额外的分组分区。例如想按产品类别查看各时段订单数、并计算各类别上一期的订单数，应先按Created At分组，再按产品类别分组。
• 不处理缺失数据：Offset只能引用结果集中"已存在的行"，因此在数据有缺口时可能产生"正确但意外"的结果。例如按天对比前一日数据时，若 10 月 3 日没有数据，则 10 月 4 日Offset(Count, -1)取到的是 10 月 2 日的值。如果希望按"前一个自然日/周"对比，需要保证数据中每个对比点都有对应行（如关联一张日历表补全缺失日期）。
• 返回类型：Offset返回偏移行中对应表达式的值，数据类型取决于该表达式。

瀑布图图表设置

打开图表设置：点击可视化区域左下角的齿轮（Gear）图标，进入图表设置面板。瀑布图的设置项定义于 definition.ts，它组合了GRAPH_AXIS_SETTINGS（坐标轴）、GRAPH_GOAL_SETTINGS（目标线）、GRAPH_DISPLAY_VALUES_SETTINGS（数值显示）、GRAPH_DATA_SETTINGS、TOOLTIP_SETTINGS（提示框）与TIMELINE_EVENTS_SETTINGS（时间线事件）等通用配置，并在此基础上追加瀑布图专属设置。

Display（显示）

在图表设置中点击Display选项卡，可以编辑图表外观。

目标线（Goal line）

• 开启Goal line开关即可为目标线添加一条目标线；
• 使用Goal value（目标值）与Goal label（目标标签）字段设置目标线的取值与标签；
• 注意：瀑布图的目标线上无法设置告警（alerts），详见 alerts.md。

各类型柱子的颜色

• Increase color（增加颜色）：正数值柱子的颜色，默认绿色。源码中默认值为color("accent1")（即 Metabase 主题色板中的 accent1，通常为绿色）；
• Decrease color（减少颜色）：负数值柱子的颜色，默认红色。源码中默认值为color("accent3")；
• Total color（总计颜色）：末尾总计柱的颜色，默认黑色。源码中默认值为Color(color("text-primary", staticVizOverrides)).hex()，即正文文字主色（深色）；该设置项还声明了readDependencies: ["waterfall.show_total"]，当Show total关闭时，总计颜色选项会自动隐藏。

数值显示

• 开启Show total（显示总计）开关，在末尾总计柱上显示其数值（默认开启，源码中getDefault: () => true）；
• 开启Show values on data points（在数据点上显示数值）开关，在所有柱子上显示数值。

Axes（坐标轴）

在图表设置中点击Axes选项卡，可以编辑图表坐标轴。

X 轴

• Show label（显示标签）：开关控制是否显示 x 轴标签；
• Label（标签）：设置 x 轴标签文本；
• Show lines and tick marks（显示轴线和刻度线）：控制是否显示 x 轴轴线与刻度。

Y 轴

• Show label（显示标签）：开关控制是否显示 y 轴标签；
• Label（标签）：设置 y 轴标签文本；
• Auto y-axis range（自动 y 轴范围）：开启时 Metabase 根据数据自动设置 y 轴范围；关闭后可使用Min（最小值）与Max（最大值）字段设置自定义范围；
• Scale（刻度类型）：选择 y 轴上数值的间距方式，可选Linear（线性）、Power（幂）与Log（对数）；
• Show lines and tick marks（显示轴线和刻度线）：控制是否显示 y 轴轴线与刻度；
• Number of tick marks（刻度数量）：设置 y 轴上出现的刻度个数，默认auto（自动）。

源码实现速览：瀑布图在前端是如何渲染的

对于希望深入理解实现细节的读者，仓库中瀑布图的完整实现链路如下：

1. 组件层：WaterfallChart.tsx 将属性直接透传给CartesianChart，即瀑布图复用通用笛卡尔图表组件树；
2. 数据模型层：在 use-models-and-option.ts 中，当card.display === "waterfall"时，图表数据模型由getWaterfallChartModel构建，ECharts 配置项由getWaterfallChartOption生成（见该文件case "waterfall"分支）；
3. 提示框配色：在 events.ts 的getSeriesOnlyTooltipRowColor函数中，瀑布图各柱的颜色判定逻辑为：若数据点属于总计柱（IS_WATERFALL_TOTAL_DATA_KEY），使用waterfall.total_color；否则按数值正负分别取waterfall.increase_color与waterfall.decrease_color——与文档中"绿涨红跌"的语义完全一致。

限制与替代方案

瀑布图是一把"专用工具"，有明确的适用边界：

• 仅正数或不需要总计：如果数据只有正值，或不需要追踪累计总计，建议改用柱状图（Bar chart）；
• 展示向单一目标的进度：如果目标是展示"距离某个单一目标值的进度"，建议使用进度条（Progress bar）或仪表图（Gauge）；
• 结构限制：瀑布图只支持单一指标按单一维度分组，不能添加分组（breakout）或显示多个序列（multiple series）——这与 definition.ts 中maxMetricsSupported: 1、maxDimensionsSupported: 1的限制一一对应；
• 告警限制：瀑布图的目标线上不能设置告警。

综合来看，瀑布图在 Metabase 中的定位非常聚焦：当你的问题恰好是"某个值如何一步步增减最终到达总计"时，它是最直观的呈现方式；而构建它最关键的一步，是借助Offset自定义表达式把原始值转换为增量值。更多可视化类型的选择思路，可参考可视化结果总览。

【免费下载链接】metabaseThe easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:项目地址: https://gitcode.com/GitHub_Trending/me/metabase