Back to top

SurrealQL

SurrealQL is a powerful database query language which closely resembles traditional SQL, but with slight differences and improvements. Although it has similar syntax and similar statement types, there are a number of differences between traditional SQL and SurrealQL. For an overview of the different statement types which can be run in SurrealDB, and for the complete syntax definitions, along with example queries for all of the different statement types, take a look at the statements page.

Record IDs

In SurrealDB, document record IDs store both the table name, and the record ID.

CREATE company:surrealdb SET name = 'SurrealDB', cofounders = [person:tobie, person:jaime];

This allows for records to be retrieved without any table scans or index scans, solely by the id.

SELECT * FROM company:surrealdb;

In addition, SurrealDB record IDs allow for direct record retrieval from within interconnected record queries.

SELECT cofounders.*.name FROM company:surrealdb;

Record IDs can be both text-based or numeric.

CREATE temperature:17493 SET time = time::now(), celcius = 37.5;

Record IDs can contain complex characters, surrounded by the ` character.

CREATE article:`8424486b-85b3-4448-ac8d-5d51083391c7` SET time = time::now(), author = person:tobie;

Alternatively complex characters within record IDs can be surrounded by the and characters.

CREATE article:⟨8424486b-85b3-4448-ac8d-5d51083391c7⟩ SET time = time::now(), author = person:tobie;

No JOINs

Due to the power and flexibility which can be achieved with record IDs in SurrealDB, the need to use JOINs is removed. Instead, queries can perform complex multi-table, and multi-depth fetches, depending on the record IDs stored within each record. There is no limit to the level of fetches, and the number of different tables used within a single query. This results in a huge performance boost and eliminates the N+1 query problem, when fetching interconnected records from many different tables.

SELECT ->purchased->product<-purchased<-person->(purchased WHERE created_at > time::now() - 3w)->product FROM person:tobie;

Comments

In SurrealQL, comments can be written in a number of different ways.

/*
In SurrealQL, comments can be written as single-line
or multi-line comments, and comments can be used and
interspersed within statements.
*/

SELECT * FROM /* get all users */ user;

# There are a number of ways to use single-line comments
SELECT * FROM user;

// Alternatively using two forward-slash characters
SELECT * FROM user;

-- Another way is to use two dash characters
SELECT * FROM user;

Categories

Statements

Detailed instructions and examples on all of the different SurrealQL statements

Operators

Numerous in-built operators can be used for simple and advanced value comparison

Parameters

Parameters can be used like variables to store a other values and query results

Transactions

Use transactions to group statements together which either succeed or fail as a whole

Functions

In-built functions for checking, manipulating, and working with different types of data