# surrealql-performance

Скилл для ИИ-агентов, который подсказывает, как ускорить запросы SurrealDB: структура record ID, индексы, вычисляемые поля. Пригодится, когда запрос тормозит или сканирует лишние записи.

- скилл · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 416 установок · ★ 28
- Автор: surrealdb
- Лицензия: MIT · policy=mirror · начало файла — в конце страницы
- Исходник: https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealql-performance/SKILL.md
- Обновлён: 2026-09-29
- HTML: https://affpapa.org/nevibecode/skills/surrealql-performance

## Что делает

Скилл разбирает три вещи: как проектировать record ID и ключи под доступ к данным, как выбирать индексы и как не пересчитывать одно и то же на каждом чтении. Внутри — три справочника: `references/keys.md` про локальность и range-сканы, `references/indexing.md` про типы индексов и порядок полей в составном, `references/computed-fields.md` про вычисляемые поля, вьюхи и события.

Главная мысль простая: record ID хранятся в отсортированном порядке, поэтому самый избирательный компонент ставят первым, а диапазон берут через `SELECT * FROM person:1..1000`, а не через `WHERE` по ID. Индекс нужен только там, где вы фильтруете, сортируете или джойните — каждый лишний добавляет стоимость записи. Проверять, что индекс реально используется, скилл советует через `EXPLAIN` или `EXPLAIN FULL`.

Скилл рассчитан на последнюю стабильную версию SurrealDB, а синтаксис вроде диапазонов записей, `COMPUTED` и опций `FULLTEXT` просит сверять с документацией и проверять примеры через `surreal validate`. Если вы застряли на старой версии, часть примеров может не пройти — это повод проверить синтаксис до того, как тащить его в прод.

## Установка

### Claude Code (родная платформа)

1. **Через Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealql-performance -a claude-code
```

2. **Вручную: положить файлы**
- Файл: `~/.claude/skills/surrealql-performance/SKILL.md` — Папка скилла целиком; для одного проекта — .claude/skills/surrealql-performance/

### Codex

1. **Через Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealql-performance -a codex
```

2. **Вручную: положить файлы**
- Файл: `.agents/skills/surrealql-performance/SKILL.md` — Для всех проектов — ~/.agents/skills/

### Cursor

1. **Через Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealql-performance -a cursor
```

2. **Вручную: положить файлы**
- Файл: `.cursor/skills/surrealql-performance/SKILL.md` — Cursor читает и .agents/skills/, и .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install surrealdb/agent-skills surrealql-performance
```

2. **Вручную: положить файлы**
- Файл: `.github/skills/surrealql-performance/SKILL.md`

### Gemini CLI

1. **Через Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealql-performance -a gemini-cli
```

2. **Командой платформы**
```bash
gemini skills install https://github.com/surrealdb/agent-skills --path skills/surrealql-performance
```

### Windsurf (Devin Desktop)

**Вручную: положить файлы**
- Файл: `.devin/skills/surrealql-performance/SKILL.md` — Старый путь .windsurf/skills/ тоже читается

### OpenCode

**Через Skills CLI (Vercel)**
```bash
npx skills add surrealdb/agent-skills --skill surrealql-performance -a opencode
```

### Claude.ai

**Claude.ai**
- Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills

Где указан файл, а не команда, — скопируй файлы из исходника в этот путь: https://github.com/surrealdb/agent-skills/tree/HEAD/skills/surrealql-performance/SKILL.md

## Когда брать
- понять, почему запрос сканирует всю таблицу
- разложить record ID так, чтобы range-сканы работали
- выбрать между обычным, `UNIQUE`, `FULLTEXT` и векторным индексом
- убедиться через `EXPLAIN`, что индекс действительно задействован
- решить, хранить вычисляемое значение или считать на чтении

## Примеры запросов агенту
- Запрос по таблице person идёт медленно, посмотри план и скажи, какой индекс нужен
- Помоги спроектировать record ID для погодных записей, чтобы выборки по городу и дате шли по ключу
- Стоит ли вынести этот агрегат в `DEFINE TABLE ... AS SELECT` или считать на чтении?

## Похожие
- [mongodb-performance-advisor](https://affpapa.org/nevibecode/agents/mongodb-performance-advisor.md) — субагент · 223 установки
- [postgresql-database-engineering](https://affpapa.org/nevibecode/skills/postgresql-database-engineering.md) — скилл · 1800 установок
- [database-query-optimization](https://affpapa.org/nevibecode/skills/database-query-optimization.md) — скилл · 586 установок
- [qdrant-performance-optimization](https://affpapa.org/nevibecode/skills/qdrant-qdrant-performance-optimization.md) — скилл · 1700 установок
- [database-performance-debugging](https://affpapa.org/nevibecode/skills/database-performance-debugging.md) — скилл · 493 установки
- [magento-performance-analyst](https://affpapa.org/nevibecode/skills/magento-performance-analyst.md) — скилл · 427 установок

Из того же набора: [surrealdb/agent-skills](https://affpapa.org/nevibecode/by/surrealdb/agent-skills.md) — 5 карточек

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md