From c6dc50ed6b75820ebfac59dac5f2387e259f9e61 Mon Sep 17 00:00:00 2001 From: Dave MacLeod <56599343+Dhghomon@users.noreply.github.com> Date: Thu, 2 Jan 2025 13:45:56 +0900 Subject: [PATCH] Add bit on deletion behaviour --- .../reference-guide/graph_relations.mdx | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/src/content/doc-surrealdb/reference-guide/graph_relations.mdx b/src/content/doc-surrealdb/reference-guide/graph_relations.mdx index b19c9ace8..1a8fa2c98 100644 --- a/src/content/doc-surrealdb/reference-guide/graph_relations.mdx +++ b/src/content/doc-surrealdb/reference-guide/graph_relations.mdx @@ -151,12 +151,13 @@ If your use case involves bidirectional links, consider the following items to m Record links are preferred if: * Performance is of the utmost importance. +* You don't need to put complex queries together. +* You want to specify in the schema what behaviour should take place when a linked record is deleted (cascade delete, refuse to delete, ignore, etc.). 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 are 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? @@ -823,4 +824,23 @@ For more details on SurrealDB's recursive syntax, see the following pages: ### 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 +As mentioned above, record links since version 2.2.0 have the ability to specify what behaviour should take place when a referencing link is deleted. Graph links have a simpler behaviour in which they will be deleted if at least of the linked records is deleted. + +```surql +-- likes record created without problems +RELATE person:one->likes->person:two; +CREATE person:one, person:two; +DELETE person:one; +-- 'likes' record is now gone +SELECT * FROM likes; +``` + +A record link allows for more complex behaviour such as the following in which a linked record is removed from the `comments` field if it is deleted, but also adds the record ID to a field called `deleted_comments` for record keeping. For more information on these `ON DELETE` clauses, see the [page on record references](/docs/surrealql/datamodel/references/). + +```surql +DEFINE FIELD comments ON person TYPE option>> REFERENCE ON DELETE THEN { + UPDATE $this SET + deleted_comments += $reference, + comments -= $reference; +}; +``` \ No newline at end of file