Start some content on references

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:
 
 <div class="video-container">
 <iframe width="560" height="315" src="https://www.youtube.com/embed/TyX45cyZ-W0?si=S9M59afDEiqxeC5d" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

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
+
+<Since v="v2.2.0" />
+
+## 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<array<record<comic_book>>> 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<array<record<comic_book>>> REFERENCE;
+DEFINE FIELD products ON publisher TYPE option<array<record<comic_book|book>>> 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<person>`, and the other a `references<publisher>`.
+
+```surql
+REMOVE TABLE person;
+REMOVE TABLE comic_book;
+REMOVE TABLE publisher;
+REMOVE TABLE book;
+
+DEFINE FIELD comics ON person TYPE option<array<record<comic_book>>> REFERENCE;
+DEFINE FIELD products ON publisher TYPE option<array<record<comic_book|book>>> REFERENCE;
+DEFINE FIELD owners ON comic_book TYPE references<person>;
+DEFINE FIELD publisher ON comic_book TYPE references<publisher>;
+
+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
+

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.

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.

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

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

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
+
+<Since v="v2.2.0" />
+
+A field that is a record link (type `record`, `option<record>`, `array<record<person>>`, 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).