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(), celsius = 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