Lightdash 漏斗图 Chart-as-Code 完整配置参考：从 YAML 声明到转换漏斗分析-二趣网

Lightdash 漏斗图 Chart-as-Code 完整配置参考：从 YAML 声明到转换漏斗分析

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

漏斗图（Funnel Chart）用于可视化顺序流程中各阶段的数值递减情况，是转化漏斗、销售管道、多步骤用户流程分析的标准图表形态。本指南以 Lightdash 的 Chart-as-Code 能力为核心，完整讲解漏斗图的 YAML 配置结构、每个配置项的语义与取值、最佳实践与常见问题排查，并结合仓库中的 JSON Schema、前端实现与 API 示例给出源码级佐证。读完本文，你将能够在 Lightdash 中用声明式 YAML 编写、校验并交付可版本控制的漏斗图配置。

何时使用漏斗图

漏斗图的核心假设是"数值随阶段推进而递减"，适合呈现以下场景：

转化漏斗：网站访客 → 注册用户 → 付费客户；
销售管道：潜在客户（Leads）→ 已确认（Qualified）→ 方案（Proposal）→ 成交（Closed）；
流程追踪：申请流转、结账流程、新用户引导步骤；
流失分析：定位用户在哪一步离开流程，量化每一步的转化率与流失点。

对于非顺序流程、多个漏斗对比、阶段过多的数据，漏斗图并非最优选择，详见下文"何时不应使用漏斗图"。

图表结构与基础配置

一份漏斗图 Chart-as-Code 配置由chartConfig（含type: funnel与config）、metricQuery（定义查询维度、指标与排序）以及name、slug、spaceSlug、tableName等元信息组成。基础示例如下：

chartConfig: config: dataInput: row fieldId: leads_count type: funnel contentType: chart metricQuery: dimensions: - leads_stage exploreName: leads metrics: - leads_count sorts: - descending: false fieldId: leads_stage name: "Sales Funnel" slug: sales-funnel spaceSlug: sales tableName: leads version: 1

其中metricQuery至少需要提供"一个表示阶段的维度（如leads_stage）+ 一个表示各阶段数值的指标（如leads_count）"，并通过sorts显式控制阶段顺序。在仓库的 Chart-as-Code JSON Schema（packages/common/src/schemas/json/chart-as-code-1.0.json）中，ChartType.FUNNEL被定义为枚举值"funnel"，FunnelChartConfig结构则要求type字段为必填，config承载漏斗图特有的全部配置项，与本文 YAML 示例一一对应。

关键配置项详解

`dataInput`：数据组织结构

声明查询结果中漏斗数据是按行还是按列排布，Schema 中由FunnelChartDataInput枚举限定为两个取值：

row（默认）：每一行代表一个漏斗阶段，推荐使用；
column：每一列代表一个漏斗阶段。

基于行（row）的示例（推荐）：

| stage | count | |----------------|-------| | Awareness | 10000 | | Interest | 5000 | | Consideration | 2000 | | Purchase | 500 |

基于列（column）的示例：

| awareness | interest | consideration | purchase | |-----------|----------|---------------|----------| | 10000 | 5000 | 2000 | 500 |

`fieldId`：漏斗数值字段

指定用于呈现漏斗数值的字段 ID（指标或维度），例如示例中的leads_count。该字段在 Schema 中被描述为"Field ID to display in funnel"（chart-as-code-1.0.json 中FunnelChart的fieldId属性）。

`labels`：标签显示控制

控制阶段标签的显示方式：

position：inside（默认）、left、right或hidden，枚举定义于FunnelChartLabelPosition；
showValue：是否显示实际数值（如 "5,000"）；
showPercentage：是否显示相对最大值的百分比（如 "50%"）。

标签位置的选择原则：短阶段名与宽漏斗用inside；长阶段名用left或right；当图例已能提供足够上下文时可用hidden。

`labelOverrides`：阶段自定义标签

为特定阶段提供面向用户的友好名称，避免直接暴露内部字段 ID：

config: labelOverrides: leads_stage_awareness: "Top of Funnel" leads_stage_interest: "Engaged Users"

键的构成方式为维度名_阶段值（leads_stage维度下的awareness值）。Schema 中labelOverrides被定义为Record<string, string>类型（"Custom labels for funnel stages"）。

`colorOverrides`：阶段颜色定制

为单个漏斗阶段定制颜色，必须使用带#前缀的合法十六进制色值：

config: colorOverrides: leads_stage_awareness: "#3b82f6" leads_stage_interest: "#10b981"

Schema 中对应描述为 "Custom colors for funnel stages"，类型同样为Record<string, string>。

图例选项

showLegend：是否显示图例（默认true）；
legendPosition：图例方向，取值horizontal或vertical，由FunnelChartLegendPosition枚举限定。

完整示例：销售管道

以下配置综合运用了颜色覆盖、标签覆盖、标签显示与图例位置等全部能力：

