managing-path-cleaning-rules

Path cleaning rules normalize $pathname and $entry_pathname so that pages sharing the same template (/users/123/profile, /users/456/profile, …) collapse into one row (/users/<id>/profile) in Web analytics tiles, Paths insights, and any HogQL query that calls apply_path_cleaning. They are the right answer when a breakdown is fragmented across thousands of near-identical URLs.

This skill teaches you how to:

• recognize when path cleaning is the right tool
• inspect real paths to find what needs cleaning
• write regex + alias rules in re2 syntax with the project's placeholder convention
• test rules before saving them
• order rules so specific patterns aren't swallowed by generic ones
• apply the rules via MCP

Team.path_cleaning_filters is a JSON list of PathCleaningFilter objects:

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

• regex — a re2 pattern. No need to escape /. Anchor with ^ / $ when you mean it.
• alias — the replacement. Default to angle-bracket placeholders (<id>, <slug>, <uuid>, <date>) so the cleaned path stays human-readable. Backreferences to the regex's capture groups also work, but they cost more to evaluate — see the backreference pitfall below before reaching for one.
• order — integer. Rules apply sequentially in order ascending, each rule's output feeds the next.

Application is replaceRegexpAll(pathname, regex, alias) per rule, chained.

When the user (or a HogQL query) opts in:

• Web analytics: the Path cleaning toggle in the page header
• Paths insights: the path cleaning toggle in the insight filters
• HogQL: any query that calls apply_path_cleaning(path_expr, team)

The rules are stored once per project — they are not insight-scoped.

• Prefer a placeholder alias over a backreference — a rule that substitutes a capture group costs roughly 3x more per row than the same rule with a fixed alias, because re2 has to track submatch boundaries instead of answering match/no-match on its fast path. Reach for one only when it collapses several near-identical rules into one, which is a clear net win since cleaning evaluates every rule against every row. Keep the regex ^-anchored either way: replaceRegexpAll keeps scanning for further matches, so an unanchored pattern is much more expensive than an anchored one.
• Backreferences in alias need double-escaping — ClickHouse's replaceRegexpAll supports \0 (whole match) and \1–\9 (capture groups). In a JSON field or SQL string literal the backslash must be doubled, so use \\1 in path_cleaning_filters / HogQL to get the \1 backreference at the ClickHouse layer.
• Forgetting $ — \d+ without an end anchor matches every numeric run in any path, so /blog/2024-09-12/post becomes /blog/<num>-<num>-<num>/post when you only meant to match the year segment. Use \d+$ or \d+(/|$) depending on intent.
• Escaping / — re2 does not require it. \/ works but adds noise.
• Case sensitivity — re2 is case-sensitive by default. Use (?i) at the start of the pattern for case-insensitive matching, e.g. (?i)/users/\d+.
• Replacing the whole list — the raw path_cleaning_filters field is overwrite, not append. Use path-cleaning-rules-update (which does the read-modify-write for you) instead of hand-editing the field; if you must edit it directly, always start from the current list.
• Rules apply globally — adding a rule can change historical numbers in every Web analytics / Paths chart that has cleaning enabled. Warn the user before applying anything destructive.