mcpField
W
writing-clickhouse-queries

writing-clickhouse-queries

github.com/posthogData & databases40.5k138 installsUpdated today
Repository

About writing-clickhouse-queries

A repository skill for writing and reviewing new ClickHouse queries and product tables in PostHog. It points developers to the authoritative query guide and related references, and distinguishes new-query work from optimization and migration tasks.

Key features

  1. 01Guidance for new ClickHouse queries
  2. 02Review of QueryRunner subclasses
  3. 03Table and ALTER design
  4. 04Row ID format selection
  5. 05Materialized columns and indexes

Use cases

  1. 01Adding a product query in PostHog
  2. 02Designing a new ClickHouse table
  3. 03Choosing row IDs for a table
  4. 04Adding skip indexes or projections

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/posthog/posthog --skill writing-clickhouse-queries

After installing, type/writing-clickhouse-queriesin Claude Code to confirm it loaded.

Details

From the project README

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:

When to use

  • Writing or reviewing a QueryRunner subclass in posthog/hogql_queries/ or products/*/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.

Comments

Markdown supported