formatting-insight-axes

インサイトの表示形式の軸

PostHog には、インサイトの軸をフォーマットする機能が組み込まれています。単位を偽装するためにクエリを無理に変更したり、固定の接頭辞や接尾辞を付けたりするのではなく、この機能を使ってください。

2 種類のインサイトでは、設定する場所が異なります。

• 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 は EUR を基本通貨とするプロジェクトでも常に USD）、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
  }
}

固定通貨の値（例：米ドル建ての LLM コスト）— 通貨記号を固定

{
  "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 の組み合わせ、または style: "percent" と "%" のサフィックスを併用した SQL 列）がある場合は、同じ posthog:insight-update 呼び出しで修正してください。N で割る処理や 100.0 *、およびリテラルの % を取り除き、単位の書式設定はフォーマットに任せてください。値は同じままで、ラベルだけが変わります。無関係なインサイトは調べず、すでに編集しているものだけを修正してください。