In SurrealDB, one record can be linked to another via a graph edge, namely a table that stands in between the two that has its own ID and properties. This page teaches how to determine whether this is the ideal way to link records in your project, and best practices for doing so.
The first item to take into account when using graph relations is whether they are the right solution in the first place, because graph edges are not the only way to link one record to another.
SurrealDB has two main ways to create relations between one record and another: record links, and graph relations.
A record link is a simple pointer from one record to another, a link that exists any time a record holds the record ID of another record. Record links are the most efficient method because record IDs are direct pointers to the data of a record, and do not require a table scan.
Take the following example that creates one user
who has written two comment
s.
LET $new_user = CREATE ONLY user SET name = "User McUserson"; -- Create a new comment, use the output to update the user UPDATE $new_user SET comments += (CREATE ONLY comment SET text = "I learned something new!", created_at = time::now()) .id; UPDATE $new_user SET comments += (CREATE ONLY comment SET text = "I don't get it, can you explain?", created_at = time::now()) .id;
Querying a record link is easy as the link is unidirectional with nothing in between. In this case, the linked comments are simply a field on a user
record and accessing them is as simple as any other field on a user
record.
SELECT name, comments.{ created_at, text } FROM user;
Output[ { comments: [ { created_at: d'2024-12-12T02:39:07.644Z', text: 'I learned something new!' }, { created_at: d'2024-12-12T02:39:07.645Z', text: "I don't get it, can you explain?" } ], name: 'User McUserson' } ]
The unidirectionality of a record link is also a limitation, because the only way to query in the other direction is by using a subquery. With some knowledge of SurrealQL this is certainly doable, but a case like this is an indication that a graph link may be the better solution.
SELECT *, -- Check the `user` table's `comments` field -- for the id of the current comment (SELECT id, name FROM user WHERE $parent.id IN comments) AS author FROM comment;
[ { author: [ { id: user:f3t90z8uvns76sr3nxrd, name: 'User McUserson' } ], created_at: d'2024-12-12T02:39:07.645Z', id: comment:gj1vtsd9d19z9afrc14j, text: "I don't get it, can you explain?" }, { author: [ { id: user:f3t90z8uvns76sr3nxrd, name: 'User McUserson' } ], created_at: d'2024-12-12T02:39:07.644Z', id: comment:zhnbfopxspekknsi6vx6, text: 'I learned something new!' } ]
The other limitation is that there is no metadata about the context in which the comment was created. Take the following metadata for instance which contains information about a user’s current location, operating system, and mood. Where does this data belong?
{ location: "Arizona", os: "Windows 11", current_mood: "Happy" }
This metadata isn’t information about the user as a whole, nor the comment itself. It’s information about the moment in time in which the user
and comment
were linked, and thus is best stored in a separate table. If this sort of metadata is necessary, then a graph table is the ideal solution.
The following example is similar to the one above, except that this time the user
record does not have a comments
field, leaving it seemingly separate from the comment
created on the next line. Instead, this time a RELATE
statement is used to create a graph edge called wrote
joining the two of them, and this is the table that holds the metadata mentioned above.
LET $new_user = CREATE ONLY user SET name = "User McUserson"; LET $new_comment = CREATE ONLY comment SET text = "I learned something new!", created_at = time::now(); RELATE $new_user->wrote->$new_comment SET location = "Arizona", os = "Windows 11", mood = "happy";
Now that a graph edge has been established, the arrow operator can be used to traverse this path. The versatility of this operator is one of the key advantages of using graph edges, as they can be traversed forward, backward, recursively, and more.
-- Go through each user and find comment(s) it wrote SELECT ->wrote->comment FROM user; -- Go through each comment and find the user(s) that wrote it SELECT <-wrote<-user FROM comment; -- Go through each comment, find the user(s) that wrote it, -- and then find all of their comments SELECT <-wrote<-user->wrote->comment FROM comment;
The arrow operator used to traverse graph edges is an intuitive way to visualize the direction(s) in which a query is traversing. As this page is devoted to an overview of when and how best to use graph relations, it does not go into the details of queries themselves. Many reference pages already exist in the SurrealDB documentation to learn this, including:
RELATE
statementThe following sections detail some tips and best practices when using graph relations.
Defining a table as TYPE RELATION
ensures that it can only be created in the context of a relation between two records.
Adding TYPE RELATION
to a DEFINE TABLE
statement is enough to ensure this behaviour.
DEFINE TABLE likes TYPE RELATION;
Specifying the record types at the in
and out
fields of a graph table will ensure that no other records can be joined to each other in this way.
DEFINE TABLE likes TYPE RELATION IN person OUT blog_post | book;
One other advantage to strictly defining a relation table is that this information can be picked up by Surrealist to be displayed in its Designer view.
Take the following queries that create some records and relate them to each other.
CREATE person:one, book:one, blog_post:one; RELATE person:one->likes->book:one; RELATE person:one->likes->blog_post:one;
As the likes
table is not yet defined as a relation, Surrealist is unable to determine anything about the table besides the fact that it exists, leading to the following view.
Defining the table as a TYPE RELATION
will improve the layout somewhat by making it clear that likes
is a graph table.
DEFINE TABLE likes TYPE RELATION; CREATE person:one, book:one, blog_post:one; RELATE person:one->likes->book:one; RELATE person:one->likes->blog_post:one;
If the in
and out
fields are specified, however, Surrealist will now be able to graphically display the relation between all these records through the likes
table.
DEFINE TABLE likes TYPE RELATION IN person OUT blog_post | book; CREATE person:one, book:one, blog_post:one; RELATE person:one->likes->book:one; RELATE person:one->likes->blog_post:one;
While most examples involve a clear subject and object relation, sometimes a graph edge represents a relation such as friendship, a partnership, sister cities, etc. in which this is not clear.
CREATE person:one, person:two; -- Relate them like this? RELATE person:one->friends_with->person:two; -- Or like this? RELATE person:two->friends_with->person:one;
To ensure that this relation cannot be established more than once, define a field made of the sorted in
and out
fields of the graph table, and define an index on it with a unique constraint.
DEFINE FIELD key ON TABLE friends_with VALUE <string>array::sort([in, out]); DEFINE INDEX only_one_friendship ON TABLE friends_with FIELDS key UNIQUE;
With this constraint in place, no second friends_with
can be initiated from the other side.
CREATE person:one, person:two; RELATE person:one->friends_with->person:two; RELATE person:two->friends_with->person:one;
Output of RELATE statements-------- Query -------- [ { id: friends_with:dblidwpc44qqz5bvioiu, in: person:one, key: '[person:one, person:two]', out: person:two } ] -------- Query -------- "Database index `only_one_friendship` already contains '[person:one, person:two]', with record `friends_with:dblidwpc44qqz5bvioiu`"
In a relation between equals like in the example above, it is never certain whether a specific person
is friends with another due to a RELATE
statement where it is the subject of the statement, or the object of the statement.
The <->
operator can be used in this case to traverse both the in
and out
fields of the friends_with
table.
SELECT *, <->friends_with<->person AS friends FROM person;
This will now show each of the records involved in the relation, regardless of whether they are located at the in
or out
field of the friends_with
graph table.
[ { friends: [ person:one, person:two ], id: person:one }, { friends: [ person:one, person:two ], id: person:two } ]
To complete this query to ensure that a record’s own ID does not show up inside the list of friends
, the array::complement()
function can be used.
SELECT *, array::complement(<->friends_with<->person, [id]) AS friends FROM person;
Output[ { friends: [ person:two ], id: person:one }, { friends: [ person:one ], id: person:two } ]
For further details on this pattern, see this section in the page on the RELATE
statement and this section of Chapter 7 of Aeon’s Surreal Renaissance.
As graph traversal takes place between records, the same syntax can be used directly from one or more record IDs without needing to use a SELECT
statement. Take the following setup that once again creates a record linked to a comment:
CREATE ONLY user:mcuserson SET name = "User McUserson"; CREATE ONLY comment:one SET text = "I learned something new!", created_at = time::now(); CREATE ONLY cat:pumpkin SET name = "Pumpkin"; RELATE user:mcuserson->wrote->comment:one SET location = "Arizona", os = "Windows 11", mood = "happy"; RELATE user:mcuserson->likes->cat:pumpkin;
These graph edges can be traversed simply using the record name and the arrow syntax.
-- Equivalent to: -- SELECT VALUE <-wrote<-user FROM ONLY comment:one; comment:one<-wrote<-user; -- Equivalent to: -- SELECT VALUE ->likes->cat FROM ONLY user:mcuserson; user:mcuserson->likes->cat;
Output-------- Query -------- [ user:mcuserson ] -------- Query -------- [ cat:pumpkin ]
To include various fields in a query that begins from a record ID, the destructuring operator can be used.
-- Equivalent to: -- SELECT name, ->likes->cat AS cats FROM ONLY user:mcuserson; user:mcuserson.{ name, cats: ->likes->cat };
While most examples in the documentation show how to traverse graph paths inside a SELECT
statement, they can just as easily be defined as a field on a table.
DEFINE FIELD employers ON TABLE person VALUE SELECT VALUE <-employs<-company FROM ONLY $this; CREATE person:1, person:2, company:1; RELATE company:1->employs->person:1; person:1.*;
However, note that the output of the query above shows an empty array for the employers
field, as it was calculated at the point that person:1
was created, not when the RELATE
statement was executed. The VALUE
clause will only recalculate if a record is updated.
UPDATE person:1;
Output[ { employers: [ company:1 ], id: person:1 } ]
A future
makes more sense in this case, as a future is calculated each time a record is queried, not just whenever it is created or updated.
DEFINE FIELD employers ON TABLE person VALUE <future> { RETURN SELECT VALUE <-employs<-company FROM ONLY $this }; CREATE person:1, person:2, company:1; RELATE company:1->employs->person:1; person:1.*;
Output{ employers: [ company:1 ], id: person:1 }
Surrealist has an Explorer view that allows users to not just view records and their fields, but also traverse their relations one step at a time. This can be an effective tool to understand the internals of graph edges and queries on them.
Take the following example similar to the ones above, except that the user
this time has two graph relations instead of one.
CREATE user:mcuserson SET name = "User McUserson"; CREATE comment:one SET text = "I learned something new!", created_at = time::now(); CREATE cat:pumpkin SET name = "Pumpkin"; RELATE user:mcuserson->wrote->comment:one SET location = "Arizona", os = "Windows 11", mood = "happy"; RELATE user:mcuserson->likes->cat:pumpkin;
The Explorer view inside Surrealist can then be used to understand a query like SELECT ->wrote->comment FROM user
and what the database sees at each and every step of the way.
user
(this is the FROM user
part), then the individual user:mcuserson
record.Relations
tab. This has two outgoing relations, outgoing being the ->
direction.wrote
, so click on that to move into the single wrote
record.comment
, which matches the ->comment
part of the path.comment
the user wrote, finishing the query.Reversing the process by beginning with the Explorer view is a good way to build up a query one step at a time when you are still getting used to the syntax.
One characteristic of graph tables is that they can be created before the two records in question exist.
-- Works fine RELATE person:one->likes->person:two; -- Returns [] person:one->likes->person; -- Finally create the 'person' records CREATE person:one, person:two; -- Now it returns [ person:two ] person:one->likes->person;
If this is not desirable, the ENFORCED
keyword can be added to a DEFINE TABLE
statement.
DEFINE TABLE likes TYPE RELATION IN person OUT person ENFORCED;
Output"The record 'person:one' does not exist"
However, certain patterns might make it desirable to use RELATE
before creating a record. For example, a street in a city might have a set of addresses registered with a predictable record ID (such as an ID composed of a street number and name) but no houses at the location yet. A DEFINE FIELD
statement can be used here that contains the path from the house
to the street
that will be calculated once the house
is finally created.
DEFINE FIELD street ON house VALUE $this<-contains<-street; CREATE street:frankfurt_road; RELATE street:frankfurt_road->contains->[ house:[200, "Frankfurt Road"], house:[205, "Frankfurt Road"], house:[210, "Frankfurt Road"], ]; -- Twelve months later once the house is built and size is known... CREATE house:[200, "Frankfurt Road"] SET sq_m = 110.5;
Output[ { id: house:[ 200, 'Frankfurt Road' ], sq_m: 110.5f, street: [ street:frankfurt_road ] } ]
Recursive queries allow traversal of a path down to a specific depth.
Take the following person
records that are connected to each other via the child_of
path.
CREATE |person:1..15|; -- parents of person:1 RELATE person:1->child_of->[person:2, person:3]; -- grandparents of person:1 RELATE person:2->child_of->[person:4, person:5]; RELATE person:3->child_of->[person:6, person:7]; -- great-grandparents of person:1 RELATE person:4->child_of->[person:8, person:9]; RELATE person:5->child_of->[person:10, person:11]; RELATE person:6->child_of->[person:12, person:13]; RELATE person:7->child_of->[person:14, person:15];
Following the person:1
record down three depths (parents, grandparents, great-grandparents) can be done manually by repeating the ->child_of->person
path as many times as required.
SELECT ->child_of->person AS parents, ->child_of->person->child_of->person AS grandparents, ->child_of->person->child_of->person->child_of->person AS great_grandparents FROM ONLY person:1;
The recursive syntax can be used in this case to repeat a path as many times as desired instead of manually typing.
SELECT @.{1}->child_of->person AS parents, @.{2}->child_of->person AS grandparents, @.{3}->child_of->person AS grandparents FROM ONLY person:1;
However, the recursive syntax goes beyond simply saving keystrokes on a regular graph query. It can also be used to return a single nested object that recurses a number of times as instructed down an indicated path.
-- Range to start at a depth of one, try to go down to depth of three SELECT @.{3}.{ id, -- At each depth, use this path to reach the next one parents: ->child_of->person.@ } FROM person:1;
person:1.{3}.{ id, parents: ->child_of->person.@ };
While developed for graph relations in particular, this path can be used in any context.
For more details on SurrealDB’s recursive syntax, see the following pages: