managing-path-cleaning-rules

パスクリーニングルールの管理

パスクリーニングルールは、$pathname と $entry_pathname を正規化します。これにより、同じテンプレートを共有するページ（/users/123/profile、/users/456/profile、…）が、Web 分析タイル、Paths insights、および apply_path_cleaning を呼び出す HogQL クエリで、1 行（/users/<id>/profile）に集約されます。ほぼ同じ URL が何千もあるために内訳が分散している場合に有効です。

このスキルでは、次の方法を学びます。

• パスクリーニングが適切な解決策かどうかを判断する
• 実際のパスを調べ、クリーニングが必要な部分を見つける
• プロジェクトのプレースホルダー規則に従って、re2 構文で regex + alias ルールを記述する
• 保存前にルールをテストする
• 具体的なパターンが汎用的なパターンに取り込まれないよう、ルールの順序を設定する
• MCP 経由でルールを適用する

データモデル

Team.path_cleaning_filters は PathCleaningFilter オブジェクトの JSON リストです。

{
  "regex": "/users/\\d+/profile",
  "alias": "/users/<id>/profile",
  "order": 0
}

• regex — re2 パターンです。/ をエスケープする必要はありません。意図する場合は ^ / $ でアンカーします。
• alias — 置換文字列です。クリーニング後のパスの可読性を保つため、山括弧のプレースホルダー（<id>、<slug>、<uuid>、<date>）をデフォルトで使用します。正規表現のキャプチャグループへの後方参照も使用できますが、評価コストが高くなります。使用する前に、後述の後方参照に関する注意点を確認してください。
• order — 整数です。ルールは order の昇順で順次適用され、各ルールの出力が次のルールに渡されます。

適用時は、ルールごとに replaceRegexpAll(pathname, regex, alias) を連結して実行します。

ワークフロー

1. パスクリーニングが適切か確認する

ユーザーが問題にしているのはカーディナリティ（グラフ内の個別パスが多すぎること）ですか、それとも URL ごとの詳細データが必要なのでしょうか。パスクリーニングが適しているのは前者です。URL ごとのデータが必要な場合は、代わりに $pathname のプロパティフィルターを提案してください。

2. 実際のパスを調べる

パターンを推測せず、クエリで確認します。execute-sql MCP ツールを使います。

SELECT properties.$pathname AS path, count() AS views
FROM events
WHERE event = '$pageview'
  AND timestamp > now() - INTERVAL 7 DAY
GROUP BY path
ORDER BY views DESC
LIMIT 200

結果で次のようなものを探します。

• 数値 ID：/users/123、/orders/4242
• UUID：/sessions/8f3c1a3b-…
• スラッグ：/posts/why-i-love-posthog
• 日付：/archive/2024-09-12
• ロケール：/en-US/、/fr-FR/
• ページネーション：?page=3、/page/3/

3. 正規表現とエイリアスを作成する

パターン	マッチ例	regex	alias
数値セグメント	/users/123/profile	/users/\d+/profile	/users/<id>/profile
UUID v4	/sessions/8f3c1a3b-…	/sessions/[0-9a-f-]{36}	/sessions/<uuid>
スラッグ	/posts/why-posthog	/posts/[a-z0-9-]+$	/posts/<slug>
ISO 日付	/archive/2024-09-12	/archive/\d{4}-\d{2}-\d{2}	/archive/<date>
ロケールプレフィックス	/en-US/about	^/[a-z]{2}-[A-Z]{2}/	/<locale>/
末尾のクエリ／ページ	/blog?page=3	\?page=\d+$	（空のエイリアスで削除）

アンカーを付ける際の目安：

• セグメントがパスの先頭にある場合に限り、正規表現の先頭に ^ を付けます
• 汎用ルール（例：\d+$）がパス途中のセグメントにマッチしないよう、末尾に $ を付けます

4. 保存前にテストする

次の 3 つの方法から 1 つ選びます。

• 設定ページのテスター：/settings/project#path_cleaning には、順序どおりのルール全体を再実行する「test path」入力欄が組み込まれています。

• プロジェクトの HogQL（execute-sql 経由）：

  SELECT replaceRegexpAll('/users/42/profile', '/users/\d+/profile', '/users/<id>/profile')
  

  複数ルールの相互作用を確認する場合は、ルールが実行される順序に合わせて replaceRegexpAll の呼び出しを連結します。

• 組み込み AI ヘルパー：ルールエディターから利用できる AiRegexHelper モーダル（Help me with Regex ボタン）があり、自然言語を正規表現に変換できます。ユーザーが「正規表現がわからない」と言った場合は提案してください。ただし、必ずテスターで実際のパスに対して出力を検証してください。

