More record range advice (#1270)

Author: Dhghomon

src/content/doc-surrealql/datamodel/ids.mdx

@@ -551,6 +551,90 @@ Not only is the `START 50 LIMIT 2` query more performant, but the entire `num` f
 ]
 ```
 
+### Move exact matches in array-based record IDs to the front
+
+Take the following `event` records which can be queried as a perfomant record range.
+
+```surql
+CREATE event:[d'2025-05-05T08:00:00Z', user:one, "debug"] SET info = "Logged in";
+CREATE event:[d'2025-05-05T08:10:00Z', user:one, "debug"] SET info = "Logged out";
+CREATE event:[d'2025-05-05T08:01:00Z', user:two, "debug"] SET info = "Logged in";
+```
+
+The ordering of the ID in this case is likely not ideal, because the first item in the array, a `datetime`, will be the first to be evaluated in a range scan. A query such as the one below on a range of dates will effectively ignore the second and third parts of the ID.
+
+```surql
+SELECT * FROM event:[d'2025-05-05', user:one, "debug"]..[d'2025-05-06', user:one, "debug"];
+
+-- Same result! user name and "debug" are irrelevant
+-- SELECT * FROM event:[d'2025-05-05']..[d'2025-05-06'];
+```
+
+```surql title="Output"
+[
+	{
+		id: event:[
+			d'2025-05-05T08:00:00Z',
+			user:one,
+			'debug'
+		],
+		info: 'Logged in'
+	},
+	{
+		id: event:[
+			d'2025-05-05T08:01:00Z',
+			user:two,
+			'debug'
+		],
+		info: 'Logged in'
+	},
+	{
+		id: event:[
+			d'2025-05-05T08:10:00Z',
+			user:one,
+			'debug'
+		],
+		info: 'Logged out'
+	}
+]
+```
+
+Instead, the parts of the array that are more likely to be exactly matched (such as `user:one` and `"debug"`) should be moved to the front.
+
+```surql
+CREATE event:[user:one, "debug", d'2025-05-05T08:00:00Z'] SET info = "Logged in";
+CREATE event:[user:one, "debug", d'2025-05-05T08:10:00Z'] SET info = "Logged out";
+CREATE event:[user:two, "debug", d'2025-05-05T08:01:00Z'] SET info = "Logged in";
+```
+
+Using this format, queries can now be performed for a certain user and logging level, over a range of datetimes.
+
+```surql
+-- Only returns events for user:one and "debug"
+SELECT * FROM event:[user:one, "debug", d'2025-05-05']..[user:one, "debug", d'2025-05-06'];
+```
+
+```surql title="Output"
+[
+	{
+		id: event:[
+			user:one,
+			'debug',
+			d'2025-05-05T08:00:00Z'
+		],
+		info: 'Logged in'
+	},
+	{
+		id: event:[
+			user:one,
+			'debug',
+			d'2025-05-05T08:10:00Z'
+		],
+		info: 'Logged out'
+	}
+]
+```
+
 ### Auto-incrementing IDs
 
 While SurrealDB does not use auto-incrementing IDs by default, this behaviour can be achieved in a number of ways. One is to use the [`record::id()`](/docs/surrealql/functions/database/record#recordid) function on the latest record, which returns the latter part of a record ID (the '1' in the record ID `person:1`). This can then be followed up with the [`type::thing()`](/docs/surrealql/functions/database/type#typething) function to create a new record ID.

src/content/doc-surrealql/functions/database/type.mdx

@@ -83,7 +83,7 @@ These functions can be used for generating and coercing data to specific data ty
     </tr>
     <tr>
       <td scope="row" data-label="Function"><a href="#typerange"><code>type::range()</code></a></td>
-      <td scope="row" data-label="Description">Converts a value into a record range</td>
+      <td scope="row" data-label="Description">Converts a value into a range</td>
     </tr>
     <tr>
       <td scope="row" data-label="Function"><a href="#typerecord"><code>type::record()</code></a></td>
@@ -454,7 +454,7 @@ RETURN type::point([ 51.509865, -0.118092 ]);
 
 <Since v="v2.0.0" />
 
-The `type::range` function converts a value into a record range. It accepts a single argument, either a range or an array with two values. If the argument is an array, it will be converted into a range,  similar to [casting](/docs/surrealql/datamodel/casting).
+The `type::range` function converts a value into a [range](docs/surrealql/datamodel/ranges). It accepts a single argument, either a range or an array with two values. If the argument is an array, it will be converted into a range, similar to [casting](/docs/surrealql/datamodel/casting).
 
 ```surql title="API DEFINITION"
 type::range(range | array) -> range<record>
@@ -485,7 +485,7 @@ RETURN type::range([1,9,4]);
 The `type::record` function converts a value into a record.
 
 ```surql title="API DEFINITION"
-type::record(record | string, option<string>) -> range<record>
+type::record(record | string, option<string>) -> record
 ```
 
 The following example shows this function, and its output, when used in a [`RETURN`](/docs/surrealql/statements/return) statement: