Casting

In the SurrealDB type system, values can be converted to other values efficiently. This is useful if input is specified in a query which must be of a certain type, or if a user may have provided a parameter with an incorrect type.

<array>

The <array> casting function converts a range into an array.

RETURN <array> 1..=3;

[1, 2, 3]

<array<T>>

The <array<T>> casting function converts a value into an array of the specified type.

Note

When using this casting function, the value must be an array and each element in the array will be cast to the specified type.

RETURN <array<int>> ["42", "314", "271", "137", "141"];

[42, 314, 271, 137, 141]

RETURN <array<string>> [42, 314, 271, 137, 141];

["42", "314", "271", "137", "141"]

A cast into an array of more than one possible type can also be used. In this case, the cast will attempt to cast into the possible types in order. As such, the string in the first query below will be cast into a datetime but not in the second.

RETURN [
  <array<datetime|string>>["2020-09-09", "21 Jan 2020"],
  <array<string|datetime>>["2020-09-09", "21 Jan 2020"]
];

Output
[
	[
		d'2020-09-09T00:00:00Z',
		'21 Jan 2020'
	],
	[
		'2020-09-09',
		'21 Jan 2020'
	]
]

An example of even more complex casting which attempts to cast each item in the input array into a record<user>, then record<person>, then array<record<user>>, and finally string.

RETURN <array<record<user | person> | array<record<user>> | string>> [
	'person:one',
	'user:two',
	[
		'user:three',
		'user:four'
	],
	'not_a_person_or_user'
];

Output
[
	person:one,
	user:two,
	[
		user:three,
		user:four
	],
	'not_a_person_or_user'
]

<bool>

The <bool casting function converts a value into a boolean.

RETURN <bool> "true";

true

RETURN <bool> "false";

false

<datetime>

The <datetime> casting function converts a value into a datetime.

RETURN <datetime> "2022-06-07";

d'2022-06-07T00:00:00Z'

<decimal>

The <decimal> casting function converts a value into an infinite precision decimal number.

RETURN <decimal> 13.572948467293847293841093845679289;

13.572948467293847293841093845679289

RETURN <decimal> "13.572948467293847293841093845679289";

"13.572948467293847293841093845679289"

RETURN <decimal> 1.193847193847193847193487E11;

"119384719384.7193847193487"

<duration>

The <duration> casting function converts a value into a duration.

RETURN <duration> "1h30m";

1h30m

<float>

The <float> casting function converts a value into a floating point number.

RETURN <float> 13.572948467293847293841093845679289;

13.572948467293847

RETURN <float> "13.572948467293847293841093845679289";

13.572948467293847

<int>

The <int> casting function converts a value into an integer.

RETURN <int> 53;

53

<number>

The <number> casting function converts a value into a number.

RETURN <number> 13.572948467293847293841093845679289;

"13.572948467293847293841093845679289"

RETURN <number> "13.572948467293847293841093845679289";

"13.572948467293847293841093845679289"

RETURN <number> 1.193847193847193847193487E11;

"119384719384.7193847193487"

<record>

The <record> casting function converts a value into a record.

Keep in mind when using this casting function that if the equivalent record id does not exist, it will not return anything.

SELECT id FROM <record> (s"person:hrebrffwm4sr2yifglta");

Output
{ id: person:hrebrffwm4sr2yifglta }

<record<T>>

The <record<T>> casting function converts a value into a record.

Keep in mind when using this casting function that if the equivalent record id does not exist, it will not return anything.

SELECT id FROM <record> (s"person:hrebrffwm4sr2yifglta");

{ id: person:hrebrffwm4sr2yifglta }

A cast into a number of possible record types can also be used.

RETURN [
  <record<user|person>>"user:one",
  <array<record<user|person>>>["person:one", "user:two"]
];

Output
[
	user:one,
	[
		person:one,
		user:two
	]
]

<set> and <set<T>>

The <set> casting function converts a value into a set. As a set is simply an array with deduplicated items, all of the examples in the section for arrays will work.

RETURN [
  <set<datetime|string>>["2020-09-09", "21 Jan 2020"],
  <set<string|datetime>>["2020-09-09", "21 Jan 2020"]
];

Output
[
	[
		d'2020-09-09T00:00:00Z',
		'21 Jan 2020'
	],
	[
		'2020-09-09',
		'21 Jan 2020'
	]
]

Using a <set> cast on an existing array is functionally identical to using the array::distinct() function.

LET $array = [1,1,3,4,4,4,4,4,4];

RETURN [
    $array.distinct(),
    <set>$array
];

Output
[
	[
		1,
		3,
		4
	],
	[
		1,
		3,
		4
	]
]

<string>

The <string> casting function converts a value into a string.

RETURN <string> true;

"true"

RETURN <string> 1.3463;

"1.3463"

RETURN <string> false;

"false"

<uuid>

The <uuid> casting function converts a value into a UUID.

SELECT id FROM <uuid> "a8f30d8b-db67-47ec-8b38-ef703e05ad1b";

[ u'a8f30d8b-db67-47ec-8b38-ef703e05ad1b' ]

General notes on casting

Syntax and order

As the parser ignores spaces and new lines, casting syntax can include spaces or new lines as desired.

-- Surrealist formatted syntax
RETURN  <array<bool | string | float>> [
	'9.1',
	'true',
	15h
];

-- Maybe someone's preferred syntax
RETURN <array
        <bool | string | float>
      >
[ '9.1', 'true', 15h ];

When more than one cast type is specified, SurrealDB will attempt to convert into the type in the order specified. In the example above, while the input '9.1' could have been converted to a float, the type string comes first in the cast syntax and thus '9.1' remains as a string.

Output
[
	'9.1',
	true,
	'15h'
]

Casting vs. affixes

SurrealDB uses a number of affixes to force the parser to treat an input as a certain type instead of another. These affixes may seem at first glance to be identical to casts, as the following queries show.

-- Both return a record person:one
RETURN r"person:one";
RETURN <record>"person:one";
-- Returns a string 'person:one'
RETURN "person:one";

-- Both return a decimal 98dec
RETURN 98dec;
RETURN <decimal>98;
-- Returns an int 98
RETURN 98;

However, casts and affixes work in different ways:

• A cast is a way to convert from one type into another.
• An affix is an instruction to the parser to treat an input as a certain type.

These differences become clear when working with input that is less than ideal or does not work with a certain type. For example, floats by nature become imprecise after a certain number of digits.

RETURN [
  8.888,
  8.8888888888888888
];

Output
[
	8.888f,
	8.88888888888889f
]

In this case, a decimal can be used which will allow a greater number of digits after the decimal point. However, casting the above numbers into a decimal will result in the same inaccurate output.

RETURN [
	<decimal>8.888,
	<decimal>8.888888888888888
];

Output
[
	8.888dec,
	8.88888888888889dec
]

This is because the parser will first treat the number as a float and then cast it into a decimal.

However, using the dec suffix will inform the parser that the entire input is to be treated as a decimal and it will never pass through a stage in which it is a float.

RETURN [
	8.888dec,
	8.888888888888888dec
];

Output
[
	8.888dec,
	8.888888888888888dec
]

Similarly, an attempt to cast a number that is too large for an int into a decimal will not work, as the parser will first attempt to handle the number on the right before moving on to the cast.

<decimal>9999999999999999999;

Output
Parse error: Failed to parse number: number too large to fit in target type

However, if the same number is followed by the dec suffix, the parser will be aware that the input is meant to be treated as a decimal from the outset and the query will succeed.

RETURN 9999999999999999999dec;