RETURN statement

The RETURN statement can be used to return a value or the result of a query, and to set the return value for a transaction, block or function.

Statement syntax

SurrealQL Syntax
RETURN @value

Example usage

Basic usage

The RETURN statement can return anything from simple values to the result of queries.

-- Return a simple value
RETURN 123;
RETURN "I am a string!";
RETURN {
	prop: "value"
};

-- Return the result of a query
RETURN SELECT * FROM person;
RETURN (CREATE person).id;

Transaction return value

RETURN statements can set the result of any transaction. This includes transactions, blocks and functions.

Transaction return value
BEGIN TRANSACTION;

-- We are executing quite a few queries here
LET $firstname = "John";
LET $lastname = "Doe";

LET $person = CREATE person CONTENT {
	firstname: $firstname,
	lastname: $lastname,
}

-- But because we end with a RETURN query, only the person's ID will be returned
-- The results of the other queries will be omitted.
RETURN $person.id;

-- One issue with this approach is that query errors are generic.
-- To get around that, use a block, which is executed as a transaction by itself.

COMMIT TRANSACTION;

Block return value
RETURN {
	-- We are executing quite a few queries here
	LET $firstname = "John";
	LET $lastname = "Doe";

	LET $person = CREATE person CONTENT {
		firstname: $firstname,
		lastname: $lastname,
	}

	-- But because we end with a RETURN query, only the person's ID will be returned
	-- The results of the other queries will be omitted.
	RETURN $person.id;
};

Function return value
DEFINE FUNCTION fn::person::create($firstname: string, $lastname: string) {
	-- We are executing more than one query here
	LET $person = CREATE person CONTENT {
		firstname: $firstname,
		lastname: $lastname,
	}

	-- But because we end with a RETURN query, only the person's ID will be returned
	-- The results of the other queries will be omitted.
	RETURN $person.id;
};

Return does not break

Do keep in mind that the RETURN statement does not break out of a block or a transaction.

IF ($something == true) THEN {
	-- It is important to note that RETURN will not break out of a block/transaction.
	-- In fact, you can add as many RETURN statements as you want, but only the result of the first one will actually be returned.
	RETURN false;
	RETURN "I am also executed!";
} END;

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.