Record links in SurrealDB

If we look at the SurrealDB docs we see record links:

SurrealDB record  links

But what is a record link and how do we create one, and how does it work?

A record link is 1 way

A graph using relate is 2 way

Well why use a record link then?

“Each record ID points directly to a specific record in the database, without needing to run a table scan query. Record IDs can be stored within other records, allowing them to be linked together.”


Send some sats if you like this article, it’ll help me keep the site ad free!

Record Links example based on SurrealDB demo database

The demo file has lots of records and tables

To simplify, I’ve stripped back to the bare minimum. What we can see is the creation of an artist table and a review table. The review needs to link back to the artist, otherwise it’d be a bit of a useless review.

We link the artist to the review using


Because the data is already in the table we have the id – but what if we were creating these tables and were using the randomly generated id numbers?

From what I’ve learned so far I’d use “Let” as per this example taken from SurrealDB docs:

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

So we use the record id of the “right hand table” in the left hand table?

Well that’s how I remember it, maybe a traditional way of thinking about it from relational database mental models but it works for me!

Ok, so here is the full “SQL” or “SurrealQL”


CREATE review;
CREATE artist;

UPDATE review:00a0ic854u4j7z02s00v 
CONTENT { artist: artist:00b2pg847d7b8r08t08t, 
          id: review:00a0ic854u4j7z02s00v, 
          person: person:67s8cp304i4p6p83q02d, 
          product: product:41v2qv923h3o7s55e96l, 
          rating: 3, review_text: 'repeat exchange meter lawyer academy sunset gang' };

UPDATE artist:00b2pg847d7b8r08t08t 
CONTENT { address: { address_line_1: '816 Cravenny', 
                     address_line_2: NONE, 
                     city: 'Malvern', 
                     coordinates: [9.854998, -0.731803], 
                     country: 'England', post_code: 'HO1D 8WY' }, 
                     company_name: NONE, email: '', 
                     first_name: 'Lasonya', id: artist:00b2pg847d7b8r08t08t, 
                     last_name: 'Spears', name: 'Lasonya Spears', phone: '0800 085411' };

So all we need to do now is use the table name as the prefix followed by a dot and then the “field name”

SELECT id,rating, 
AS city, 
AS email 
FROM review;


We’v looked at how to add a link and then how to query a record link.

Remember that it is one-way so we can’t query the review from the artist table.

If you want to have 2 way queries then relate and graph tables are the way to do it.

If you want to make advanced queries check out the SurrealDB cheatsheet

Previous article

SurrealDB tutorial

Next article

Binary Tree in Python