Record IDs
In SurrealDB, document record IDs store both the table name, and the record ID.
Text Record IDs
Without annotation, text record IDs can contain letters, numbers and _
characters.
CREATE company:surrealdb SET name = 'SurrealDB';
Record IDs can contain complex characters, surrounded by the `
character.
CREATE article:`8424486b-85b3-4448-ac8d-5d51083391c7` SET time = time::now(), author = person:tobie;
Alternatively complex characters within record IDs can be surrounded by the ⟨
and ⟩
characters.
CREATE article:⟨8424486b-85b3-4448-ac8d-5d51083391c7⟩ SET time = time::now(), author = person:tobie;
Numeric Record IDs
If a numeric value is specified without any decimal point suffix and is within the range -9223372036854775808
to 9223372036854775807
then the value will be parsed, stored, and treated as a 64-bit integer.
CREATE temperature:17493 SET time = time::now(), celsius = 37.5;
Object-based Record IDs
Complex Record IDs support dynamic expressions, allowing parameters, and function expressions to be used as values within the IDs. This is useful in a timeseries context, or for ensuring locality between specific records in a table.
// Set a new parameter
LET $now = time::now();
// Create a record with a complex ID using an object
CREATE temperature:{ location: 'London', date: $now } SET
location = 'London',
date = $now,
temperature = 23.7
;
Array-based Record IDs
Complex Record IDs support dynamic expressions, allowing parameters, and function expressions to be used as values within the IDs. This is useful in a timeseries context, or for ensuring locality between specific records in a table.
// Set a new parameter
LET $now = time::now();
// Create a record with a complex ID using an array
CREATE temperature:['London', $now] SET
location = 'London',
date = $now,
temperature = 23.7
;
Generating Record IDs
Record IDs can be generated with a number of built-in ID generation functions. These allow for Record IDs to be generated using cryptographically-secure randomly-generated identifiers (which are suitable for dispersion across a distributed datastore), sequentially incrementing ULID
Record identifiers, and UUID
version 7 Record idenfitifiers.
// Generate a random Record ID
CREATE temperature:rand() SET time = time::now(), celsius = 37.5;
// Generate a ULID-based Record ID
CREATE temperature:ulid() SET time = time::now(), celsius = 37.5;
// Generate a UUIDv7-based Record ID
CREATE temperature:uuid() SET time = time::now(), celsius = 37.5;
Record ranges
SurrealDB supports the ability to query a range of records, using the record ID. The record ID ranges, retrieve records using the natural sorting order of the record IDs. These range queries can be used to query a range of records in a timeseries context.
-- Select all person records with IDs between the given range
SELECT * FROM person:1..1000;
-- Select all records for a particular location, inclusive
SELECT * FROM temperature:['London', NONE]..=['London', time::now()];
-- Select all temperature records with IDs less than a maximum value
SELECT * FROM temperature:..['London', '2022-08-29T08:09:31'];
-- Select all temperature records with IDs greater than a minimum value
SELECT * FROM temperature:['London', '2022-08-29T08:03:39']..;
-- Select all temperature records with IDs between the specified range
SELECT * FROM temperature:['London', '2022-08-29T08:03:39']..['London', '2022-08-29T08:09:31'];