All skills
clickhouse avatar

/clickhouse-best-practices

@d284161 official
by clickhouseclickhouse/agent-skills543 stars
39

MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 31 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.

Use this Skill: https://skilld.dev/gh/clickhouse/agent-skills/clickhouse-best-practices

This session only. Nothing lands on disk.

rulesschema-pk-filter-on-orderby.md

≈396 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Filter on ORDER BY Columns in Queries

Impact: CRITICAL

Even with good schema design, queries must use ORDER BY columns to benefit. Skipping prefix columns or filtering on non-ORDER BY columns prevents index usage.

Incorrect (skips prefix or uses non-ORDER BY columns):

-- Given: ORDER BY (tenant_id, event_type, timestamp)

-- Skips prefix columns - can't use index effectively
SELECT * FROM events WHERE event_type = 'click';

-- Filter on column not in ORDER BY - full table scan
SELECT * FROM events WHERE user_agent LIKE '%Chrome%';

Correct (uses ORDER BY prefix):

-- Given: ORDER BY (tenant_id, event_type, timestamp)

-- Full prefix match - best performance
SELECT * FROM events
WHERE tenant_id = 123 AND event_type = 'click';

-- Partial prefix - still uses index
SELECT * FROM events WHERE tenant_id = 123;

-- Range on later column after equality on earlier
SELECT * FROM events
WHERE tenant_id = 123 AND event_type = 'click' AND timestamp >= '2024-01-01';

Index usage reference:

Filter Index Used?
WHERE tenant_id = 123 Full
WHERE tenant_id = 123 AND event_type = 'click' Full
WHERE event_type = 'click' None (skipped prefix)
WHERE timestamp > '2024-01-01' None (skipped both)

Reference: Choosing a Primary Key

Source: SKILL.md on GitHub

No alerts17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill provides comprehensive best practices for ClickHouse database management, including schema design, query optimization, and ingestion strategies. It includes robust safety guardrails for AI agents, such as mandatory query limits, execution timeouts, and a structured schema discovery workflow. All external references and tools trace back to official ClickHouse vendor resources.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    8/34 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at d284161. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 5 months ago
metadata
{
  "author": "ClickHouse Inc",
  "version": "0.4.0"
}

README badge

README badge for clickhouse/agent-skills/clickhouse-best-practices

Provides 31 ClickHouse-specific rules organized by priority across schema design, query optimization, data ingestion, and agent connectivity. Use this skill to validate schemas, review queries, and establish safe agent workflows with proper connection setup, schema discovery, and query safety procedures.

Generated from the current SKILL.md.

When should I use this skill?
Use this skill when reviewing ClickHouse schemas, queries, or data ingestion strategies. It contains 31 rules covering primary key design, data types, JOINs, partitioning, and insert batching that you must check before providing ClickHouse recommendations.
Does this skill help with AI agent connectivity to ClickHouse?
Yes. The skill includes rules for MCP and CLI connection setup, schema discovery workflows, and query safety (LIMIT, timeouts, progressive exploration) specific to AI agents querying ClickHouse.
What should I do if a rule doesn't exist for my question?
Fall back to the LLM's ClickHouse knowledge, search the official ClickHouse documentation, or use web search. Always cite your source in the response.
Are the rules mandatory or advisory?
The rules are mandatory checks before answering ClickHouse questions. They encode ClickHouse-specific behaviors (columnar storage, merge tree mechanics, sparse indexes) where general database intuition can be misleading.
Can I use this skill for INSERT performance tuning?
Yes. The skill covers batch sizing (10K-100K rows), async inserts for high-frequency small batches, mutation avoidance (ReplacingMergeTree instead of ALTER UPDATE), and OPTIMIZE TABLE risks.

Generated from the current SKILL.md. These answers refresh after source changes.