creating-box-plot-insights

创建箱线图洞察

箱线图需要分布数据，而非已汇总的平均值或总计。请选择最简单、足以表达用户问题的查询类型。

选择查询类型

以下条件全部满足时，使用标准产品分析箱线图：

• 来源是 Trends 支持的事件、操作或数据仓库表。
• 一个数值属性包含要分布的值。
• 用户想查看常规时间区间内的分布。

用户需要自定义分组、联接、派生值或专用 SQL 时，使用 SQL 箱线图。编写 HogQL 前，请阅读 querying-posthog-data，然后以 references/sql-examples.md 为起点。

不要仅为复现标准 Trends 查询而使用 SQL。

标准产品分析箱线图

1. 确定事件或操作及其数值属性。保存前确认该属性为数值型。
2. 构建一个来源为 TrendsQuery 的 InsightVizNode：
   • 设置系列事件或操作。
   • 将 math_property 设为数值属性。
   • 将 trendsFilter.display 设为 BoxPlot。
   • 选择符合问题的日期范围和间隔。
3. 使用 posthog:query-trends 运行查询。
4. 如果返回分布行，使用 posthog:insight-create 保存。
5. 使用 posthog:insight-get 读取并确认属性、间隔和显示方式。

不设置数值型 math_property 的箱线图无效。除非用户想分布的值就是事件计数，否则不要用事件计数替代。

SQL 箱线图

SQL 必须针对每个 X 轴与系列组合返回一行预聚合数据。在数据库中计算汇总值。切勿根据客户端中受限的结果行计算百分位数。

必需的数值字段：

• 最小值
• 第 25 百分位数
• 中位数
• 平均值
• 第 75 百分位数
• 最大值

最简单的结果格式使用以下别名：

x, series, min, p25, median, mean, p75, max

x 和 series 为可选项：

• 对于一个整体分布或每个系列一个箱线图，将 xAxisColumn 设为 null。
• 对于一个系列，将 seriesColumn 设为 null。

保存前使用 posthog:execute-sql 验证 HogQL。检查以下内容：

• 每项必需统计值都是数值型。
• 每一行都满足 min <= p25 <= median <= p75 <= max。
• 平均值介于最小值与最大值之间。
• 每个 X 轴与系列组合只出现一次。
• 系列数不超过 200，X 轴与系列的组合数不超过 10,000。

然后使用 posthog:insight-create 保存此格式：

{
  "query": {
    "kind": "DataVisualizationNode",
    "source": {
      "kind": "HogQLQuery",
      "query": "<validated HogQL>"
    },
    "display": "BoxPlot",
    "chartSettings": {
      "boxPlot": {
        "xAxisColumn": "x",
        "seriesColumn": "series",
        "minColumn": "min",
        "p25Column": "p25",
        "medianColumn": "median",
        "meanColumn": "mean",
        "p75Column": "p75",
        "maxColumn": "max",
        "excludeOutliers": true
      }
    }
  }
}

如果查询使用了不同名称，请使用实际别名。不要将六项统计值映射为六个 Y 轴系列。

验证已保存的洞察

1. 使用 posthog:insight-get 读取已保存的洞察。
2. 使用 posthog:insight-query 运行它。
3. 确认结果仍包含预期列，且每个箱线图对应一行。
4. 报告洞察链接、所分布的数值，以及分组方式。

如果某一行缺少汇总值或汇总值无效，PostHog 会省略该箱线图，同时保留有效箱线图。若不应省略箱线图，请修正 SQL。

相关技能

• querying-posthog-data - 编写或更改 SQL 箱线图的 HogQL 前必须阅读。
• formatting-insight-axes - 当数值轴需要货币、时长、百分比或其他格式时使用。
• building-a-dashboard - 当箱线图需要与其他洞察一起放在仪表板上时使用。