Model Graph Relations in SurrealDB with RELATE

The Problem: Linking Data Without Application Joins

When you need to follow relationships between records, most databases require you to write extra code or perform multiple queries to join tables. In SurrealDB the relationship itself is a first‑class record, so you can model and query links directly.

Thesis: Use SurrealDB’s Native Graph Features

The built‑in RELATE operation creates a stable edge record, and arrow operators let you traverse those links in a single SurrealQL statement, eliminating the need for application‑side joins.

Creating Stable Graph Edges with RELATE

Edges are stored in a dedicated table, typically named after the relationship type. Each record has a globally unique ID of the form table:id. To create a link you use the RELATE statement, which references an inbound and an outbound record by their IDs.

-- Create namespace and database (requires admin rights)
CREATE NAMESPACE demo_ns;
CREATE DATABASE demo_db;

-- Define node tables
CREATE TABLE person;
INSERT INTO person:1 {name: 'Alice'};
INSERT INTO person:2 {name: 'Bob'};

-- Create edge table and link the two persons
CREATE TABLE friend;
RELATE person:1 -> person:2 RELATIONSHIP friend;

After the RELATE call, the edge record appears in the friend table. You can inspect it with a simple SELECT:

SELECT * FROM friend;

Expected result: one row with fields id, in, out, and any attributes you added.

Querying Graphs in One Statement

SurrealQL’s arrow operators let you follow links directly. The following query starts at person:1 and returns the connected person:2 node:

SELECT * FROM person:1 -> person:2;

If the edge exists, the result includes the person:2 record, confirming the traversal succeeded without any extra joins.

Trade‑off: Edge Table Growth and Query Cost

In dense graphs the edge table can become large, increasing storage usage and the cost of broad scans. Queries that traverse many hops or cover high fan‑out may also consume more CPU. To keep performance predictable, limit the depth of traversals and add filters that reduce the set of records examined.

Actionable Steps to Verify and Deploy

1. Start a local SurrealDB instance in memory mode (requires no persistent storage). Example: surreal start --log trace --user root --pass root. This gives you a clean environment for experiments.
2. Create a namespace and database (admin rights needed). Use CREATE NAMESPACE and CREATE DATABASE as shown above.
3. Define node tables and insert sample records. Ensure each record gets a unique ID (the table:id format).
4. Create the edge table and issue a RELATE statement. Verify the edge appears by selecting from the edge table.
5. Run a traversal query using arrow operators. Check that the returned nodes match the expected path.
6. Add an attribute to the edge record (e.g., weight: 0.8) and re‑run the traversal. The new attribute should be visible without any schema migration, demonstrating SurrealDB’s flexible schema.
7. Monitor storage growth in production. If the edge table size exceeds your expectations, consider limiting traversal depth or adding WHERE clauses to restrict the search space.

By following these steps you can confidently model graph relationships in SurrealDB, query them efficiently, and anticipate the main limitations before deploying to production.