5. ルールは具体的なものから一般的なものの順に並べます

順番に適用されるため、一般的なルールを先に置くと、具体的なルールに適用されるべきパスもすべて取り込まれてしまいます。

order=0  /users/me/profile        →  /users/me/profile     (specific, runs first)
order=1  /users/\d+/profile       →  /users/<id>/profile
order=2  /users/[a-z0-9-]+        →  /users/<slug>          (catch-all, runs last)

/users/[a-z0-9-]+ を先に実行すると、/users/me/profile にも一致してしまい、より具体的なルールが適用されなくなります。

6. MCP で適用します

path-cleaning-rules-update ツールの使用をおすすめします。現在のルールを読み込み、細かい操作（append、insert、replace、remove、reorder）を適用し、order を自動で採番します。また、confirm: true を渡さない限り、保存せずに適用後のルールのプレビューを返します。sample_paths を渡すと、適用後のルールによって実際のパスがどのように書き換えられるか確認できます。

まず confirm を指定せずに呼び出してプレビューを取得し、それをユーザーに提示してから、同じ呼び出しを "confirm": true とともに再送信して保存します。

{
  "operations": [{ "action": "append", "alias": "/users/<id>/profile", "regex": "/users/\\d+/profile" }],
  "sample_paths": ["/users/123/profile", "/users/me/profile"]
}

このツールが読み込み、変更を適用し、書き戻す処理を行うため、ルールの一覧全体を取得したり、order を振り直したり、既存のルールを誤って上書きしたりする心配はありません。path_cleaning_filters を直接編集する場合によくある失敗を避けられます。

project-settings-update（リスト全体の上書き）に切り替える必要がある場合は、必ず先に既存のルールを読み込み、内容を統合してください。上書きすると、チームがすでに設定しているルールが通知なく失われます。

ルールが適用される場所

ユーザーが（または HogQL クエリが）有効にした場合、次の場所で適用されます。

• Web analytics：ページヘッダーのPath cleaning切り替え
• Paths insights：インサイトフィルターの Path cleaning 切り替え
• HogQL：apply_path_cleaning(path_expr, team) を呼び出すクエリ

ルールはプロジェクトごとに一度だけ保存され、インサイト単位ではありません。

よくある落とし穴

• 後方参照よりプレースホルダーのエイリアスを優先する — キャプチャグループを置換するルールは、固定エイリアスを使う同じルールと比べて、行ごとの処理コストが約3倍になります。これは、re2 の高速パスで一致／不一致を判定する代わりに、部分一致の境界を追跡する必要があるためです。複数のよく似たルールを1つにまとめられるなど、明らかに全体的な利点がある場合にのみ使用してください。クリーニングでは、すべてのルールをすべての行に対して評価するためです。どちらの場合も正規表現の先頭に ^ を付けてください。replaceRegexpAll は後続の一致も検索し続けるため、アンカーのないパターンはアンカー付きのパターンよりも大幅に処理コストが高くなります。
• alias の後方参照ではエスケープを二重にする — ClickHouse の replaceRegexpAll は、\0（一致全体）と \1～\9（キャプチャグループ）をサポートしています。JSON フィールドまたは SQL 文字列リテラルではバックスラッシュを二重にする必要があるため、ClickHouse のレイヤーで \1 の後方参照を使うには、path_cleaning_filters／HogQL で \\1 を指定します。
• $ を忘れる — 終端アンカーのない \d+ は、どのパスに含まれる数字の並びにも一致します。そのため、年のセグメントだけを対象にするつもりでも、/blog/2024-09-12/post が /blog/<num>-<num>-<num>/post になります。意図に応じて \d+$ または \d+(/|$) を使ってください。
• / をエスケープする — re2 ではエスケープは不要です。\/ も使えますが、記述が煩雑になります。
• 大文字と小文字の区別 — re2 はデフォルトで大文字と小文字を区別します。大文字と小文字を区別せずに一致させるには、パターンの先頭に (?i) を付けます。例：(?i)/users/\d+。
• リスト全体の置き換え — path_cleaning_filters フィールドへの直接書き込みは、追加ではなく上書きです。フィールドを手動で編集するのではなく、path-cleaning-rules-update（読み込み、変更を適用し、書き戻す処理を行います）を使ってください。直接編集する必要がある場合は、必ず現在のリストを元にしてください。
• ルールはグローバルに適用される — ルールを追加すると、クリーニングが有効になっているすべての Web analytics／Paths チャートで、過去の数値が変わる可能性があります。破壊的な変更を適用する前に、ユーザーに警告してください。