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 を使います
• NULL の処理：HogQL では、生の ClickHouse SQL と比べて NULL の処理が簡略化されています
• フィルターのプレースホルダー：PostHog のダッシュボードで UI によるフィルタリングを可能にするには、クエリで {filters} を使います
• 集計：count()、uniq()、avg()、sum() などの ClickHouse の集計関数を優先します

よく使われるパターン

イベントクエリ

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') を使います
• ダッシュボードで UI によるフィルタリングを有効にするには、WHERE 句に {filters} のプレースホルダーを含めます
• ダッシュボード全体で再利用する SQL 変数には、{variables.name} を使います
• ダッシュボードの日付範囲には、{filters.dateRange.from} と {filters.dateRange.to} でアクセスします
• 必ず時間範囲でフィルタリングします。範囲が短いほど高速です（例：timestamp >= now() - INTERVAL 7 DAY）
• 一意の値を数える場合は、count(distinct) より効率的な uniq() を優先します
• 同じテーブルを複数回スキャンしないでください。再利用するサブセットにはマテリアライズドビューを使います
• 大規模なデータセットでは、OFFSET ではなくタイムスタンプベースのページネーションを使います
• query_log でデバッグしやすいよう、クエリには内容がわかる名前を付けます
• 時間単位でグループ化するには、dateTrunc() を使います（例：dateTrunc('day', timestamp)）
• ファネルクエリには、windowFunnel() または sequenceMatch() 関数を使います
• インサイトや API で使う前に、PostHog の SQL エディターでクエリをテストします