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):

``bash 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 .surql extension.
• SurrealQL is a relatively young language and changes between releases. Default to the latest SurrealDB version (see [Version & Documentation](#version--documentation)) and refer to https://surrealdb.com/docs for the most up-to-date syntax.

Statements

Query Statements

Schema & Resource Statements

Control Flow Statements

References

For detailed querying patterns (filtering, graph traversal, aggregation, subqueries), see [references/querying.md](references/querying.md).

For schema management patterns (tables, fields, indexes, events, access), see [references/schema.md](references/schema.md).

For in-depth information about the values that can be stored in SurrealDB records, see [references/values.md](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 .surql files

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