tools-and-features-hogql

PostHog 的 HogQL 查询

此技能可帮助你编写 PostHog 分析所用的 HogQL 查询。HogQL 是 PostHog 的 SQL 方言，是对 ClickHouse SQL 的封装，并简化了属性访问，同时提供 PostHog 专用函数。

参考文件

• references/expressions.md - SQL 表达式 - 文档
• references/aggregations.md - 支持的聚合函数 - 文档
• references/clickhouse-functions.md - 支持的 ClickHouse 函数 - 文档
• references/data-access.md - 使用 SQL 访问数据 - 文档
• references/variables.md - SQL 变量 - 文档
• references/useful-functions.md - 实用 SQL 函数 - 文档
• references/posthog.md - PostHog 表结构（事件、用户、群组、会话）
• references/sessions.md - 会话 - 文档

请查阅文档，了解 SQL 语法、可用函数和查询模式。

关键原则

• 属性访问：使用 properties.$property_name 访问事件属性，使用 person.properties.$property_name 访问用户属性
• 空值处理：与原始 ClickHouse SQL 相比，HogQL 的空值处理更简便
• 筛选器占位符：在查询中使用 {filters}，以支持在 PostHog 仪表板中通过 UI 进行筛选
• 聚合：优先使用 ClickHouse 聚合函数，例如 count()、uniq()、avg()、sum()

常见模式

事件查询

SELECT event, count()
FROM events
WHERE {filters}
GROUP BY event
ORDER BY count() DESC

属性细分

SELECT properties.$browser AS browser, count()
FROM events
WHERE event = '$pageview' AND {filters}
GROUP BY browser

用户属性

SELECT person.properties.email, count()
FROM events
WHERE {filters}
GROUP BY person.properties.email

框架指南

• 事件属性使用 properties.$name 语法，用户属性使用 person.properties.$name
• 对于特殊字符，使用方括号表示法，例如 properties['$feature/cool-flag']
• 筛选群组时，使用 person_id IN COHORT 'cohort-name'
• 对于操作，在 WHERE 子句中使用 matchesAction('action-name')
• 在 WHERE 子句中加入 {filters} 占位符，以启用仪表板中的 UI 筛选
• 使用 {variables.name} 在不同仪表板间复用 SQL 变量
• 使用 {filters.dateRange.from} 和 {filters.dateRange.to} 访问仪表板的日期范围
• 始终添加时间范围筛选——范围越短，查询越快（例如，timestamp >= now() - INTERVAL 7 DAY）
• 统计唯一值时，优先使用 uniq() 而不是 count(distinct)，效率更高
• 不要多次扫描同一张表——使用物化视图保存可复用的数据子集
• 对大型数据集使用基于时间戳的分页，而不是 OFFSET
• 为查询起描述性名称，以便在 query_log 中更容易调试
• 使用 dateTrunc() 按时间分组（例如，dateTrunc('day', timestamp)）
• 对于漏斗查询，使用 windowFunnel() 或 sequenceMatch() 函数
• 在将查询用于洞察或 API 前，先在 PostHog SQL 编辑器中进行测试