К основному содержанию
скилл CX Codex

query-optimization — скилл для Claude Code

Скилл query-optimization разбирает медленные T-SQL-запросы в SQL Server и Azure SQL: сначала схема и план, потом переписывание, индексы или хинты.

MIT 194 установок ★ 66 обновлён 2026-06-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill query-optimization -a claude-code
Открыть на GitHub

Что делает query-optimization

Скилл ведёт агента по фиксированному порядку. Сначала проверяет версию SQL Server, уровень совместимости, DDL таблиц, типы данных, индексы, статистику и число строк. Потом ищет узкое место по фактическому плану и STATISTICS IO, TIME, а не по процентам в оценке.

Внутри SKILL.md лежит таблица «плохой предикат → безопасный вариант», шаблоны переписывания под конкретную ситуацию и playbook по parameter sniffing с оговорками для OPTION (RECOMPILE), OPTIMIZE FOR и хинтов Query Store. Удаление join принимается только с доказательством через EXCEPT в обе стороны. Для детального разбора .sqlplan скилл подгружает tsql-master:execution-plan-analysis.

Если нет текста запроса, DDL, значений параметров или плана, на выходе будут диагностика и условные советы. Готовый рецепт в таком случае не выдаётся. Отдельно сверяются типы колонок временных таблиц: расхождение в длине строки или collation ломает весь анализ плана и рекомендации по индексам.

Какие задачи решает

  • разобрать медленный T-SQL запрос по фактическому плану
  • убрать не-SARGable предикат и вернуть seek вместо scan
  • доказать, что join можно удалить, через EXCEPT в обе стороны
  • согласовать типы колонок временной таблицы с исходными
  • выбрать между RECOMPILE, OPTIMIZE FOR и хинтом Query Store

Примеры запросов агенту

  • Запрос на Sales.Orders стал медленнее после релиза — посмотри фактический план и скажи, где теряются строки.
  • Проверь, можно ли убрать join с Customers, и докажи результат через EXCEPT в обе стороны.
  • Сверь типы колонок временной таблицы #Stage с исходными таблицами, прежде чем вешать на неё индекс.

Как установить query-optimization

1Через Skills CLI (Vercel)

npx skills add JosiahSiegel/claude-plugin-marketplace --skill query-optimization -a claude-code

2Вручную: положить файлы

~/.claude/skills/query-optimization/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/query-optimization/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о query-optimization

Как установить query-optimization в Claude Code?

Выполните npx skills add JosiahSiegel/claude-plugin-marketplace --skill query-optimization -a claude-code, файл скилла окажется по пути ~/.claude/skills/query-optimization/SKILL.md.

Что делает query-optimization?

Проводит агента через разбор медленного T-SQL: проверка схемы и типов, поиск узкого места по плану, правка SARGability, шаблоны переписывания и разбор parameter sniffing.

Что нужно, чтобы получить готовую рекомендацию, а не условную?

Версия SQL Server и уровень совместимости, полный текст запроса со значениями параметров, DDL таблиц и временных таблиц, список индексов и фактический план выполнения.

Исходный текст

SKILL.md · MIT
---
name: query-optimization
description: |
  This skill should be used when the user asks to optimize slow T-SQL queries, fix SQL Server performance regressions, improve SARGability, rewrite joins, prove whether joins can be removed, compare temp-table data types, select rewrite templates, diagnose parameter sniffing, evaluate query hints, inspect statistics/cardinality estimates, reduce spills or memory grants, use Query Store, or interpret plan evidence. PROACTIVELY activate for slow queries, scans vs seeks, implicit conversions, bad joins, tempdb spills, query rewrites, partition predicate safety, and before recommending indexes or hints.
  Provides: evidence-first workflow, rewrite templates, parameter-sniffing playbook, and gating rules before recommending indexes or hints.
---

# Query Optimization

Comprehensive guide to T-SQL query optimization for SQL Server and Azure SQL Database. Optimize from verified evidence: schema, data types, indexes, row counts, partitioning, execution plans, and allowed change types.

## Mandatory Workflow

### 1. Schema-First Validation

Before recommending rewrites, indexes, or hints, verify or mark unknown:

- SQL Server version, edition, compatibility level, and Azure SQL tier if applicable.
- Full query/procedure text, parameter values, frequency, and runtime target.
- DDL for tables, views, temp tables, table variables, and TVFs.
- Data types for join, filter, grouping, ordering, and temp-table columns, including length, precision, scale, collation, and nullability.
- Existing indexes, constraints, statistics age, partition function/scheme, and row counts.
- Whether objects are local or linked-server/remote sources.
- Allowed change types: query rewrite, new index, huge-table index change, stats update, staging table, computed column, or no code change.

Use `../_shared/optimization-intake.md` and `../_shared/assumption-tracker.md`. If key facts are missing, provide conditional guidance plus diagnostics instead of final prescriptions.

