managing-path-cleaning-rules

管理路径清理规则

路径清理规则会规范化 $pathname 和 $entry_pathname，使共享同一模板的页面（/users/123/profile、/users/456/profile……）在 Web 分析图块、Paths 洞察以及任何调用 apply_path_cleaning 的 HogQL 查询中合并为一行（/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-…
• slug：/posts/why-i-love-posthog
• 日期：/archive/2024-09-12
• 区域设置：/en-US/、/fr-FR/
• 分页：?page=3、/page/3/

3. 起草 regex + alias

模式	匹配示例	regex	alias
数字片段	/users/123/profile	/users/\d+/profile	/users/<id>/profile
UUID v4	/sessions/8f3c1a3b-…	/sessions/[0-9a-f-]{36}	/sessions/<uuid>
slug	/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+$	（空 alias 会将其删除）

锚定规则参考：

• 仅当片段必须位于路径开头时，才在 regex 开头添加 ^
• 末尾添加 $，以避免通用规则（例如 \d+$）匹配路径中间的片段

4. 保存前测试

有三种方法，任选其一：

• 设置页面测试器：/settings/project#path_cleaning 内置了一个“测试路径”输入框，可按顺序重放完整规则链。

• 项目 HogQL（通过 execute-sql）：

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

  如果要验证多条规则之间的交互，请按规则实际运行的顺序串联 replaceRegexpAll 调用。

• 内置 AI 助手：规则编辑器中已提供可访问的 AiRegexHelper 模态框（Help me with Regex 按钮），可将自然语言转换为正则表达式。当用户表示“我不懂 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 分析：页面标题中的 路径清理开关
• 路径洞察：洞察筛选器中的路径清理开关
• HogQL：任何调用 apply_path_cleaning(path_expr, team) 的查询

规则按项目存储一份，不按洞察单独存储。

常见问题

• 优先使用占位符别名，而不是反向引用 — 替换捕获组的规则，每行的成本大约是使用固定别名的同一规则的 3 倍，因为 re2 必须追踪子匹配边界，而不是在快速路径上判断是否匹配。只有在它能将多个近似相同的规则合并为一个时才使用反向引用；由于清理会对每一行评估每条规则，这显然能带来净收益。无论哪种情况，都要确保正则以 ^ 锚定：replaceRegexpAll 会继续扫描以查找更多匹配，因此未锚定的模式开销远高于锚定模式。
• alias 中的反向引用需要双重转义 — ClickHouse 的 replaceRegexpAll 支持 \0（整个匹配）和 \1–\9（捕获组）。在 JSON 字段或 SQL 字符串字面量中，反斜杠必须加倍，因此在 path_cleaning_filters / HogQL 中使用 \\1，才能在 ClickHouse 层获得 \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 分析 / 路径图表中的历史数据。应用任何破坏性更改前，请先提醒用户。