formatting-insight-axes

格式化洞察坐标轴

PostHog 使用内置的坐标轴格式化器来呈现洞察。请使用它，而不是通过扭曲查询或添加字面前缀／后缀来伪造单位。

两种洞察类型在不同位置配置该格式化器：

• TrendsQuery — trendsFilter.aggregationAxisFormat（本页下文）
• SQL 洞察（DataVisualizationNode）— 按列配置 settings.formatting（参见 SQL 洞察）

反模式

如果你打算使用以下任一做法，请先停下来，选择下面的格式：

• formula: "A / 60" 配合 aggregationAxisPostfix: " mins" — 手动将秒转换为分钟
• formula: "A / 1000" 配合 aggregationAxisPostfix: " s" — 手动将毫秒转换为秒
• formula: "A * 100" 配合 aggregationAxisPostfix: "%" — 手动将比率转换为百分比
• 对原始值使用 aggregationAxisPostfix: "ms" / "s" / "min" / "hr"

这些做法会将单位固定在一个尺度上。内置格式化器会根据数值选择易读的单位（1.5s、2m 12s、1h 4m），并确保底层序列的数值正确，以便进行后续计算、细分和设置警报。

可用格式

在 TrendsQuery 上设置 trendsFilter.aggregationAxisFormat：

值	适用于……	呈现为
numeric（默认）	普通计数	1,234
duration	秒（任意尺度）	45s、2m 12s、1h 4m
duration_ms	毫秒	850ms、1.5s、1m 4s
percentage	已是 0-100 的值	47.3%
percentage_scaled	0-1 的比率	47.3%
currency	项目基础货币金额	$1,234.56（或本地货币代码）
short	需要缩写显示的大数值	1.2K、3.4M

trendsFilter 上的配套字段：

• aggregationAxisPrefix — 字面前缀（例如 "$"），用于无论项目设置如何，都要固定显示特定货币或单位符号的情况
• aggregationAxisPostfix — 字面后缀；仅用于格式无法表示的实际单位（例如 " req"、" events"），切勿用于 "mins" / "s" / "%" — 百分比格式已经会添加 % 符号，因此添加 "%" 后缀会显示为 50%%
• decimalPlaces — 小数位数上限（货币／比率通常设置为 1 或 2 位即可）

货币 — 谨慎选择 format 或 prefix

aggregationAxisFormat: "currency" 会使用项目基础货币呈现（在项目设置中设置，默认为 USD）。当底层数值使用相同货币时，请使用此格式，例如 PostHog 自动转换为项目基础货币的收入事件。

如果数值固定为特定货币，不受项目设置影响（例如 $ai_total_cost_usd 始终为 USD，即使项目的基础货币是 EUR），请使用 aggregationAxisPrefix: "$" + decimalPlaces: 2，以确保符号与数据相符。在这种情况下使用 format: "currency"，会在 EUR 项目中将 USD 数值显示为 €。

当序列的单位是秒时

如果序列的单位是秒（延迟、会话时长、首次事件耗时、处理时间、页面加载时间等），请默认使用 aggregationAxisFormat: "duration"，无需说明。不要停下来询问——格式化不会破坏数据（底层数值始终以秒为单位，只有标签会变化），因此选择它总比直接显示秒数更合适。

只有当用户明确指定了想固定使用的单位（“以分钟显示”“绘制以小时为单位的平均值”）时，才向用户确认：

“我可以将 y 轴固定为分钟，方法是将序列除以 60；也可以使用 PostHog 的 duration 格式化方式，根据每个值自动选择秒／分钟／小时——90s 会显示为 1m 30s，而 5400s 会显示为 1h 30m。你更倾向哪种方式？”

在没有用户参与的单次 MCP 调用场景中，直接选择 duration 并继续。

示例

延迟——以毫秒为单位的时长

{
  "kind": "TrendsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "$pageview",
      "math": "p95",
      "math_property": "$performance_page_loaded"
    }
  ],
  "trendsFilter": {
    "aggregationAxisFormat": "duration_ms"
  }
}

平均会话时长——以秒为单位的时长

{
  "kind": "TrendsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "$pageleave",
      "math": "avg",
      "math_property": "$session_duration"
    }
  ],
  "trendsFilter": {
    "aggregationAxisFormat": "duration"
  }
}

收入——项目的基础货币

{
  "trendsFilter": {
    "aggregationAxisFormat": "currency",
    "decimalPlaces": 2
  }
}

固定货币值（例如以 USD 计价的大模型成本）——固定符号

{
  "trendsFilter": {
    "aggregationAxisPrefix": "$",
    "decimalPlaces": 2
  }
}

转化率——由 0-1 公式计算的百分比

{
  "kind": "TrendsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "checkout_completed",
      "math": "dau"
    },
    {
      "kind": "EventsNode",
      "event": "checkout_started",
      "math": "dau"
    }
  ],
  "trendsFilter": {
    "formula": "A / B",
    "aggregationAxisFormat": "percentage_scaled",
    "decimalPlaces": 1
  }
}

SQL 洞察（DataVisualizationNode）

SQL 洞察没有 trendsFilter。 图表的格式化设置按列配置在 chartSettings.yAxis[].settings.formatting 中，表格的格式化设置按列配置在顶层的 tableSettings.columns[].settings.formatting 中。

{
  "kind": "DataVisualizationNode",
  "source": { "kind": "HogQLQuery", "query": "SELECT week, conversion_rate FROM ..." },
  "display": "ActionsLineGraph",
  "chartSettings": {
    "xAxis": { "column": "week" },
    "yAxis": [
      {
        "column": "conversion_rate",
        "settings": { "formatting": { "style": "percent", "decimalPlaces": 1 } }
      }
    ]
  }
}

style 可以是 none、number、short 或 percent——不支持 duration 或 currency。 这些格式请使用 prefix／suffix 表示，或直接在 SQL 中处理。

percent 会添加 % 符号，并将数值乘以 100（类似趋势的 percentage_scaled 格式；没有不缩放的变体）。 因此，请传入 0-1 的比率，并将 suffix 留空——选择一种形式，不要混用：

SQL 返回值	formatting	显示效果
0-1 的比率（a / b）	{"style": "percent", "decimalPlaces": 1}	47.3%
0-100（round(100.0 * a / b, 1)）	{"style": "number", "suffix": "%", "decimalPlaces": 1}	47.3%

混用会导致显示错误：style: "percent" 加上 "%" 后缀会显示为 47.3%%，而对已缩放到 0-100 的列使用 percent 则会显示为 4730%。 优先采用比率形式——这样查询中就不必包含 100.0 *，存储的列也会保持为普通比率，供其他读取该列的逻辑使用。

更新现有洞察

如果你正在编辑的洞察已使用以下反模式之一——趋势中的 formula／postfix 配对，或 SQL 列同时使用 style: "percent" 和 "%" 后缀——请在同一次 posthog:insight-update 调用中修正：移除除以 N 或乘以 100.0 * 的操作，以及字面量 %，让格式化设置负责单位。数值保持不变，只有标签会变化。不要扫描无关的洞察——只修正你当前正在处理的项目。