surrealdb SurrealQL
A skill for writing and modifying SurrealQL queries to interact with SurrealDB databases.
SurrealQL is the official query language for SurrealDB. It is a modern, flexible, and powerful query language that is designed to be easy to learn and use.
When to use this skill
Reference these guidelines when:
- Writing, modifying, or troubleshooting SurrealQL queries
- Designing or managing schemas
- Converting other query languages to SurrealQL
Version & Documentation
Always target the latest stable SurrealDB release. SurrealQL evolves between major versions, and syntax from older releases (e.g. SurrealDB 2.x) is a common source of incorrect, non-validating queries. Unless the user explicitly asks for an older version, generate current (3.x) syntax.
Determine the active version before generating version-sensitive syntax:
If the SurrealDB CLI is installed, run
surreal version.Otherwise, the latest released version is published as a plain string at
https://download.surrealdb.com(e.g.v3.1.4):curl -s https://download.surrealdb.com
https://surrealdb.com/docs always documents the latest stable release —
treat it as the source of truth for current syntax. When in doubt about whether
a function or form still applies (for example type::* helpers and how record
IDs are constructed), confirm against the current docs rather than assuming
older behavior.
Rules & Conventions
- SurrealQL is NOT ANSI-SQL. Never assume SQL knowledge from other databases applies. Always refer to the examples below or the documentation at https://surrealdb.com/docs for accurate syntax and behavior.
- When SurrealQL is stored in a file, it should have a
.surqlextension. - SurrealQL is a relatively young language and changes between releases. Default to the latest SurrealDB version (see Version & Documentation) and refer to https://surrealdb.com/docs for the most up-to-date syntax.
Statements
Query Statements
| Statement | Purpose |
|---|---|
| SELECT | Query records, traverse graphs, aggregate data |
| CREATE | Create new records (errors if record exists) |
| INSERT | Insert one or more records or graph edges; supports ON DUPLICATE KEY UPDATE |
| UPDATE | Update existing records (no-op if record doesn't exist) |
| UPSERT | Insert a record, or update it if it already exists |
| DELETE | Delete records or graph edges |
| RELATE | Create graph edges between records |
| LIVE SELECT | Stream real-time changes to a table |
| KILL | Cancel an active LIVE SELECT query |
| LET | Assign a value to a parameter |
| RETURN | Return a value from a block or function |
Schema & Resource Statements
| Statement | Purpose |
|---|---|
| DEFINE NAMESPACE | Define a namespace |
| DEFINE DATABASE | Define a database |
| DEFINE TABLE | Define a table (schemafull, schemaless, as view) |
| DEFINE FIELD | Define a field with type, default, assertion |
| DEFINE INDEX | Define an index (unique, search, vector) |
| DEFINE EVENT | Define event triggers on a table |
| DEFINE FUNCTION | Define a custom function |
| DEFINE ANALYZER | Define a search analyzer |
| DEFINE ACCESS | Define authentication access methods (Bearer, JWT, Record) |
| DEFINE API | Define an API endpoint |
| DEFINE BUCKET | Define a storage bucket |
| DEFINE CONFIG | Define a configuration |
| DEFINE MODULE | Define a Surrealism extension module |
| DEFINE PARAM | Define a global parameter |
| DEFINE SEQUENCE | Define an auto-incrementing sequence |
| DEFINE USER | Define a system user |
| ALTER | Alter an existing resource definition |
| REMOVE | Remove any defined resource |
| REBUILD | Rebuild an index |
| ACCESS | Manage access grants |
| USE | Switch to a different namespace or database |
| INFO | Inspect definitions for a resource |
| SHOW | View changefeed for a table or database |
Control Flow Statements
| Statement | Purpose |
|---|---|
| BEGIN / COMMIT | Begin and commit a manual transaction |
| CANCEL | Cancel a transaction |
| IF / ELSE | Conditional execution |
| FOR | Iterate over values |
| BREAK | Exit a FOR loop early |
| CONTINUE | Skip to next iteration in a FOR loop |
| THROW | Cancel execution and return an error |
| SLEEP | Pause execution for a duration |
References
For detailed querying patterns (filtering, graph traversal, aggregation, subqueries), see references/querying.md.
For schema management patterns (tables, fields, indexes, events, access), see references/schema.md.
For in-depth information about the values that can be stored in SurrealDB records, see references/values.md.
Validation
When generating SurrealQL queries, or modifying existing queries, you should always validate them using the SurrealDB CLI if available. Validation may fail to due version differences, at which point you can retrieve your SurrealDB CLI version with surreal version. Validation can only be performed against full queries or values, not partial or fragmentary statements.
Usage
# Validate a single file:
surreal validate query.surql
# Validate glob pattern of files:
surreal validate queries/*.surql
# Validate from stdin (available since SurrealDB v3.1.0):
echo "SELECT * FROM person WHERE age > 18" | surreal validate --stdin
Formatting
When generating SurrealQL queries or SQON values you may decide to format them using the surqlfmt CLI tool if a NodeJS-like runtime is available. Situations in which you should always format include:
- When presenting queries to users
- When generating migration files
- When writing
.surqlfiles
Usage
# Format a file and print to stdout:
npx @surrealdb/surql-fmt query.surql
# Format files in-place:
npx @surrealdb/surql-fmt --write migrations/*.surql
# Check if files are already formatted (exits with code 1 if not):
npx @surrealdb/surql-fmt --check src/**/*.surql
# Format from stdin:
echo "SELECT * FROM person WHERE age>18" | npx @surrealdb/surql-fmt --stdin