RELATE statement

The RELATE statement can be used to generate graph edges between two records in the database.

Statement syntax

RELATE @from -> @table -> @with
	[ CONTENT @value
	  | SET @field = @value ...
	]
	[ RETURN [ NONE | BEFORE | AFTER | DIFF | @projections ... ]
	[ TIMEOUT @duration ]
	[ PARALLEL ]
;

Example usage

The following query shows example usage of this statement.

-- Add a graph edge between two specific records
RELATE user:tobie->write->article:surreal SET time.written = time::now();

-- Add a graph edge between multiple specific users and devs
LET $from = (SELECT users FROM company:surrealdb);
LET $devs = (SELECT * FROM user WHERE tags CONTAINS 'developer');
RELATE $from->like->$devs SET time.connected = time::now();

Instead of specifying record data using the SET clause, it is also possible to use the CONTENT keyword to specify the record data using a SurrealQL object.

RELATE user:tobie->write->article:surreal CONTENT {
	source: 'Apple notes',
	tags: ['notes', 'markdown'],
	time: {
		written: time::now(),
	},
};

By default, the relate statement returns the record value once the changes have been made. To change the return value of each record, specify a RETURN clause, specifying either NONE, BEFORE, AFTER, DIFF, or a comma-separated list of specific fields to return.

-- Don't return any result
RELATE user:tobie->write->article:surreal SET time.written = time::now() RETURN NONE;

-- Return the changeset diff
RELATE user:tobie->write->article:surreal SET time.written = time::now() RETURN DIFF;

-- Return the record before changes were applied
RELATE user:tobie->write->article:surreal SET time.written = time::now() RETURN BEFORE;

-- Return the record after changes were applied (the default)
RELATE user:tobie->write->article:surreal SET time.written = time::now() RETURN AFTER;

-- Return a specific field only from the updated records
RELATE user:tobie->write->article:surreal SET time.written = time::now() RETURN time;