NoteRecord functions before SurrealDB 2.0 were located inside the module meta. Their behaviour has not changed.
These functions can be used to retrieve specific metadata from a SurrealDB Record ID.
Function | Description |
---|---|
record::exists() | Checks to see if a SurrealDB Record ID exists |
record::id() | Extracts and returns the table id from a SurrealDB Record ID |
record::tb() | Extracts and returns the table name from a SurrealDB Record ID |
record::refs() | Extracts and returns the table name from a SurrealDB Record ID |
record::exists
The record::exists
function checks to see if a given record exists.
API DEFINITIONrecord::exists(record) -> bool
A simple example showing the output of this function when a record does not exist and when it does:
RETURN record::exists(r"person:tobie"); -- false CREATE person:tobie; RETURN record::exists(r"person:tobie"); -- true
A longer example of record::exists
using method syntax:
FOR $person IN ["Haakon_VII", "Ferdinand_I", "Manuel_II", "Wilhelm_II", "George_I", "Albert_I", "Alfonso_XIII", "George_V", "Frederick_VIII"] { LET $record_name = type::thing("person", $person.lowercase()); IF !$record_name.exists() { CREATE $record_name; } }
record::id
The record::id
function extracts and returns the table id from a SurrealDB Record ID.
API DEFINITIONrecord::id(record) -> value
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN record::id(person:tobie); "tobie"
record::refs
Available since: v2.2.0
The record::refs
function returns the record IDs of any records that have a record link along with a REFERENCES
clause.
API DEFINITIONrecord::refs(record) -> array<record> record::refs(record, $table_name: string) -> array<record> record::refs(record, $table_name: string, $field_name: string) -> array<record>
This function can be used on its own to return all references to a single record.
DEFINE FIELD best_friend ON person TYPE option<record<person>> REFERENCE; -- Both Billy and Bobby think Gaston is their best friend CREATE person:billy, person:bobby SET best_friend = person:gaston; -- But not Gaston CREATE person:gaston SET best_friend = NONE; person:gaston.refs();
Output[ person:billy, person:bobby ]
It can be followed by a single string to filter references to only include those from a certain table.
DEFINE FIELD located_in ON city TYPE option<record<country>> REFERENCE; DEFINE FIELD located_in ON state TYPE option<record<country>> REFERENCE; CREATE country:germany; CREATE state:bavaria, city:munich SET located_in = country:germany; country:germany.refs('city'); country:germany.refs('state');
Output-------- Query -------- [ city:munich ] -------- Query -------- [ state:bavaria ]
If followed by a second string, it will filter references by table name as well as field name.
DEFINE FIELD owner ON dog TYPE option<record<person>> REFERENCE; DEFINE FIELD acquaintances ON dog TYPE option<array<record<person>>> REFERENCE; DEFINE FIELD roommates ON cat TYPE option<record<person>> REFERENCE; DEFINE FIELD acquaintances ON cat TYPE option<array<record<person>>> REFERENCE; CREATE person:one, person:two, person:three; CREATE dog:mr_bark SET owner = person:one, acquaintances = [person:two, person:three]; CREATE cat:mr_meow SET roommates = [person:one], acquaintances = [person:two, person:three]; -- All the dogs that consider person:one the owner person:one.refs('dog', 'owner'); -- All the cats that consider person:one the roommate person:one.refs('cat', 'roommate'); -- All the dogs acquainted with person:two person:two.refs('dog', 'acquaintances');
Output-------- Query -------- [ dog:mr_bark ] -------- Query -------- [ cat:mr_meow ] -------- Query -------- [ dog:mr_bark ]
record::tb
The record::tb
function extracts and returns the table name from a SurrealDB Record ID.
API DEFINITIONrecord::tb(record) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN record::tb(person:tobie); "person"
Available since: v2.0.0
Method chaining allows functions to be called using the .
dot operator on a value of a certain type instead of the full path of the function followed by the value.
-- Traditional syntax record::id(r"person:aeon"); -- Method chaining syntax r"person:aeon".id();
Response'aeon'
This is particularly useful for readability when a function is called multiple times.
-- Traditional syntax record::table(array::max([r"person:aeon", r"person:landevin"])); -- Method chaining syntax [r"person:aeon", r"person:landevin"].max().table();
Response'person'