From 223c070927352455495b3c72ed847d575df11d7a Mon Sep 17 00:00:00 2001 From: Dave MacLeod <56599343+Dhghomon@users.noreply.github.com> Date: Tue, 24 Dec 2024 14:01:44 +0900 Subject: [PATCH] Start some content on references --- .../doc-surrealql/datamodel/records.mdx | 2 +- .../doc-surrealql/datamodel/references.mdx | 117 ++++++++++++++++++ src/content/doc-surrealql/datamodel/sets.mdx | 2 +- .../doc-surrealql/datamodel/strings.mdx | 2 +- src/content/doc-surrealql/datamodel/uuid.mdx | 2 +- .../doc-surrealql/datamodel/values.mdx | 2 +- .../doc-surrealql/statements/define/field.mdx | 17 +++ 7 files changed, 139 insertions(+), 5 deletions(-) create mode 100644 src/content/doc-surrealql/datamodel/references.mdx diff --git a/src/content/doc-surrealql/datamodel/records.mdx b/src/content/doc-surrealql/datamodel/records.mdx index d6bf410ba..50c768550 100644 --- a/src/content/doc-surrealql/datamodel/records.mdx +++ b/src/content/doc-surrealql/datamodel/records.mdx @@ -90,7 +90,7 @@ SELECT friends.friends.friends.name FROM person:tobie; You've now seen how to create records using randomly generated ids, or specific record ids. This is just the beginning! The power and flexibility which is possible with the remote record fetching functionality within queries opens up a whole new set of possibilities for storing and querying traditional data, and connected datasets. Take a look at the next chapter to understand how futures can be used to dynamically compute values only when retrieved. -Also checkout this explainer video on using record links in SurrealDB: +Also check out this explainer video on using record links in SurrealDB:
diff --git a/src/content/doc-surrealql/datamodel/references.mdx b/src/content/doc-surrealql/datamodel/references.mdx new file mode 100644 index 000000000..11b98345d --- /dev/null +++ b/src/content/doc-surrealql/datamodel/references.mdx @@ -0,0 +1,117 @@ +--- +sidebar_position: 17 +sidebar_label: Record references +title: Record references | SurrealQL +description: One of the most powerful features of SurrealDB is the ability to traverse from record-to-record without the need for traditional SQL JOINs. Each record ID points directly to a specific record in the database. + +--- + +import Since from '@components/shared/Since.astro' + +# Record references + + + +## Basic concepts + +Reference tracking begins by adding a `REFERENCE` clause to any `DEFINE FIELD` statement, as long as the field is a `record` or array of records. + +```surql +DEFINE FIELD comics ON person TYPE option>> REFERENCE; +``` + +Any referencing record can then be picked up on the referenced record by creating a field of type `references`. + +```surql +DEFINE FIELD owners ON comic_book TYPE references; +``` + +```surql +CREATE person:one, person:two SET comics = [comic_book:one]; +CREATE comic_book:one SET title = "Loki, God of Stories"; +SELECT * FROM comic_book; +``` + +The linking records will now be picked up automatically from the `comic_book` side. + +```surql title="Output" +[ + { + id: comic_book:one, + owners: [ + person:one, + person:two + ], + title: 'Loki, God of Stories' + } +] +``` + +## Specifying linking tables + +The following is similar to the previous example, except that the `comic_book` is now being linked to from two sources, one of which is a `publisher` which publishes both books and comic books. + +```surql +DEFINE FIELD comics ON person TYPE option>> REFERENCE; +DEFINE FIELD products ON publisher TYPE option>> REFERENCE; +DEFINE FIELD owners ON comic_book TYPE references; + +CREATE person:one, person:two SET comics = [comic_book:one]; +CREATE publisher:one SET products = [comic_book:one, book:one]; +CREATE comic_book:one SET title = "Loki, God of Stories"; +SELECT * FROM comic_book; +``` + +Because the `owners` field on `comic_book` looks for any and all references, it now includes the publisher as an owner, which is not ideal. + +```surql title="Output" +[ + { + id: comic_book:one, + owners: [ + person:one, + person:two, + publisher:one + ], + title: 'Loki, God of Stories' + } +] +``` + +This can be fixed by changing the single field of type `references` to two fields, one of which is a `references`, and the other a `references`. + +```surql +REMOVE TABLE person; +REMOVE TABLE comic_book; +REMOVE TABLE publisher; +REMOVE TABLE book; + +DEFINE FIELD comics ON person TYPE option>> REFERENCE; +DEFINE FIELD products ON publisher TYPE option>> REFERENCE; +DEFINE FIELD owners ON comic_book TYPE references; +DEFINE FIELD publisher ON comic_book TYPE references; + +CREATE person:one, person:two SET comics = [comic_book:one]; +CREATE publisher:one SET products = [comic_book:one, book:one]; +CREATE comic_book:one SET title = "Loki, God of Stories"; +SELECT * FROM comic_book; +``` + +```surql title="Output" +[ + { + id: comic_book:one, + owners: [ + person:one, + person:two + ], + publisher: [ + publisher:one + ], + title: 'Loki, God of Stories' + } +] +``` + +## Specifying linking tables and/or field names + diff --git a/src/content/doc-surrealql/datamodel/sets.mdx b/src/content/doc-surrealql/datamodel/sets.mdx index 03e133f9b..1bbeded86 100644 --- a/src/content/doc-surrealql/datamodel/sets.mdx +++ b/src/content/doc-surrealql/datamodel/sets.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 17 +sidebar_position: 18 sidebar_label: Sets title: Sets | SurrealQL description: A set is a collection type of deduplicated values that can have a maximum size limit. diff --git a/src/content/doc-surrealql/datamodel/strings.mdx b/src/content/doc-surrealql/datamodel/strings.mdx index 4cef162cf..510aee13e 100644 --- a/src/content/doc-surrealql/datamodel/strings.mdx +++ b/src/content/doc-surrealql/datamodel/strings.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 18 +sidebar_position: 19 sidebar_label: Strings title: Strings | SurrealQL description: Strings can be used to store text values. All string values can include Unicode values, emojis, tab characters, and line breaks. diff --git a/src/content/doc-surrealql/datamodel/uuid.mdx b/src/content/doc-surrealql/datamodel/uuid.mdx index 92220a07b..f64acd74e 100644 --- a/src/content/doc-surrealql/datamodel/uuid.mdx +++ b/src/content/doc-surrealql/datamodel/uuid.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 19 +sidebar_position: 20 sidebar_label: UUIDs title: UUIDs | SurrealQL description: UUID values in SurrealQL represent UUID values diff --git a/src/content/doc-surrealql/datamodel/values.mdx b/src/content/doc-surrealql/datamodel/values.mdx index 070c43106..4c8343881 100644 --- a/src/content/doc-surrealql/datamodel/values.mdx +++ b/src/content/doc-surrealql/datamodel/values.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 20 +sidebar_position: 21 sidebar_label: Values title: Values | SurrealQL description: Every type in SurrealDB is a value diff --git a/src/content/doc-surrealql/statements/define/field.mdx b/src/content/doc-surrealql/statements/define/field.mdx index 06f6d0258..72f643ac0 100644 --- a/src/content/doc-surrealql/statements/define/field.mdx +++ b/src/content/doc-surrealql/statements/define/field.mdx @@ -21,6 +21,14 @@ The `DEFINE FIELD` statement allows you to instantiate a named field on a table, ```syntax title="SurrealQL Syntax" DEFINE FIELD [ OVERWRITE | IF NOT EXISTS ] @name ON [ TABLE ] @table [ [ FLEXIBLE ] TYPE @type ] + [ REFERENCE + [ ON DELETE REJECT | + ON DELETE CASCADE | + ON DELETE IGNORE | + ON DELETE REJECT | + ON DELETE UNSET | + ON DELETE THEN @expression ] + ] [ DEFAULT @expression ] [ READONLY ] [ VALUE @expression ] @@ -507,3 +515,12 @@ DEFINE FIELD filter ON TABLE search_settings TYPE | { type: "Snowball", language: string } | { type: "Uppercase" }; ``` + + +## Defining a reference + + + +A field that is a record link (type `record`, `option`, `array>`, and so on) can be defined as a `REFERENCE`. If this clause is used, any linked to record will be able to define a field of its own of type `references` which will be aware of the incoming links. + +For more information, see [the page in the datamodel section on references](/docs/surrealql/datamodel/references). \ No newline at end of file