### 2. Identify the Root Bottleneck

Use actual execution plans and `STATISTICS IO, TIME` when possible. Rank findings by measured impact, not just estimated plan percentage:

- High logical reads or row reads.
- Bad estimate vs actual row gaps.
- Scans caused by non-SARGable predicates or missing access paths.
- Key lookups multiplied by many executions.
- Sort/hash/window spills from poor estimates or missing order.
- Remote queries that fail to push predicates or joins to the linked server.

For detailed `.sqlplan` inspection, load `tsql-master:execution-plan-analysis`.

### 3. Fix SARGability and Type Mismatches

SARGable predicates can use ordered index access. Avoid functions or conversions on indexed columns.

| Non-SARGable | Safer pattern |
|---|---|
| `WHERE YEAR(OrderDate) = 2026` | `WHERE OrderDate >= '20260101' AND OrderDate < '20270101'` |
| `WHERE LEFT(Name, 3) = 'ABC'` | `WHERE Name LIKE 'ABC%'` |
| `WHERE Amount * 1.1 > 1000` | `WHERE Amount > 1000 / 1.1` |
| `WHERE CONVERT(date, Dt) = @d` | `WHERE Dt >= @d AND Dt < DATEADD(day, 1, @d)` |
| `WHERE VarcharCol = 123` | `WHERE VarcharCol = '123'` |

Check actual data types. A syntactically SARGable predicate can still scan if a parameter, temp column, or join key has the wrong type or collation.

### 4. Prove Join Changes

Never remove or replace joins only because selected columns come from one table. Prove:

- **Does the join filter rows?** Compare base count vs joined count and check trusted foreign keys.
- **Does the join multiply rows?** Check uniqueness on the joined key and duplicates in the referenced table.
- **Can it be replaced with `EXISTS`?** Use a semi-join when only existence is needed and row multiplication must be avoided.
- **Are outer joins preserved?** Predicates in `WHERE` can accidentally convert `LEFT JOIN` to inner join.

Move join-removal experiments into a proof harness and validate equivalence with `EXCEPT` in both directions. See `references/rewrite-proof-harnesses.md`.

### 5. Check Temp Tables and Staging Types

Temp tables are often the right optimization tool, but bad types can create hidden conversions.

Before using or recommending a temp table:

- Compare staged column types against source metadata.
- Match string length and collation for join/filter columns.
- Match numeric precision/scale and date/time precision.
- Add appropriate clustered or nonclustered indexes after load when row counts justify them.
- Update temp-table statistics when phased optimization depends on accurate cardinality.

Flag mismatches as first-order findings because they can invalidate plan analysis and index recommendations. Use the checker in `references/rewrite-proof-harnesses.md`.

### 6. Select the Rewrite Template

Choose the least invasive rewrite that addresses the verified bottleneck:

| Situation | Template |
|---|---|
| Highly selective predicate before huge joins | Stage selective keys first, index the stage, then join. |
| Huge detail table aggregated later | Aggregate early if grouping preserves semantics. |
| Join only tests existence | Replace row-producing join with `EXISTS`. |
| OR across different columns | Split into `UNION ALL` branches with duplicate guards. |
| Catch-all optional predicates | Dynamic SQL or targeted recompilation; avoid `Col = @p OR @p IS NULL` for hot paths. |
| Unsafe partition predicate | Rewrite to direct typed range on partition column. |
| Bad estimates from table variables/TVFs | Use temp tables, inline TVFs, or recompile depending on version and workload. |

Do not stage huge unfiltered tables or aggregate early unless the row reduction and semantic equivalence are proven.

## Parameter Sensitivity

Parameter sniffing occurs when a plan compiled for one value is reused for a very different value. Confirm skew and compile/runtime values before applying fixes.

| Option | Best for | Caution |
|---|---|---|
| `OPTION (RECOMPILE)` | Infrequent or highly variable statements | Adds compile CPU; plan not reused. |
| `OPTIMIZE FOR (@p = value)` | Stable representative value | Can age badly as data changes. |
| `OPTIMIZE FOR UNKNOWN` | Average distribution is acceptable | Can be mediocre for all cases. |
| Dynamic SQL | Optional predicates and varied shapes | Requires safe parameterization. |
| Query Store hints | SQL Server 2022+ or Azure SQL, no code change | Monitor regressions. |
| PSP optimization | SQL Server 2022+ with compatibility 160 | Only applies to eligible patterns. |

## Execution Plan Checks

Watch these operators and warnings:

| Plan evidence | Likely action |
|---|---|
| Scan with residual predicate | Fix SARGability, key order, or filtered index. |
| Seek with high rows read | Add more selective key columns or rewrite residual predicate. |
| Key lookup repeated many times | Cover query or reduce outer rows first. |
| Sort spill or hash spill | Fix estimates, reduce rows/width, add order-compatible index. |
| `CONVERT_IMPLICIT` on column | Align parameter/temp/source data types. |
| Estimate off by 10x+ | Check stats, skew, table variables, predicates, constraints. |
| Missing-index warning | Treat as candidate only; merge with existing indexes and workload. |

