SurrealDB Docs Logo

Enter a search query

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.

FunctionDescription
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 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'

On this page

© SurrealDB GitHub Discord Community Cloud Features Releases Install