mcpField
Q
query-validation

query-validation

github.com/nimrodfisherData & databases504228 installsUpdated 5w ago
Repository

About query-validation

A SQL review skill for analysts and data teams preparing queries for production or investigating unexpected results and slow performance. It combines linting, anti-pattern checks, explain-plan parsing, and engine-specific guidance in a structured review.

Key features

  1. 01Lints SQL for syntax and engine compatibility
  2. 02Flags query anti-patterns with severity
  3. 03Parses explain plans for slow steps
  4. 04Estimates join cardinality when schema stats exist
  5. 05Produces review and optimization recommendations

Use cases

  1. 01Reviewing queries before dashboard or report release
  2. 02Investigating surprising query results
  3. 03Finding performance issues and rewrite options

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nimrodfisher/data-analytics-skills --skill query-validation

After installing, type/query-validationin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
optimization_recommendations.md
query_review_template.md
references/
engine_specific_guide.md
sql_anti_patterns.md
scripts/
cardinality_estimator.py
explain_plan_parser.py
sql_lint.py

Details

From the project README

When to use

  • A SQL query is about to be promoted to a production dashboard or report
  • A query is returning surprising or incorrect results
  • A query is running slowly and needs performance review
  • You want to catch anti-patterns (implicit conversions, SELECT *, unbounded CTEs) before they cause incidents

Process

  1. Lint the query — run scripts/sql_lint.py (sqlglot-based) to catch syntax errors, unsupported functions for the target engine, and style violations. Fix hard errors before continuing.
  2. Review anti-patterns — compare the query structure against references/sql_anti_patterns.md. Flag any present anti-patterns with a severity rating.
  3. Parse the explain plan — if an EXPLAIN or query profile output is available, run scripts/explain_plan_parser.py to extract slow steps (full table scans, missing indexes, high row estimates).
  4. Estimate cardinality — run scripts/cardinality_estimator.py if schema stats are available to flag joins that might fan-out unexpectedly.
  5. Check engine-specific behaviour — consult references/engine_specific_guide.md for the target engine (Snowflake / BigQuery / Postgres / Redshift) to verify date functions, window behaviour, and clustering assumptions.
  6. Produce review output — fill in assets/query_review_template.md with findings; for any performance issues found, complete assets/optimization_recommendations.md.

Inputs the skill needs

  • Required: the SQL query text
  • Required: target database engine (Snowflake / BigQuery / Postgres / Redshift / other)
  • Optional: relevant table schemas (column names, types, approximate row counts)
  • Optional: EXPLAIN / query profile output
  • Optional: expected business logic — what should the query calculate?

Output

  • assets/query_review_template.md (filled) — categorised findings: correctness, performance, style
  • assets/optimization_recommendations.md (filled, if issues found) — ranked rewrite suggestions with expected impact

Comments

Markdown supported