## Statistics and Cardinality

Use statistics work when evidence points to stale or insufficient estimates:

```sql
DBCC SHOW_STATISTICS('dbo.TableName', 'IndexOrStatsName');
UPDATE STATISTICS dbo.TableName IndexOrStatsName WITH FULLSCAN;
```

For large partitioned tables, evaluate incremental statistics and filtered stats. Do not run broad fullscan updates in production without maintenance-window and blocking considerations.

## Output Format

Respond with:

1. **Intake status**: verified, unverified, disproved, needs diagnostic.
2. **Bottleneck evidence**: plan nodes, reads, rows, estimates, warnings.
3. **Recommendation path**: rewrite, index/stat change, or diagnostic, separated by allowed change type.
4. **Proof harness**: result equivalence and before/after performance metrics.
5. **Risks**: parameter sensitivity, write overhead, blocking, partition safety, remote pushdown.

## References

- `../_shared/optimization-intake.md` - mandatory intake checklist.
- `../_shared/assumption-tracker.md` - assumption status protocol.
- `references/rewrite-proof-harnesses.md` - join proof, temp type checker, and rewrite templates.
- `references/dmv-diagnostic-queries.md` - DMV queries for performance analysis.

© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace

Похожие скиллы

Все скиллы по теме «Данные и базы» →
database-query-optimization aj-geddes Скилл database-query-optimization для Claude Code и других агентов разбирает медленные SQL-запросы: индексы, планы выполнения, узкие места. Анализирует базы с высокой нагрузкой на CPU. CX Codex +1 594установок mongodb-query-optimizer mongodb Скилл mongodb-query-optimizer для Claude Code и Codex, анализирует медленные запросы MongoDB и подбирает индексы. Запускается когда вы спрашиваете, почему запрос медленный или как его ускорить. CX Codex +1 7 700установок sql-query-optimization aj-geddes Скилл sql-query-optimization для Claude Code, Cursor, Codex и других платформ — анализирует медленные SQL-запросы и переписывает их быстрее. Запускается по требованию для PostgreSQL и MySQL. CX Codex +1 529установок sql-query-optimizer patricio0312rev Скилл sql-query-optimizer для Claude Code разбирает планы выполнения SQL, предлагает индексы и переписывает запросы. Находит причины медленных запросов. CX Codex +1 297установок platform-soql-query forcedotcom Скилл platform-soql-query пишет и оптимизирует запросы SOQL/SOSL в Salesforce: от формулировки на естественном языке до анализа селективности и плана запроса. CX Codex +1 7 200установок query-expert jamesrochabrun Скилл query-expert помогает писать и ускорять запросы к SQL и NoSQL базам: разбор EXPLAIN, подбор индексов, переписывание медленных выборок. CX Codex +1 227установок

Из того же набора96

Весь набор →
windows-path-troubleshooting Скилл windows-path-troubleshooting объясняет, как записывать пути Windows для Read, Write и Edit и как перевести путь из Git Bash, чтобы не ловить ENOENT. CX Codex +1 199установок viral-video-animated-captions Скилл viral-video-animated-captions собирает вшитые в видео субтитры со словной подсветкой и анимацией в духе CapCut: таймкоды Whisper идут в ASS, FFmpeg прожигает их в ролик. CX Codex +1 196установок ffmpeg-audio-processing Скилл ffmpeg-audio-processing для Claude Code выбирает кодек, извлекает аудиодорожку из видео и нормализует громкость по EBU R128 через ffmpeg. Обрабатывает звук для подкастов и эфирных мастеров. CX Codex +1 195установок powershell-security Скилл powershell-security настраивает безопасное окружение PowerShell: защищает учётные данные через SecretManagement, развёртывает конечные точки JEA и настраивает политики WDAC. CX Codex +1 194установок ffmpeg-kinetic-captions Скилл ffmpeg-kinetic-captions для Claude Code собирает анимированные субтитры в ASS для вертикальных видео. Слова растут на караоке-подсветке, подпрыгивают и трясутся в роликах TikTok, Shorts и Reels. CX Codex +1 193установок docker-platform-guide Скилл docker-platform-guide для Claude и других агентов: разбирает отличия Docker на Windows, Linux и macOS и подсказывает, что менять в командах и настройках. CX Codex +1 192установок tsql-functions Скилл tsql-functions для Claude Code — справочник функций T-SQL для SQL Server и Azure SQL Database с категориями и версиями. Включается при работе с запросами T-SQL. CX Codex +1 187установок viral-video-short-form Скилл viral-video-short-form для Claude Code помогает готовить короткие видео для TikTok, Reels и YouTube Shorts. Включается при работе над хуками, подписями и стратегией публикаций. CX Codex +1 186установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой