Time and datetime improvements, add boolean and none/null page (#449)

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/booleans.mdx

@@ -0,0 +1,44 @@
+---
+sidebar_position: 3
+sidebar_label: Booleans
+title: Booleans | SurrealQL
+description: Boolean values in SurrealDB can be used to mark whether a field is true or false
+
+---
+
+## Booleans
+Boolean values can be used to mark whether a field is `true` or `false`.
+
+```surql
+CREATE person SET newsletter = false, interested = true;
+```
+
+Many SurrealDB operators and functions return booleans.
+
+```surql
+CREATE person SET 
+    name = "Billy", 
+    name_is_billy = name = "Billy",
+    name_is_long = string::len(name) > 10;
+```
+
+```bash title="Response"
+[
+    {
+        "id": "person:8ii7v7f54a2m1rla1y6b",
+        "name": "Billy",
+        "name_is_billy": true,
+        "name_is_long": false
+    }
+]
+```
+
+Boolean values can be written in anycase.
+
+```surql
+CREATE person SET 
+    newsletter = FALSE,
+    interested = True,
+    very_interested = trUE;
+```
+

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/casting.mdx

@@ -8,7 +8,7 @@ description: In the SurrealDB type system, values can be converted to other valu
 
 # Casting
 
-In the SurrealDB type system, values can be converted to other values efficiently. This is useful if input is specified in a query which must be of a certain type, or if a user has provided a parameter with an incorrect type.
+In the SurrealDB type system, values can be converted to other values efficiently. This is useful if input is specified in a query which must be of a certain type, or if a user may have provided a parameter with an incorrect type.
 
 <table>
   <thead>

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/formatters.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 5
 sidebar_label: Formatters
 title: Formatters | SurrealQL
 description: Formatting functions in SurrealQL accept certain text formats for date/time formatting.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/futures.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 6
 sidebar_label: Futures
 title: Futures | SurrealQL
 description: Futures are values which are only computed when the data is selected and returned to the client.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/geometries.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 7
 sidebar_label: Geometries
 title: Geometries | SurrealQL
 description: SurrealDB makes working with GeoJSON easy, with support for Point, Line, Polygon, MultiPoint, MultiLine, MultiPolygon, and Collection values.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/ids.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 8
 sidebar_label: Record IDs
 title: Record IDs | SurrealQL
 description: In SurrealDB, document record IDs store both the table name, and the record ID.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/none_and_null.mdx

@@ -0,0 +1,37 @@
+---
+sidebar_position: 9
+sidebar_label: None and Null
+title: None and Null | SurrealQL
+description: SurrealDB uses two types called None and Null to represent two different ways in which data may not exist.
+
+---
+
+# None and null
+
+SurrealDB uses two types called None and Null to represent two different ways in which data may not exist.
+
+## None values
+Values can be specifically set to `NONE` in SurrealDB to remove a field from a record.
+
+```surql
+CREATE person SET children = NONE;
+```
+The `NONE` keyword can be written in anycase.
+
+```surql 
+CREATE person SET children = NONE, siblings = none;
+```
+
+## Null values
+Values can be specifically set to `NULL` in SurrealDB to denote a field which is set, but which does not have a value.
+
+```surql
+CREATE person SET children = NULL;
+```
+The `NULL` keyword can be written in anycase.
+
+```surql
+CREATE person SET children = NULL, siblings = null;
+```
+
+

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/numbers.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 sidebar_label: Numbers
 title: Numbers | SurrealQL
 description: In SurrealDB, numbers can be one of three types - 64-bit integers, 64-bit floating point numbers, or 128-bit decimal numbers.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/objects.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 sidebar_label: Objects
 title: Objects | SurrealQL
 description: SurrealDB records can store objects, with no limit to the depth of any nested objects or values within.

doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/datetimes.mdx → doc-surrealdb_versioned_docs/version-1.x/surrealql/datamodel/time.mdx

@@ -1,52 +1,103 @@
 ---
-sidebar_position: 5
-sidebar_label: Datetimes
-title: Datetimes | SurrealQL
+sidebar_position: 14
+sidebar_label: Time
+title: Time | SurrealQL
 description: SurrealDB has native support for datetimes with nanosecond precision. SurrealDB automatically parses and understands datetimes which are written as strings in the SurrealQL language.
 
 ---
 
-# Datetimes
+# Time
+
+## Datetimes
 
 SurrealDB has native support for datetimes with nanosecond precision. SurrealDB automatically parses and understands datetimes which are written as strings in the SurrealQL language. Times must also be formatted in an [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format.
 
 ```surql
-CREATE event SET time = "2022-07-03T07:18:52Z";
+CREATE event SET time = "2023-07-03T07:18:52Z";
 ```
 SurrealDB handles all datetimes with nanosecond precision.
 
 ```surql
-CREATE event SET time = "2022-07-03T07:18:52.841147Z";
+CREATE event SET time = "2023-07-03T07:18:52.841147Z";
 ```
 
 SurrealDB handles all timezones, and automatically converts and stores datetimes as a UTC date.
 
 ```surql
-CREATE event SET time = "2022-07-03T07:18:52.841147+02:00";
+CREATE event SET time = "2023-07-03T07:18:52.841147+02:00";
+```
+
+The above queries will all work even if the datetime format is incorrect, but will generate a `string` instead of a `datetime`. Casting with `<datetime>` will force an error if the input is incorrect.
+
+With correct input:
+
+```surql
+CREATE event SET time = <datetime>"2023-07-03T07:18:52.841147Z";
+```
+
+```bash title="Response"
+[
+    {
+        "id": "event:0ucwynrgada73ixvllxv",
+        "time": "2023-07-03T07:18:52.841147Z"
+    }
+]
+```
+
+With incorrect input (missing final Z):
+
+```surql
+CREATE event SET time = <datetime>"2023-07-03T07:18:52.841147";
+```
+
+```bash title="Response"
+"Expected a datetime but cannot convert '2023-07-03T07:18:52.841147' into a datetime"
+```
+
+Note: As a convenience, a date without time will always parse correctly as a datetime.
+
+```surql
+CREATE event SET time = <datetime>"2024-04-03";
+```
+
+```bash title="Response"
+"2024-03-04T00:00:00Z"
+```
+
+Defining a schemafull table will also ensure that datetimes are properly formatted and not passed on as simple strings.
+
+```surql
+DEFINE TABLE event SCHEMAFULL;
+DEFINE FIELD time ON event TYPE datetime;
+CREATE event SET time = "2023-07-03T07:18:52.841147";
+```
+
+```bash title="Response"
+"Found '2023-07-03T07:18:52.841147' for field `time`, with record `event:l4q1s7hermg9yoemkqrp`, but expected a datetime"
 ```
 
-## Datetime comparison
-datetimes can be compared with each other using the advanced SurrealDB operators.
+### Datetime comparison
+A datetime can be compared with another using the advanced SurrealDB operators.
 
 ```surql
-SELECT * FROM "2022-07-03T07:18:52Z" > "2022-01-03T01:43:78Z";
+SELECT * FROM "2023-07-03T07:18:52Z" > "2023-01-03T01:42:78Z";
 ```
 
-## Datetimes and Durations
+## Durations and datetimes
 
 Durations can be used to modify and alter datetimes.
 
 ```surql
-CREATE event SET time = "2022-07-03T07:18:52Z" + 2w;
+CREATE event SET time = "2023-07-03T07:18:52Z" + 2w;
 ```
 
 Multi-part durations can also be used to modify datetimes.
 
 ```surql
-CREATE event SET time = "2022-07-03T07:18:52.841147Z" + 1h30m20s1350ms;
+CREATE event SET time = "2023-07-03T07:18:52.841147Z" + 1h30m20s1350ms;
 ```
 
-## Duration units
+### Duration units
 
 Durations can be specified in any of the following units:
 

doc-surrealdb_versioned_docs/version-1.x/surrealql/functions/geo.mdx

@@ -65,7 +65,7 @@ RETURN geo::area({
 
 0.13350018278702186
 ```
-If the argument is not a geometry type, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If the argument is not a geometry type, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::area(12345);
@@ -90,7 +90,7 @@ RETURN geo::bearing( (51.509865, -0.118092), (-0.118092, 51.509865) );
 
 -31.913259585079818
 ```
-If either argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If either argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::bearing(12345, true);
@@ -128,7 +128,7 @@ RETURN geo::centroid({
 	]
 }
 ```
-If either argument is not a geometry type, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If either argument is not a geometry type, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::centroid(12345);
@@ -152,7 +152,7 @@ RETURN geo::distance( (51.509865, -0.118092), (-0.118092, 51.509865) );
 
 7491494.807105545
 ```
-If either argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If either argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::distance(12345, true);
@@ -183,7 +183,7 @@ RETURN geo::hash::decode("mpuxk4s24f51");
 	]
 }
 ```
-If the argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If the argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::hash::decode(12345);
@@ -220,7 +220,7 @@ RETURN geo::hash::encode( (51.509865, -0.118092), 5 );
 
 "mpuxk"
 ```
-If the first argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/simple) value will be returned:
+If the first argument is not a geolocation point, then an [`EMPTY`](/docs/surrealdb/surrealql/datamodel/none_and_null) value will be returned:
 
 ```surql
 RETURN geo::hash::encode(12345);

doc-surrealdb_versioned_docs/version-1.x/surrealql/functions/rand.mdx

@@ -105,7 +105,7 @@ SELECT * FROM [{ age: 33 }, { age: 45 }, { age: 39 }] ORDER BY rand();
 
 ## `rand::bool`
 
-The rand::bool function generates a random [`boolean`](/docs/surrealdb/surrealql/datamodel/simple#booleans) value.
+The rand::bool function generates a random [`boolean`](/docs/surrealdb/surrealql/datamodel/booleans) value.
 
 ```surql title="API DEFINITION"
 rand::bool() -> bool
@@ -272,14 +272,14 @@ RETURN rand::string(10, 15);
 
 ## `rand::time`
 
-The `rand::time` function generates a random [`datetime`](/docs/surrealdb/surrealql/datamodel/datetimes).
+The `rand::time` function generates a random [`datetime`](/docs/surrealdb/surrealql/datamodel/time#datetimes).
 
 
 
 ```surql title="API DEFINITION"
 rand::time() -> datetime
 ```
-The rand::time function generates a random [`datetime`](/docs/surrealdb/surrealql/datamodel/datetimes), between two unix timestamps.
+The rand::time function generates a random [`datetime`](/docs/surrealdb/surrealql/datamodel/time#datetime), between two unix timestamps.
 
 ```surql title="API DEFINITION"
 rand::time(number, number) -> datetime

doc-surrealdb_versioned_docs/version-1.x/surrealql/functions/script/type-conversion.mdx

@@ -15,7 +15,7 @@ CREATE user:test SET created_at = function() {
 };
 ```
 
-In addition, a number of special classes are included within the JavaScript functions for the additional types which are not built into JavaScript. These enable the creation of [`duration`](/docs/surrealdb/surrealql/datamodel/datetimes#datetimes-and-durations) values, [`record`](/docs/surrealdb/surrealql/datamodel/ids) ids, and [`UUID`](/docs/surrealdb/surrealql/datamodel/strings#uuid) values from within JavaScript.
+In addition, a number of special classes are included within the JavaScript functions for the additional types which are not built into JavaScript. These enable the creation of [`duration`](/docs/surrealdb/surrealql/datamodel/time#durations-and-datetimes) values, [`record`](/docs/surrealdb/surrealql/datamodel/ids) ids, and [`UUID`](/docs/surrealdb/surrealql/datamodel/strings#uuid) values from within JavaScript.
 
 Any values of these types passed into embedded scripting functions are also represented with these special classes.