chartConfig: config: # Custom stage colors colorOverrides: opportunities_stage_closed: "#8b5cf6" opportunities_stage_lead: "#3b82f6" opportunities_stage_negotiation: "#f59e0b" opportunities_stage_proposal: "#10b981" opportunities_stage_qualified: "#06b6d4" dataInput: row fieldId: opportunities_count # Custom stage labels labelOverrides: opportunities_stage_closed: "Closed Won" opportunities_stage_lead: "New Leads" opportunities_stage_negotiation: "In Negotiation" opportunities_stage_proposal: "Proposal Sent" opportunities_stage_qualified: "Qualified Opportunities" labels: position: inside showPercentage: true showValue: true legendPosition: vertical showLegend: true type: funnel contentType: chart metricQuery: dimensions: - opportunities_stage exploreName: opportunities limit: 10 metrics: - opportunities_count sorts: - descending: false fieldId: opportunities_stage name: "Sales Pipeline" slug: sales-pipeline spaceSlug: sales tableName: opportunities version: 1

注意metricQuery.limit可以限制返回的阶段数量，配合sorts可以保证 4~7 个阶段的推荐展示范围。

结合仓库源码理解漏斗图实现

Lightdash 仓库中除了 Chart-as-Code 声明式配置，还提供了独立的"漏斗构建器"（funnel builder）能力，可用于理解漏斗图背后的数据模型与查询语义：

类型定义：packages/common/src/types/funnel.ts 定义了FunnelStep（步骤顺序 + 事件名）、FunnelDateRange（预设范围如last_7_days/last_30_days/last_90_days或自定义起止日期）、FunnelConversionWindowUnit（hours/days/weeks）、FunnelQueryRequest与结果类型FunnelStepResult（包含总体转化率conversionRate、相邻步骤转化率stepConversionRate与中位转化耗时等）。可见漏斗分析关注的不只是阶段数值，还包括用户路径中的时间语义。
前端校验逻辑：packages/frontend/src/features/funnelBuilder/utils/funnelChartConfig.ts 中的canRunFunnelQuery要求配置必须同时具备 project、explore、时间戳字段、用户 ID 字段、事件名字段，且有效步骤数不少于 2，日期范围必须合法，才能发起查询。
API 示例：examples/api/funnel.http 给出了完整请求体，例如"商品浏览 → 加购 → 发起结账 → 完成结账"的四步电商转化漏斗，附带conversionWindow（如 7 天）与breakdownDimensionId（按设备类型拆解）等扩展参数，可用于对照验证漏斗图数据来源。
历史演进：漏斗图类型由迁移文件 packages/backend/src/database/migrations/20240619090032_add-funnel-chart-type.ts 引入，说明它是一个较新的、有独立存储与查询链路支持的图表类型。

最佳实践

数据准备

按逻辑顺序排列阶段：在metricQuery.sorts中按漏斗顺序（从上到下）对阶段排序，避免阶段错乱；
使用有意义的阶段名：清晰的标签能帮助读者快速理解流程，必要时用labelOverrides将内部 ID 映射为业务术语；
包含全部阶段：不要过滤掉数值为零的阶段——零值阶段恰恰是流失点的直观体现。

视觉设计

控制阶段数量：4~7 个阶段可读性最佳，超过 7 个建议改用折线图或柱状图；
展示百分比：开启showPercentage帮助读者理解阶段间的转化率差异；
使用递进色系：颜色应暗示流程推进的方向感，可用colorOverrides设置由冷到暖的序列；
合理选择标签位置：短阶段名与宽漏斗用inside；长阶段名用left或right；图例已足够时用hidden。

何时不应使用漏斗图

非顺序流程：改用饼图或柱状图；
多个漏斗对比：改用分组柱状图；
阶段过多（>7）：考虑折线图或柱状图；
阶段数值可能增长：漏斗图假设数值递减，递增阶段不适合用漏斗呈现。

常见问题排查

问题：阶段顺序错乱

解决：在metricQuery中添加显式排序：

metricQuery: sorts: - descending: false fieldId: stage_field

问题：标签被截断或相互重叠

解决：将标签位置改为left或right，避免inside模式下长文本拥挤。

问题：颜色不生效

解决：确认使用的是带#前缀的合法十六进制色值，且colorOverrides的键与维度取值完全一致（格式为维度名_阶段值）。

问题：图例显示内部字段 ID

解决：使用labelOverrides为各阶段提供面向用户的友好名称，替换掉内部字段 ID。

校验与落地

完整的 Schema 定义可在仓库两份 Chart-as-Code JSON Schema 中查阅$defs/funnelChart（即FunnelChart）部分：packages/common/src/schemas/json/chart-as-code-1.0.json 为源码生成的权威版本，skills/developing-in-lightdash/resources/schemas/chart-as-code-1.0.json 为技能资源目录中的副本。二者共同确认了dataInput（row/column）、labels.position（inside/left/right/hidden）、legendPosition（horizontal/vertical）等所有枚举取值的合法性，可作为编写与校验漏斗图 YAML 时的权威依据。将漏斗图配置为 Chart-as-Code 文件后，即可像管理代码一样对图表进行版本控制、评审与自动化部署，实现"分析以代码的速度运转"。

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析