Parameters
Parameters can be used like variables to store a value which can then be used in subsequent queries. To define a parameter in SurrealQL, use the LET statement. The name of the parameter should begin with a $ character.
Defining parameters within SurrealQL
-- Define the parameter
LET $suffix = "Morgan Hitchcock";
-- Use the parameter
CREATE person SET name = "Tobie " + $suffix;
-- (Another way to do the same)
CREATE person SET name = string::join(" ", "Jaime", $suffix);
Response[
{
"id": "person:3vs17lb9eso9m7gd8mml",
"name": "Tobie Morgan Hitchcock"
}
]
[
{
"id": "person:xh4zbns5mgmywe6bo1pi",
"name": "Jaime Morgan Hitchcock"
}
]
A parameter can store any value, including the result of a query.
-- Assuming the CREATE statements from the previous example
LET $founders = (SELECT * FROM person);
RETURN $founders.name;
Response[
"Tobie Morgan Hitchcock",
"Jaime Morgan Hitchcock"
]
Parameters can be defined using SurrealQL as shown above, or can be passed in using the client libraries as request variables.
Defining parameters within client libraries
SurrealDB's client libraries allow parameters to be passed in as JSON values, which are then converted to SurrealDB data types when the query is run. The following example show a variable being used within a SurrealQL query from the JavaScript library.
let people = await surreal.query("SELECT * FROM article WHERE status INSIDE $status", {
status: ["live", "draft"],
});
Reserved variable names
SurrealDB automatically predefines certain variables depending on the type of operation being performed. For example, $this and $parent are automatically predefined for subqueries so that the fields of one can be compared to another if necessary. Other predefined variables like $session give access to parts of the current database configuration. You should not declare new parameters of your own using the same names as the predefined variables below.
$before, $after
Represent the values before and after a mutation on a field.
CREATE cat SET name = "Mr. Meow", nicknames = ["Mr. Cuddlebun"];
UPDATE cat SET nicknames += "Snuggles" WHERE name = "Mr. Meow" RETURN $before, $after;
Response[
{
"after": {
"id": "cat:6p71csv2zqianixf0dkz",
"name": "Mr. Meow",
"nicknames": [
"Mr. Cuddlebun",
"Snuggles"
]
},
"before": {
"id": "cat:6p71csv2zqianixf0dkz",
"name": "Mr. Meow",
"nicknames": [
"Mr. Cuddlebun"
]
}
}
]
$auth
Represents the currently authenticated scope user.
DEFINE TABLE user SCHEMAFULL
PERMISSIONS
FOR select, update, delete WHERE id = $auth.id;
$event
Represents the type of table event triggered on an event.
DEFINE EVENT user_created ON TABLE user WHEN $event = "CREATE" THEN (
CREATE log SET table = "user", event = $event, created_at = time::now()
);
$input
Represents the initially inputted value in a field definition, as the value clause could have modified the $value variable.
CREATE city:london SET
population = 8900000,
year = 2019,
historical_data = [];
INSERT INTO city [
{ id: "london", population: 9600000, year: 2023 }
]
ON DUPLICATE KEY UPDATE
-- Stick old data into historical_data
historical_data += {
year: year,
population: population
},
-- Then update current record with the new input using $input
population = $input.population,
year = $input.year;
[
{
"historical_data": [
{
"population": 8900000,
"year": 2019
}
],
"id": "city:london",
"population": 9600000,
"year": 2023
}
]
$parent, $this
$this represents the current record in a subquery, and $parent its parent.
CREATE user SET name = "User1", member_of = "group1";
CREATE user SET name = "User2", member_of = "group1";
CREATE user SET name = "User3", member_of = "group1";
SELECT name,
(SELECT VALUE name FROM user WHERE member_of = $parent.member_of)
AS group_members
FROM user
WHERE name = "User1";
Response[
{
"group_members": [
"User1",
"User3",
"User2"
],
"name": "User1"
}
]
INSERT INTO person (name) VALUES ("John Doe"), ("John Doe"), ("Jane Doe");
SELECT
*,
(SELECT VALUE id FROM person WHERE $this.name = $parent.name) AS
people_with_same_name
FROM person;
Response[
{
"id": "person:hwffcckiv61ylwiw43yf",
"name": "John Doe",
"people_with_same_name": [
"person:hwffcckiv61ylwiw43yf",
"person:tmscoy7bjj20xki0fld5"
]
},
{
"id": "person:tmscoy7bjj20xki0fld5",
"name": "John Doe",
"people_with_same_name": [
"person:hwffcckiv61ylwiw43yf",
"person:tmscoy7bjj20xki0fld5"
]
},
{
"id": "person:y7mdf3912rf5gynvxc7q",
"name": "Jane Doe",
"people_with_same_name": [
"person:y7mdf3912rf5gynvxc7q"
]
}
]
$scope
Represents the name of the scope of a currently authenticated scope user.
IF $scope = "admin" THEN
( SELECT * FROM account )
ELSE IF $scope = "user" THEN
( SELECT * FROM $auth.account )
ELSE
[]
END
$session
Represents values from the session functions as an object.
CREATE user SET
name = "Some User",
on_database = (SELECT VALUE db FROM ONLY $session);
Response[
{
"id": "user:wa3ajflozlqoyurc4i4v",
"name": "Some User",
"on_database": "database"
}
]
$token
Represents values held inside the JWT token used for the current session.
DEFINE TABLE user SCHEMAFULL
PERMISSIONS FOR select, update, delete, create
WHERE $scope = "users"
AND email = $token.email;
$value
Represents the value after a mutation on a field (identical to $after in the case of an event).
DEFINE EVENT email ON TABLE user WHEN $before.email != $after.email THEN (
CREATE event SET
user = $value.id,
time = time::now(),
value = $after.email,
action = 'email_changed'
);