Chore: Update rand functions documentation for UUID and ULID (#689)

surrealdb · Jul 24, 2024 · 384dcfb · 384dcfb
1 parent 03cbde5
commit 384dcfb
Showing 1 changed file with 104 additions and 2 deletions.
diff --git a/doc-surrealdb_versioned_docs/version-2.x/surrealql/functions/database/rand.mdx b/doc-surrealdb_versioned_docs/version-2.x/surrealql/functions/database/rand.mdx
@@ -302,7 +302,7 @@ d"1991-01-13T23:27:17Z"
 
 ## `rand::uuid`
 
-The `rand::uuid` function generates a random UUID.
+The `rand::uuid` function generates a random UUID. You can also generate uuids from datatime values.
 
 ```surql title="API DEFINITION"
 rand::uuid() -> uuid
@@ -316,11 +316,36 @@ RETURN rand::uuid();
 [u"e20b2836-e689-4643-998d-b17a16800323"]
 ```
 
+### `rand::uuid` from timestamp
+
+The `rand::uuid` function generates a random UUID from a datetime type.
+
+```surql title="API DEFINITION"
+rand::uuid(datetime) -> uuid
+```
+
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+
+```surql
+RETURN rand::uuid(d"2021-09-07T04:27:53Z");
+```
+
+```surql
+CREATE ONLY test:[rand::uuid()] SET created = time::now(), num = 1;
+SLEEP 100ms;
+
+LET $rec = CREATE ONLY test:[rand::uuid()] SET created = time::now(), num = 2;
+SLEEP 100ms;
+CREATE ONLY test:[rand::uuid()] SET created = time::now(), num = 3;
+-- Select the value of the record created before the current record in the table
+SELECT VALUE num FROM test:[rand::uuid($rec.created - 100ms)]..;
+  ```
+
 <br />
 
 ## `rand::uuid::v4`
 
-The `rand::uuid::v4` function generates a random UUID.
+The `rand::uuid::v4` function generates a random version 4 UUID.
 
 ```surql title="API DEFINITION"
 rand::uuid::v4() -> uuid
@@ -334,6 +359,31 @@ RETURN rand::uuid::v4();
 [u"4def23a5-a847-4934-8dad-c64ccc48921b"]
 ```
 
+### `rand::uuid::v4` from timestamp
+
+The `rand::uuid::v4` function generates a random version 4 UUID from a datetime type.
+
+```surql title="API DEFINITION"
+rand::uuid::v4(datetime) -> uuid
+```
+
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+
+```surql
+RETURN rand::uuid::v4(d"2021-09-07T04:27:53Z");
+```
+
+```surql
+CREATE ONLY test:[rand::uuid::v4()] SET created = time::now(), num = 1;
+SLEEP 100ms;
+
+LET $rec = CREATE ONLY test:[rand::uuid::v4()] SET created = time::now(), num = 2;
+SLEEP 100ms;
+CREATE ONLY test:[rand::uuid::v4()] SET created = time::now(), num = 3;
+-- Select the value of the record created before the current record in the table
+SELECT VALUE num FROM test:[rand::uuid::v4($rec.created - 100ms)]..;
+  ```
+
 <br />
 
 ## `rand::uuid::v7`
@@ -351,6 +401,32 @@ RETURN rand::uuid::v7();
 
 [u'0190d9df-c6cd-7e8a-aae2-aa3a162507ed']
 ```
+
+### `rand::uuid::v7` from timestamp
+
+The `rand::uuid::v7` function generates a random  Version 7  UUID from a datetime type.
+
+```surql title="API DEFINITION"
+rand::uuid::v7(datetime) -> uuid
+```
+
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+
+```surql
+RETURN rand::uuid::v7(d"2021-09-07T04:27:53Z");
+```
+
+```surql
+CREATE ONLY test:[rand::uuid::v7()] SET created = time::now(), num = 1;
+SLEEP 100ms;
+
+LET $rec = CREATE ONLY test:[rand::uuid::v7()] SET created = time::now(), num = 2;
+SLEEP 100ms;
+CREATE ONLY test:[rand::uuid::v7()] SET created = time::now(), num = 3;
+-- Select the value of the record created before the current record in the table
+SELECT VALUE num FROM test:[rand::uuid::v7($rec.created - 100ms)]..;
+  ```
+
 To enable `rand::uuid::v7` in [embedded mode](/docs/surrealdb/embedding/rust) you need to add the following to your `.cargo/config.toml` file in your project
 
 ```toml
@@ -376,4 +452,30 @@ RETURN rand::ulid();
 [u"01H9QDG81Q7SB33RXB7BEZBK7G"]
 ```
 
+### `rand::ulid` from timestamp
+
+The `rand::ulid` function generates a random ULID from a datetime type.
+
+```surql title="API DEFINITION"
+rand::ulid(datetime) -> uuid
+```
+
+The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealdb/surrealql/statements/return) statement:
+
+```surql
+RETURN rand::ulid(d"2021-09-07T04:27:53Z");
+```
+
+```surql
+CREATE ONLY test:[rand::ulid()] SET created = time::now(), num = 1;
+SLEEP 100ms;
+
+LET $rec = CREATE ONLY test:[rand::ulid()] SET created = time::now(), num = 2;
+SLEEP 100ms;
+CREATE ONLY test:[rand::ulid()] SET created = time::now(), num = 3;
+-- Select the value of the record created before the current record in the table
+SELECT VALUE num FROM test:[rand::ulid($rec.created - 100ms)]..;
+  ```
+
+
 <br /><br />