Prepare doc tests (#1453)

Co-authored-by: Micha de Vries <[email protected]>

Author: Dhghomon

bun.lockb

@@ -24,6 +24,19 @@ Using the `EXPLAIN` clause in addition to the `FULL` keyword is expeciallly usef
 For example, consider the performance of the following query when the field `email` is not indexed. We can see that the execution plan will iterate over the whole table.
 
 ```surql title="Index not used"
+/**[test]
+
+[[test.results]]
+value = "[{ address: '1 Bagshot Row', email: '[email protected]', id: person:tobie, name: 'Tobie' }]"
+
+[[test.results]]
+value = "[{ detail: { direction: 'forward', table: 'person' }, operation: 'Iterate Table' }, { detail: { type: 'Memory' }, operation: 'Collector' }]"
+
+[[test.results]]
+value = "[{ detail: { direction: 'forward', table: 'person' }, operation: 'Iterate Table' }, { detail: { type: 'Memory' }, operation: 'Collector' }, { detail: { type: 'KeysAndValues' }, operation: 'RecordStrategy' }, { detail: { count: 1 }, operation: 'Fetch' }]"
+
+*/
+
 CREATE person:tobie SET
 	name = "Tobie",
 	address = "1 Bagshot Row",
@@ -39,6 +52,7 @@ SELECT * FROM person WHERE email='[email protected]' EXPLAIN FULL;
 [
 	{
 		detail: {
+			direction: 'forward',
 			table: 'person'
 		},
 		operation: 'Iterate Table'
@@ -56,6 +70,7 @@ SELECT * FROM person WHERE email='[email protected]' EXPLAIN FULL;
 [
 	{
 		detail: {
+			direction: 'forward',
 			table: 'person'
 		},
 		operation: 'Iterate Table'
@@ -66,19 +81,40 @@ SELECT * FROM person WHERE email='[email protected]' EXPLAIN FULL;
 		},
 		operation: 'Collector'
 	},
+	{
+		detail: {
+			type: 'KeysAndValues'
+		},
+		operation: 'RecordStrategy'
+	},
 	{
 		detail: {
 			count: 1
 		},
 		operation: 'Fetch'
 	}
 ]
-
 ```
 
 On the other hand, here is the result when the field `email` is indexed. We can see that the execution plan will use the index to retrieve the record.
 
 ```surql title="Index used"
+/**[test]
+
+[[test.results]]
+value = "NONE"
+
+[[test.results]]
+value = "[{ address: '1 Bagshot Row', email: '[email protected]', id: person:tobie, name: 'Tobie' }]"
+
+[[test.results]]
+value = "[{ detail: { plan: { index: 'fast_email', operator: '=', value: '[email protected]' }, table: 'person' }, operation: 'Iterate Index' }, { detail: { type: 'Memory' }, operation: 'Collector' }]"
+
+[[test.results]]
+value = "[{ detail: { plan: { index: 'fast_email', operator: '=', value: '[email protected]' }, table: 'person' }, operation: 'Iterate Index' }, { detail: { type: 'Memory' }, operation: 'Collector' }, { detail: { type: 'KeysAndValues' }, operation: 'RecordStrategy' }, { detail: { count: 1 }, operation: 'Fetch' }]"
+
+*/
+
 DEFINE INDEX fast_email ON TABLE person FIELDS email;
 
 CREATE person:tobie SET
@@ -133,12 +169,17 @@ SELECT * FROM person WHERE email='[email protected]' EXPLAIN FULL;
 		},
 		operation: 'Collector'
 	},
+	{
+		detail: {
+			type: 'KeysAndValues'
+		},
+		operation: 'RecordStrategy'
+	},
 	{
 		detail: {
 			count: 1
 		},
 		operation: 'Fetch'
 	}
 ]
-
 ```

src/content/doc-surrealql/clauses/explain.mdx

@@ -64,7 +64,7 @@ This keyword can be particularly useful with SDKs as it can guaranteed to have j
 
 ```surql title="Using the ONLY keyword"
 -- Select only the 'user' table.
-SELECT * FROM ONLY user:one ;
+SELECT * FROM ONLY user:one;
 
 -- Selects only the first 10 records from the 'user' table.
 SELECT * FROM ONLY user LIMIT 10;

src/content/doc-surrealql/clauses/from.mdx

@@ -29,8 +29,15 @@ SELECT * FROM person LIMIT 10 START 50;
 ```
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "[5, 6, 7, 8, 9]"
+
+*/
+
 -- Select the first 5 records from the array
-SELECT * FROM [1,2,3,4,5,6,7,8,9,10] LIMIT 5 START 4; 
+SELECT * FROM [1,2,3,4,5,6,7,8,9,10] LIMIT 5 START 4;
 ```
 
 ```surql title="Result"

src/content/doc-surrealql/clauses/limit.mdx

@@ -18,6 +18,25 @@ OMIT @fields FROM @table
 ## Examples
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "[{ id: person:tobie, name: 'Tobie', opts: { enabled: true, security: 'secure' }, password: '123456' }]"
+
+[[test.results]]
+value = "[{ id: person:jaime, name: 'Jaime', opts: { enabled: false, security: 'secure' }, password: 'asdfgh' }]"
+
+[[test.results]]
+value = "[{ id: person:jaime, name: 'Jaime', opts: { enabled: false, security: 'secure' }, password: 'asdfgh' }, { id: person:tobie, name: 'Tobie', opts: { enabled: true, security: 'secure' }, password: '123456' }]"
+
+[[test.results]]
+value = "[{ id: person:jaime, name: 'Jaime', opts: { enabled: false } }, { id: person:tobie, name: 'Tobie', opts: { enabled: true } }]"
+
+[[test.results]]
+value = "[{ id: person:jaime, name: 'Jaime', opts: {  } }, { id: person:tobie, name: 'Tobie', opts: {  } }]"
+
+*/
+
 CREATE person:tobie SET
 	name = 'Tobie',
 	password = '123456',

src/content/doc-surrealql/clauses/omit.mdx

@@ -20,6 +20,17 @@ Suppose you have a user table with a field emails that contains an array of emai
 Here's how you can use the SPLIT clause in SurrealQL:
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "[{ emails: ['[email protected]', '[email protected]'], id: user:jhjsg6c9ta32gdut36b8, name: 'John Doe' }]"
+skip-record-id-key = true
+
+[[test.results]]
+value = "[{ emails: '[email protected]', id: user:jhjsg6c9ta32gdut36b8, name: 'John Doe' }, { emails: '[email protected]', id: user:jhjsg6c9ta32gdut36b8, name: 'John Doe' }]"
+skip-record-id-key = true
+
+*/
 CREATE user SET
     name = "John Doe",
     emails = ["[email protected]", "[email protected]"];
@@ -55,6 +66,31 @@ The output of the query will be:
 One practical use case with `SPLIT` is returning every possible combination of the relations inside multiple graph paths. For instance, take the following data below that represents the relations between Canada the country, its provinces, and their cities.
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "[{ id: country:canada }]"
+
+[[test.results]]
+value = "[{ id: province:bc }, { id: province:alberta }]"
+
+[[test.results]]
+value = "[{ id: city:vancouver }, { id: city:victoria }, { id: city:edmonton }, { id: city:calgary }]"
+
+[[test.results]]
+value = "[{ id: in:5bgf21urlmudhbv87weh, in: city:vancouver, out: province:bc }, { id: in:nt3jd2nxdf28t1eeg7uz, in: city:victoria, out: province:bc }]"
+skip-record-id-key = true
+
+[[test.results]]
+value = "[{ id: in:6iqjlca9vrnrcotwfb0a, in: city:edmonton, out: province:alberta }, { id: in:56xr5okh0jbmd5d34r0a, in: city:calgary, out: province:alberta }]"
+skip-record-id-key = true
+
+[[test.results]]
+value = "[{ id: in:gr88pyx3de7nrsm63uo2, in: province:bc, out: country:canada }, { id: in:fidjczbmblc01syn4gzd, in: province:alberta, out: country:canada }]"
+skip-record-id-key = true
+
+*/
+
 CREATE country:canada;
 CREATE province:bc, province:alberta;
 CREATE city:vancouver, city:victoria, city:edmonton, city:calgary;

src/content/doc-surrealql/clauses/split.mdx

@@ -41,6 +41,12 @@ UPDATE [TABLE_NAME] SET [FIELDS] WHERE [CONDITION] = [VALUE];
 ## Setting conditions in `DEFINE FUNCTION` statements
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "NONE"
+
+*/
 -- Define a function that checks if a relation exists between two nodes
 DEFINE FUNCTION fn::relation_exists(
 	$in: record,
@@ -59,6 +65,12 @@ DEFINE FUNCTION fn::relation_exists(
 The `WHERE` clause can be used to specify the conditions for the permissions of a table and based on the conditions, the permissions are applied to the table CRUD operations.
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "NONE"
+
+*/
 -- Specify access permissions for the 'post' table
 DEFINE TABLE post SCHEMALESS
 	PERMISSIONS
@@ -79,6 +91,13 @@ DEFINE TABLE post SCHEMALESS
 ```
 
 ```surql
+/**[test]
+
+[[test.results]]
+value = "NONE"
+
+*/
+
 -- Define a relation table, and constrain the type of relation which can be stored
 DEFINE TABLE assigned_to SCHEMAFULL TYPE RELATION IN tag OUT sticky
     PERMISSIONS