LET Statement

The LET statement allows you to create parameters to store any value, including the results of queries or the outputs of expressions. These parameters can then be referenced throughout your SurrealQL code, making your queries more dynamic and reusable.

Syntax

The syntax for the LET statement is straightforward. The parameter name is prefixed with a $ symbol.

SurrealQL Syntax
LET $@parameter [: @type_name] = @value;

Example Usage

Basic Parameter Assignment

You can use the LET statement to store simple values or query results. For example, storing a string value and then using it in a CREATE statement:

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

Storing Query Results

The LET statement is also useful for storing the results of a query, which can then be used in subsequent operations:

-- Define the parameter
LET $adults = SELECT * FROM person WHERE age > 18;
-- Use the parameter
UPDATE $adults SET adult = true;

Conditional Logic with IF ELSE

SurrealQL allows you to define parameters based on conditional logic using IF ELSE statements:

LET $num = 10;

LET $num_type =
         IF type::is_int($num)     { "integer" }
    ELSE IF type::is_decimal($num) { "decimal" }
    ELSE IF type::is_float($num)   { "float"   };

Anonymous Functions

You can define anonymous functions also known as closures using the LET statement. These functions can be used to encapsulate reusable logic and can be called from within your queries. Learn more about anonymous functions in the Data model section.

Pre-Defined and Protected Parameters

SurrealDB comes with pre-defined parameters that are accessible in any context. However, parameters created using LET are not accessible within the scope of these pre-defined parameters.

Furthermore, some pre-defined parameters are protected and cannot be overwritten using LET:

LET $before = "Before!";

-- Returns ["Before!"];
RETURN $before;

-- Returns the `person` records before deletion
DELETE person RETURN $before;

-- Returns "Before!" again
RETURN $before;

Attempting to redefine protected parameters will result in an error:

LET $auth = 1;
LET $session = 10;

Output
-------- Query 1 (0ns) --------

"'auth' is a protected variable and cannot be set"

-------- Query 2 (0ns) --------

"'session' is a protected variable and cannot be set"

Typed LET statements

Available since: v2.0.0

Type safety in a LET statement can be ensured by adding a : (a colon) and the type name after the LET keyword.

LET $number: int = "9";

Output
"Found '9' for param $number, but expected a int"

Taking advantage of type safety

Using typed LET statements is a good practice when prototyping code or when getting used to SurrealQL for the first time. Take the following example that attempts to count the number of true values in a field by filtering out values that are not true, without noticing that the field actually contains strings instead of booleans. The query output ends up being 3, rather than the expected 2.

CREATE some:record SET vals = ["true", "false", "true"];
some:record.vals.filter(|$val| $val = true).len();

Output
3

Breaking this into multiple typed LET statements shows the error right away.

LET $vals: array<bool> = some:record.vals;
LET $len: number = $vals.filter(|$val| $val = true).len();
$len;

Output
-------- Query 1 --------

"Found 'true' for param $vals, but expected a array<bool>"

-------- Query 2 --------

'There was a problem running the filter() function. no such method found for the none type'

-------- Query 3 --------

NONE

With the location of the error in clear sight, a fix is that much easier to implement.

-- Use .map() to turn each string into a bool
LET $vals: array<bool> = some:record.vals.map(|$val| <bool>$val);
LET $len: number = $vals.filter(|$val| $val = true).len();
$len;

Output
2

Typed literal statements

Multiple possible types can be specified in a LET statement by adding a | (vertical bar) in between each possible type.

LET $number: int | string = "9";

Even complex types such as objects can be included in a typed LET statement.

LET $error_info: string | { error: string } = { error: "Something went wrong plz help" };

For more information on this pattern, see the page on literals.

Conclusion

The LET statement in SurrealDB is versatile, allowing you to store values, results from subqueries, and even define anonymous functions. Understanding how to use LET effectively can help you write more concise, readable, and maintainable queries.