Record functions

Note

Record 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.

record::exists

The record::exists function checks to see if a given record exists.

API DEFINITION
record::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 DEFINITION
record::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 DEFINITION
record::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 DEFINITION
record::tb(record) -> string

The following example shows this function, and its output, when used in a RETURN statement:

RETURN record::tb(person:tobie);

"person"

Method chaining

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'