Click here to sign up to SurrealDB Cloud

Back to top
Documentation SurrealQL 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.