THROW statement
The THROW statement can be used to throw an error in a place where something unexpected is happening. Execution of the query will be aborted and the error will be returned to the client. Any value can be used as an error.
Statement syntax
SurrealQL SyntaxTHROW @error
Example usage
The following query shows example usage of this statement.
-- Throw an error
THROW "some error message";
The following query shows the THROW statement being used to send back a custom error to the client.
-- In this example, we throw a custom error when a user provides invalid signin details
DEFINE SCOPE user SESSION 1w
SIGNIN {
LET $user = SELECT * FROM user WHERE username = $username AND crypto::argon2::compare(password, $password);
IF !$user {
THROW "You either provided invalid credentials, or a user with the username " + <string> $username + " might not exist.";
};
RETURN $user;
};
THROW can contain any value: arrays, objects, and so on. It can even take the value of a separate SELECT statement:
CREATE event SET time = time::now();
CREATE event SET time = time::now();
THROW SELECT * FROM event;
Response"An error occurred: [{ id: event:0hscgodgumozmmq1inz7, time: '2024-05-01T04:18:50.502Z' }, { id: event:54qknk3trimrx6ana34e, time: '2024-05-01T04:18:50.503Z' }]"
THROW can also be used to cancel a transaction, usually inside an IF statement checking a condition.
BEGIN TRANSACTION;
LET $transfer_amount = 150;
CREATE account:one SET dollars = 100;
CREATE account:two SET dollars = 100;
UPDATE account:one SET dollars -= $transfer_amount;
UPDATE account:two SET dollars += $transfer_amount;
IF account:one.dollars < 0 {
THROW "Insufficient funds, would have $" + <string>account:one.dollars + " after transfer"
};
COMMIT TRANSACTION;
SELECT * FROM account;
Output when $transfer_amount set to 150'An error occurred: Insufficient funds, would have $-50 after transfer'
Output when $transfer_amount set to 50[
{
dollars: 50,
id: account:one
},
{
dollars: 150,
id: account:two
}
]