Skip to content
Skills Library
Data & analytics · Building & coding

sql-expert

/sql-expert

Expert system for generating, validating, and optimizing ClickHouse SQL. Use this when the user needs data, queries, or analysis.

Repository
datastoria ↗
Licence
Apache-2.0
Last repository change
21.07.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.07.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Expert system for generating, validating, and optimizing ClickHouse SQL. Use this when the user needs data, queries, or analysis.

Original author description

Expert system for generating, validating, and optimizing ClickHouse SQL. Use this when the user needs data, queries, or analysis.

How it works

SKILL.md has no level-two headings · 37 lines, 507 words

SKILL.md preview
---
name: sql-expert
description: Expert system for generating, validating, and optimizing ClickHouse SQL. Use this when the user needs data, queries, or analysis.
metadata:
  author: System
  disable-slash-command: true
---

> ## 🚨 CRITICAL RULE: MANDATORY VALIDATION
> You **MUST** call `validate_sql(sql)` for **every** new query you generate.
> **Context Note**: Historical validation steps are pruned to save tokens, but this does NOT excuse you from validating new queries in the current turn. Always validate before executing.

# 1. Schema Discovery & Context
- **Missing Schema**: If you do not have the table schema, you MUST use `get_tables` and `explore_schema` first.
  - *Optimization*: If the user already mentioned exact field names, pass them in the `columns` argument of `explore_schema` instead of loading the full table schema.
- **Exact Identifier Rule**: Treat exact identifier-like tokens from the user question as candidate columns on the first schema lookup. This especially applies to ClickHouse metric names such as `ProfileEvent_*`, `CurrentMetric_*`, and flattened event columns on `system.*` tables.
- **Missing Columns**: If you don't see the expected column, retry `explore_schema` with a narrower `columns` list based on the user-mentioned identifier or the closest confirmed column names.
- **Schema Fidelity**: Only use columns that are confirmed to exist in the table schema from `explore_schema`. Do not assume standard columns exist if they are not in the tool output.
- **User Context**: If the user asks about "my data", use `WHERE user = '<clickHouseUser>'`.
- **System Tables**: For queries on `system.*` tables (e.g., `system.query_log`, `system.parts`, `system.merges`), defer to the `clickhouse-system-queries` skill - it contains table-specific patterns, predicates, and resource metrics that this skill does not cover. For `system.query_log`, do not generate SQL until `references/system-query-log.md` has been loaded via `skill_resource`, and do not call `search_query_log` for chart/time-series requests.

# 2. Syntax Rules (The Grammar)
- **Tables**: ALWAYS use fully qualified names (e.g., `database.table`).
- **Semicolons**: NEVER include a trailing semicolon (`;`).
- **Enums**: Use exact string literals for Enum columns.
- **Safety**: ALWAYS use `LIMIT` for data exploration queries.

# 3. Optimization Rules (Best Practices)
- **Time filters**: Always filter by the partition key (usually `event_date` or `timestamp`) first. Use **bounded time windows** (e.g., last 24h, 7 days) unless the user asks for all history.
- **Primary Keys (CRITICAL)**: ClickHouse indexes are sparse. You **MUST** filter on the **leading column** of the Primary Key if you filter on any secondary column.
  - *Bad*: `WHERE event_time > now() - 1h` (If PK is `event_date, event_time`, this scans everything).
  - *Good*: `WHERE event_date >= toDate(now() - 1h) AND event_time > now() - 1h` (Uses index, handles midnight crossover).
- **Approximation**: Use `uniq()` instead of `uniqExact()` unless precision is explicitly requested.
- **Joins**: Put the **smaller table on the RIGHT**. Use `GLOBAL IN` only for distributed queries.

# 4. Execution Workflow
1. **Generate**: Create the SQL following the rules above.
2. **Validate (MANDATORY)**: Call `validate_sql(sql)`.
   - *If invalid*: Read the error, fix the SQL, and retry (max 3 attempts).
3. **Decide Action**:
   - *Visualization*: IF the user wants a chart, DO NOT execute. Pass the SQL to the visualization skill logic.
   - *Data*: IF the user wants answers (lists, counts), call `execute_sql(sql)`.
   - *Code Only*: IF the user asks to "write SQL", just output the code block.

Versions

RepositoryScoreLicence
This page · frankchen021/datastoria90Apache-2.0
traylinx/switchAILocal100Apache-2.0
personamanagmentlayer/pcl100Apache-2.0
miaoge-ge/coding-agent-skills100MIT
SSameer20/data-analyst-toolkit90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 9ee688ac7999 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100clickhouse-core-workflow-b
    Insert, query, and aggregate data in ClickHouse with real SQL patterns. Use when writing analytical queries, inserting data at scale, building dashboards, or implementing materialized views for pre-aggregation. Trigger with "clickhouse query", "clickhouse insert", "clickhouse…
  • 100clickhouse-query
    Run ClickHouse queries for analytics, metrics analysis, and event data exploration. Use when you need to query ClickHouse directly, analyze metrics, check event tracking data, or test query performance. Read-only by default.
  • 100clickhouse-data-handling
    Handle data lifecycle in ClickHouse — TTL expiration, data deletion (GDPR), column-level encryption, and audit logging with real ClickHouse SQL. Use when implementing data retention, fulfilling GDPR/CCPA deletion requests, or managing sensitive data in ClickHouse. Trigger with…
  • 100clickhouse-io
    ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads. Use when writing ClickHouse schemas or queries, or when an analytical query is too slow.
  • 100optimizing-clickhouse-and-hogql-queries
    Workflow for optimizing ClickHouse and HogQL queries. Use when a HogQL query, query runner, insight, or report is too slow; when a hand-written ClickHouse query (via `sync_execute` or in a migration) is too slow; when ClickHouse times out or hits memory limits; when…
  • 100data-analyst
    Act as an interactive data analyst for ClickHouse-backed analytics. Use when the user asks questions about internal data, metrics, dashboards, telemetry, active users, revenue, funnels, trends, distributions, or wants an analyst-style conversation, ad hoc SQL, charts, or a data…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.