fix: add hogql anti-pattern rules to mcp sql guidance

[andyzzhao]

Problem

LLMs can write poor-performing HogQL. I created an LLM judge evaluation to find anti-patterns in LLM-written HogQL queries.

Changes

products/posthog_ai/skills/querying-posthog-data/references/guidelines.md. It's bundled into the MCP server, so the rules land in both the execute-sql tool description and the querying skill.

• Don't hunt for event or property names with LIKE '%term%'. Look up the real names with read-data-schema and match them exactly. A wildcard search reads every row in the time range; an exact match lets ClickHouse skip most of the table.
• Every events query needs a time filter in its WHERE clause. A time condition inside countIf(...) doesn't count, and a selective-looking id filter (session, trace, user) doesn't either: without a time filter the whole history gets scanned.
• Read the events table once per question where possible, using conditional aggregates like countIf instead of self-joins or repeating the same subquery. A WITH subquery used twice runs twice.
• Count unique users with uniq(person_id), not uniq(distinct_id). This one is about correctness than speed
• Don't GROUP BY values with unlimited variety (raw URLs, ids, free text) over long time ranges. The database holds every distinct value in memory, and LIMIT doesn't help.

Left alone on purpose: the uniq(distinct_id) examples in models-mcp.md, which mirror backend code and belong to the MCP analytics team.

How did you test this code?

Benchmarked the two biggest rewrites on our test ClickHouse cluster:

• Finding events with "insight" in the name: the wildcard version read 23x more rows (1.3B vs 56M) and 12x more data than matching the 48 exact names, for the identical result.
• Grouping by raw URL vs by URL with ids stripped out: same data read, but 6x more memory (2.9 GiB vs 495 MiB).

After this merges, the same evaluations that produced the fail rates above tell us whether the rules actually changed client behavior.

Automatic notifications

• Publish to changelog?
• Alert Sales and Marketing teams?

Docs update

Not needed: this PR is itself the guidance change.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written by Claude Code, directed by the assignee, as part of a quality loop: capture every MCP SQL query with its stated intent, score them with online evaluations, fix the guidance where the scores show problems, then watch the rates move. The rules come from the internal optimizing-clickhouse-and-hogql-queries skill plus the benchmarks above. Started as a single JSONExtract rule, expanded to the full measured set, then the JSONExtract rule was dropped on the assignee's direction after we confirmed the HogQL engine already rewrites the common form to the materialized column. No repo skills were invoked for the edits themselves (markdown-only change).

[greptile-apps]

_{Reviews (1): Last reviewed commit: "fix(phai): label person_id rule correctn..." | Re-trigger Greptile}

[greptile-apps]

_{Reviews (2): Last reviewed commit: "fix(phai): drop the jsonextract dot-acce..." | Re-trigger Greptile}

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-07-14 02:24 UTC	Run
prod-us	✅ Deployed	2026-07-14 02:36 UTC	Run
prod-eu	✅ Deployed	2026-07-14 02:36 UTC	Run