diff --git a/src/content/doc-surrealdb/reference-guide/graph_relations.mdx b/src/content/doc-surrealdb/reference-guide/graph_relations.mdx index 781e7bfea..389365ccf 100644 --- a/src/content/doc-surrealdb/reference-guide/graph_relations.mdx +++ b/src/content/doc-surrealdb/reference-guide/graph_relations.mdx @@ -59,7 +59,7 @@ FROM user; ] ``` -Until SurrealDB version 2.2.0, record links were strictly unidirectional. The only way to query in the other direction was by using a subquery, which made graph edges the only option for bidirectional links. +Until SurrealDB version 2.2.0, record links were strictly unidirectional. The only way to query in the other direction was by using a subquery, which made graph edges the only easy option for bidirectional links. ```surql SELECT @@ -68,6 +68,13 @@ SELECT -- for the id of the current comment (SELECT id, name FROM user WHERE $parent.id IN comments) AS author FROM comment; + +-- Equivalent graph query is much easier +-- to read and write +SELECT + *, + <-wrote<-author +FROM comment; ``` ```surql @@ -139,7 +146,19 @@ comment:one.refs(); ] ``` -The main 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? +If your use case involves bidirectional links, consider the following items to make a decision. + +Record links are preferred if: + +* Performance is of the utmost importance. + +Graph links are preferred if: + +* You want to create links without touching the database schema. +* You want to put together complex queries that take advantage of SurrealQL's expressive arrow syntax, like `->wrote->comment<-wrote<-person->wrote->comment FROM person`. +* You want to + +Finally, graph links arle not just preferred but almost certainly necessary if you need to keep metadata about the context in which a link is created. Take the following metadata for the examples above involving a user and its comments which contains information about a user's current location, operating system, and mood. Where does this data belong? ```surql { @@ -149,7 +168,18 @@ The main limitation is that there is no metadata about the context in which the } ``` -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. +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. + +Or you might have some information about the link itself, which would also belong nowhere else but inside a graph table. + +```surql +{ + friends_since: d'2024-12-31T06:43:21.981Z', + friendship_strength: 0.4 +} +``` + +If this sort of metadata is necessary, then a graph table is the ideal solution. ## Creating a graph relation @@ -599,4 +629,8 @@ While developed for graph relations in particular, this path can be used in any For more details on SurrealDB's recursive syntax, see the following pages: * [Idioms: recursive paths](/docs/surrealql/datamodel/idioms#recursive-paths) -* [Chapter 8 of Aeon's Surreal Renaissance](/learn/book/chapter-08#longer-relational-queries) \ No newline at end of file +* [Chapter 8 of Aeon's Surreal Renaissance](/learn/book/chapter-08#longer-relational-queries) + +### When links are deleted + +Mention how graph tables are deleted if the records involved are deleted, while record links have the fancy clauses \ No newline at end of file