optimizing-sql-queries skill
Optimize slow analytical SQL by reading query/EXPLAIN plans, cutting scanned data, fixing join strategy, and using partitioning, clustering, and indexes across Postgres, Snowflake, BigQuery, Databricks/Spark SQL, and Redshift. Use when a query is slow, times out, costs too much, scans too many rows/bytes, or spills to disk.
- GitHub stars
- 27
- Files
- 2
- Last commit
- Aug 30, 2026
- License
- —
- Allowed tools
- —
What does the optimizing-sql-queries skill do?
optimizing-sql-queries is an agent skill. Optimize slow analytical SQL by reading query/EXPLAIN plans, cutting scanned data, fixing join strategy, and using partitioning, clustering, and indexes across Postgres, Snowflake, BigQuery, Databricks/Spark SQL, and Redshift. Use when a query is slow, times out, costs too much, scans too many rows/bytes, or spills to disk.
How to install the optimizing-sql-queries skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the optimizing-sql-queries skill in Plugin
/plugin marketplace add Unknown-333/awesome-data-engineering-skills /plugin install data-engineering-skills@awesome-data-engineering-skills
Install the optimizing-sql-queries skill in Claude Code
~/.claude/skills/optimizing-sql-queries/SKILL.md
$ npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries ~/.claude/skills/optimizing-sql-queriesInstall the optimizing-sql-queries skill in Claude Code (project)
.claude/skills/optimizing-sql-queries/SKILL.md
$ npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries .claude/skills/optimizing-sql-queriesInstall the optimizing-sql-queries skill in Codex
~/.agents/skills/optimizing-sql-queries/SKILL.md
$ npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries ~/.agents/skills/optimizing-sql-queriesInstall the optimizing-sql-queries skill in Gemini CLI
~/.gemini/skills/optimizing-sql-queries/SKILL.md
$ npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries ~/.gemini/skills/optimizing-sql-queriesInstall the optimizing-sql-queries skill in Claude.ai
npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries optimizing-sql-queries && zip -r optimizing-sql-queries.zip optimizing-sql-queries # claude.ai → Customize → Skills → + → Create skill → Upload a skill → optimizing-sql-queries.zip
SKILL.md
View on GitHubOptimizing SQL Queries
When to use
- A query is slow, times out, or is expensive (bytes/credits/slots scanned).
- A dashboard or model run regressed after data grew.
- You see full-table scans, large shuffles, disk spills, or exploding row counts.
- Do NOT use for query correctness bugs — this skill assumes results are correct.
Workflow
- [ ] Read the actual query/EXPLAIN plan (not guesses)
- [ ] Find the dominant cost: scan, join, aggregation, or sort/spill
- [ ] Reduce data read (predicates, partition/cluster pruning, column pruning)
- [ ] Fix join strategy (order, keys, broadcast vs shuffle, skew)
- [ ] Re-measure and confirm the plan changed
- Get the plan. Never optimize blind:
- Postgres:
EXPLAIN (ANALYZE, BUFFERS) <query> - Snowflake: Query Profile UI, or
SYSTEM$EXPLAIN_PLAN_JSON - BigQuery: execution details /
--dry_runfor bytes billed - Spark/Databricks:
df.explain("formatted")or the SQL plan tab
- Postgres:
- Identify the dominant operator by time/rows/bytes. Optimize that first; ignore cheap nodes.
- Reduce data scanned before anything else — it usually dominates cost.
- Fix the join only after the scan is minimal.
- Re-run the plan and verify the change (row estimates, join type, pruning).
Patterns
Enable partition/cluster pruning — push filters on the partition/cluster key so the engine skips files. On BigQuery/Snowflake this is the single biggest lever.
-- Good: filter on the partitioning column with a literal/range so pruning applies
SELECT user_id, SUM(amount)
FROM orders
WHERE order_date >= '2026-01-01' AND order_date < '2026-02-01' -- prunes partitions
GROUP BY user_id;
Filter before joining, not after. Reduce each side to the needed rows/columns first so the join processes less data.
Prefer explicit column lists over SELECT * in columnar warehouses — reading
fewer columns reads fewer bytes.
Choose the right join for the sizes. A small dimension joined to a large fact
should broadcast (map-side) rather than shuffle. In Spark, let Adaptive Query
Execution pick, or hint /*+ BROADCAST(dim) */.
Aggregate/pre-filter in a CTE to shrink data before an expensive window or join, rather than computing over the full table.
Common pitfalls
- Wrapping the partition key in a function (
WHERE DATE(ts) = ...) disables pruning — filter on a raw range instead. - Implicit type casts on join keys (string vs int) force full scans and block index/pruning use — align types.
SELECT DISTINCTto hide a fan-out join — fix the join grain instead; it is cheaper and correct.ORacross columns often prevents index/pruning use — rewrite asUNION ALLorIN.- Optimizing a cheap node — always target the dominant operator in the plan.
- Chasing indexes on columnar warehouses — Snowflake/BigQuery have no row-store indexes; use clustering/partitioning and result caching instead.
References
Files in this skill
2optimizing-sql-queries skill questions
How do I install the optimizing-sql-queries skill in Claude Code?
Run npx degit Unknown-333/awesome-data-engineering-skills/skills/optimizing-sql-queries ~/.claude/skills/optimizing-sql-queries. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the optimizing-sql-queries skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.