From b67625988f87dc80914348fbc26286f0b7a94e16 Mon Sep 17 00:00:00 2001
From: Dave MacLeod <56599343+Dhghomon@users.noreply.github.com>
Date: Thu, 12 Dec 2024 14:17:37 +0900
Subject: [PATCH] Add examples of RETURN VALUE (#1050)

---
 .../doc-surrealql/statements/create.mdx       | 18 +++++++++++++-
 .../doc-surrealql/statements/insert.mdx       | 24 ++++++++++++++++++-
 .../doc-surrealql/statements/relate.mdx       |  5 ++++
 .../doc-surrealql/statements/update.mdx       |  5 +++-
 4 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/src/content/doc-surrealql/statements/create.mdx b/src/content/doc-surrealql/statements/create.mdx
index 50839b3e3..fd22e104f 100644
--- a/src/content/doc-surrealql/statements/create.mdx
+++ b/src/content/doc-surrealql/statements/create.mdx
@@ -317,7 +317,7 @@ CREATE person SET age = 46, username = "john-smith" RETURN BEFORE;
 CREATE person SET age = 46, username = "john-smith" RETURN AFTER;
 ```
 
-You can also return specific fields from a created record, as well as ad-hoc fields to modify the output as needed.
+You can also return specific fields from a created record, the value of a single field using `VALUE`, as well as ad-hoc fields to modify the output as needed.
 
 ```surql
 CREATE person
@@ -328,9 +328,15 @@ RETURN
     age,
     interests,
     age + 1 AS age_next_year;
+
+CREATE |person:5|
+    SET age = 20
+RETURN VALUE age;
 ```
 
 ```surql title="Response"
+-------- Query --------
+
 [
 	{
 		age: 46,
@@ -341,6 +347,16 @@ RETURN
 		]
 	}
 ]
+
+-------- Query --------
+
+[
+	20,
+	20,
+	20,
+	20,
+	20
+]
 ```
 
 ### Timeout
diff --git a/src/content/doc-surrealql/statements/insert.mdx b/src/content/doc-surrealql/statements/insert.mdx
index 4fd63ecb3..6a8d54767 100644
--- a/src/content/doc-surrealql/statements/insert.mdx
+++ b/src/content/doc-surrealql/statements/insert.mdx
@@ -157,7 +157,7 @@ INSERT INTO company {
 } RETURN AFTER;
 ```
 
-You can also return specific fields from a created record, as well as ad-hoc fields to modify the output as needed.
+You can also return specific fields from a created record, the value of a single field using `VALUE`, as well as ad-hoc fields to modify the output as needed.
 
 ```surql
 INSERT INTO person {
@@ -168,9 +168,24 @@ RETURN
     age,
     interests,
     age + 1 AS age_next_year;
+
+INSERT INTO planet [
+	{
+		name: 'Venus',
+        surface_temp: 462,
+        temp_55_km_up: 27
+	},
+	{
+		name: 'Earth',
+        surface_temp: 15,
+        temp_55_km_up: -55
+	}
+] RETURN VALUE temp_55_km_up;
 ```
 
 ```surql title="Response"
+-------- Query --------
+
 [
 	{
 		age: 46,
@@ -181,6 +196,13 @@ RETURN
 		]
 	}
 ]
+
+-------- Query --------
+
+[
+	27,
+	-55
+]
 ```
 
 ## Bulk insert
diff --git a/src/content/doc-surrealql/statements/relate.mdx b/src/content/doc-surrealql/statements/relate.mdx
index da484ab1a..1545d0f17 100644
--- a/src/content/doc-surrealql/statements/relate.mdx
+++ b/src/content/doc-surrealql/statements/relate.mdx
@@ -377,6 +377,11 @@ RELATE person:l19zjikkw1p1h9o6ixrg->wrote->article:8nkk6uj4yprt49z7y3zm
 RELATE person:l19zjikkw1p1h9o6ixrg->wrote->article:8nkk6uj4yprt49z7y3zm
     SET time.written = time::now()
     RETURN time;
+
+-- Return only the value of a specific field without the field name
+RELATE person:l19zjikkw1p1h9o6ixrg->wrote->article:8nkk6uj4yprt49z7y3zm
+    SET time.written = time::now()
+    RETURN VALUE time;
 ```
 
 ### Using the `TIMEOUT` clause
diff --git a/src/content/doc-surrealql/statements/update.mdx b/src/content/doc-surrealql/statements/update.mdx
index 400c1af79..e4f080d97 100644
--- a/src/content/doc-surrealql/statements/update.mdx
+++ b/src/content/doc-surrealql/statements/update.mdx
@@ -439,7 +439,7 @@ UPDATE person:tobie PATCH [
 
 ## Alter the `RETURN` value
 
-By default, the update statement returns the record value once the changes have been made. To change the return value of each record, specify a `RETURN` clause, specifying either `NONE`, `BEFORE`, `AFTER`, `DIFF`, or a comma-separated list of specific fields to return.
+By default, the update statement returns the record value once the changes have been made. To change the return value of each record, use the `RETURN` clause, specifying `NONE`, `BEFORE`, `AFTER`, `DIFF`, a comma-separated list of specific fields or ad-hoc fields, or `VALUE` for a single field without its key name.
 
 ```surql
 -- Don't return any result
@@ -454,6 +454,9 @@ UPDATE person SET skills += 'reading' RETURN BEFORE;
 -- Return the record after changes were applied (the default)
 UPDATE person SET skills += 'reading' RETURN AFTER;
 
+-- Return the value of the 'skills' field without the field name
+UPDATE person SET skills += 'reading' RETURN VALUE skills;
+
 -- Return a specific field only from the updated records
 UPDATE person:tobie SET skills = ['skiing', 'music'] RETURN name, interests;
 ```