Parameters

Parameters

Parameters can be used like variables to store a value which can then be used in a subsequent query. A parameter can store any value, including the result of a query. Parameters can be defined within the SQL, or can be passed in using the client libraries as request variables.

Defining parameters within SurrealQL

To define a parameter in SurrealQL, use the LET statement. The name of the parameter should begin with a $ character.

-- Define the parameter
LET $name = "tobie";
-- Use the parameter
CREATE person SET name = $name;

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 uses predefined variables. For that purpose, you can use those variables inside your query but you cannot declare new parameters using one of the following name:

Name		Description
$auth		Represents the currently authenticated scope user
$token		Represents values held inside the JWT token used for the current session
$Scope		Represents the name of the scope of a currently authenticated scope user.
$session		Represents values from the session functions as an object
$before		Represents the value before a mutation on a field
$after		Represents the value after a mutation on a field
$value		Represents the value after a mutation on a field (identical to $after in the case of an event)
$input		Represents the initially inputted value in a field definition, as the value clause could have modified the $value variable
$parent		Represents the parent record in a subquery
$event		Represents the type of table event triggered on an event.