writing-clickhouse-queries
Guide for writing performant ClickHouse queries in PostHog product code. Use when writing HogQL query runners, designing a ClickHouse table for a new product, adding materialized columns or skip indexes, or choosing a row ID format. For optimizing an existing query that is already too slow, use `/optimizing-clickhouse-and-hogql-queries` instead.
How do I install this agent skill?
npx skills add https://github.com/posthog/posthog --skill writing-clickhouse-queriesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a documentation guide for writing ClickHouse queries and is safe to use. It contains no executable code or external dependencies.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Writing ClickHouse queries for new products
If you're optimizing an existing query rather than writing a new one, this is the wrong skill. Use /optimizing-clickhouse-and-hogql-queries instead. That skill covers layer triage, smell scanning (FROM ... FINAL, JSONExtract over properties, missing skip indexes, self-joins, CTE blow-up), measurement on the Test Cluster, and applying the fix at the right layer.
Read docs/published/handbook/engineering/databases/clickhouse-queries-new-products.md for the authoritative guide on writing new queries.
Then pull in whichever related docs the task touches:
hogql-python.mdfor HogQL in Pythonmaterialized-columns.mdquery-performance-optimization.md
When to use
- Writing or reviewing a
QueryRunnersubclass inposthog/hogql_queries/orproducts/*/backend/ - Adding a new ClickHouse table or ALTER for a product (
posthog/clickhouse/migrations/) - Choosing a row ID format for a new table
- Adding or removing materialized columns, skip indexes, or projections
For investigating an existing slow query, debugging a system.query_log row, or reviewing a proposed HogQL printer change for performance, use /optimizing-clickhouse-and-hogql-queries.
Not the right skill for: customer-facing ad-hoc HogQL via Max / posthog:execute-sql, use query-examples for that. For migration mechanics (node roles, engines, replication), use clickhouse-migrations.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/posthog/posthog/writing-clickhouse-queries">View writing-clickhouse-queries on skillZs</a>