surrealql-performance
Optimize SurrealDB performance through record ID and key design, indexing strategy, and computed/derived fields. Use when queries are slow, when designing record IDs for locality and range scans, choosing between standard/unique/full-text/vector indexes, verifying index usage with EXPLAIN, or deciding whether to precompute values with computed fields, views, or events. Triggers: slow query, performance, record id design, range scan, DEFINE INDEX, EXPLAIN, computed field, FUTURE, DEFINE TABLE AS SELECT.
- Installs
- 422
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/surrealdb/agent-skills --skill surrealql-performance- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads surrealql-performance automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
SurrealQL Performance
Techniques for making SurrealDB queries fast: structuring record IDs and keys for data locality, choosing and verifying the right indexes, and precomputing values with computed fields and views instead of recomputing them on every read.
Target the latest stable SurrealDB release. Confirm version-sensitive syntax
(record ranges, COMPUTED fields, FULLTEXT index options) against
https://surrealdb.com/docs, and validate examples with surreal validate. See
the surrealql skill for version detection.
When to use this skill
- A query is slow or scans more records than expected
- Designing record IDs to support efficient lookups and range scans
- Choosing between standard,
UNIQUE, full-textSEARCH, or vector indexes - Confirming whether an index is actually used (
EXPLAIN) - Deciding whether to store a derived value vs. compute it on read
Topic map
| Topic | Reference |
|---|---|
| Record ID & key structuring for locality and range scans | references/keys.md |
| Index types, composite order, verifying usage, rebuild cost | references/indexing.md |
| Computed fields, precomputed views, event-maintained values | references/computed-fields.md |
Top rules
- Design IDs for access patterns. Record IDs are stored in sorted order. Put
the most selective, range-friendly component first (e.g.
weather:['London', d'2025-02-13T05:00Z']) so related records sit together and range queries avoid full-table scans. See references/keys.md. - Prefer record ranges over
WHEREon the ID.SELECT * FROM person:1..1000uses key ordering directly; filtering withWHEREafter a full scan does not. - Index the fields you filter, sort, or join on — but no more. Every index adds write cost. Order composite index fields from most to least selective and to match your query's filter/sort order. See references/indexing.md.
- Verify, don't assume. Run
EXPLAIN(orEXPLAIN FULL) to confirm a query uses the index you expect before concluding it is optimized. - Precompute expensive, read-heavy values. Use computed fields, a
DEFINE TABLE ... AS SELECTview, or aDEFINE EVENTto maintain derived data rather than recomputing aggregates on every query. See references/computed-fields.md. - Use bound parameters. Parameterized queries are safer and let the engine reuse query plans.
FAQ
What does the surrealql-performance skill do?
Optimize SurrealDB performance through record ID and key design, indexing strategy, and computed/derived fields. Use when queries are slow, when designing record IDs for locality and range scans, choosing between standard/unique/full-text/vector indexes, verifying index usage with EXPLAIN, or deciding whether to precompute values with computed fields, views, or events. Triggers: slow query, performance, record id design, range scan, DEFINE INDEX, EXPLAIN, computed field, FUTURE, DEFINE TABLE AS SELECT.
How do I install surrealql-performance?
Run npx skills add https://github.com/surrealdb/agent-skills --skill surrealql-performance in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/surrealql-performance/ (personal) or .claude/skills/surrealql-performance/ (project).
Which AI agents can use surrealql-performance?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is surrealql-performance safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains surrealql-performance?
It is published by surrealdb in surrealdb/agent-skills. It has 422 recorded installs.
More from surrealdb/agent-skills
surrealql
surrealdb/agent-skills
Generate and modify SurrealQL queries to interact with SurrealDB databases. This includes creating and retrieving records, designing and managing schemas, establishing and querying graph relationships, performing live (real-time) queries, and leveraging all unique SurrealQL features for advanced database workflows. Use this skill whenever users need to write, adapt, or troubleshoot SurrealQL statements.
surrealdb-vector
surrealdb/agent-skills
Vector search with SurrealDB using HNSW indexes, KNN queries, and similarity scoring. Use when creating vector indexes, querying vectors with KNN distance operators, building semantic search or RAG pipelines, tuning HNSW parameters (EFC, M, M0, distance function, type), or implementing recommendation systems with SurrealDB. Triggers: HNSW, vector, embedding, KNN, cosine, euclidean, semantic search, RAG, vector::distance.
surrealdb-python
surrealdb/agent-skills
Using SurrealDB with the Python SDK, covering both client/server mode (WebSocket) and embedded mode (in-memory or file-based). Use when connecting to SurrealDB from Python, using the surrealdb Python package, running SurrealDB embedded without a server, or performing CRUD operations from Python code. Triggers: surrealdb Python, Surreal(), AsyncSurreal(), Python SDK, embedded SurrealDB, mem://, file://.
surrealql-functions
surrealdb/agent-skills
Open the skill to read its SKILL.md instructions.
surrealkit
surrealdb/agent-skills
Open the skill to read its SKILL.md instructions.
surrealdb-cli
surrealdb/agent-skills
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.