Back to top
Documentation SurrealQL Functions Type functions

Type functions

These functions can be used for generating and coercing data to specific data types. These functions are useful when accepting input values in client libraries, and ensuring that they are the desired type within SQL statements.

Function Description
type::bool() Converts a value into a boolean
type::datetime() Converts a value into a datetime
type::decimal() Converts a value into a decimal
type::duration() Converts a value into a duration
type::field() Projects a single field within a SELECT statement
type::fields() Projects a multiple fields within a SELECT statement
type::float() Converts a value into a floating point number
type::int() Converts a value into an integer
type::number() Converts a value into a number
type::point() Converts a value into a geometry point
type::regex() Converts a value into a regular expression
type::string() Converts a value into a string
type::table() Converts a value into a table
type::thing() Converts a value into a record pointer
type::is::array() Checks if given value is of type array
type::is::bool() Checks if given value is of type bool
type::is::bytes() Checks if given value is of type bytes
type::is::collection() Checks if given value is of type collection
type::is::datetime() Checks if given value is of type datetime
type::is::decimal() Checks if given value is of type decimal
type::is::duration() Checks if given value is of type duration
type::is::float() Checks if given value is of type float
type::is::geometry() Checks if given value is of type geometry
type::is::int() Checks if given value is of type int
type::is::line() Checks if given value is of type line
type::is::null() Checks if given value is of type null
type::is::multiline() Checks if given value is of type multiline
type::is::multipoint() Checks if given value is of type multipoint
type::is::multipolygon() Checks if given value is of type multipolygon
type::is::number() Checks if given value is of type number
type::is::object() Checks if given value is of type object
type::is::point() Checks if given value is of type point
type::is::polygon() Checks if given value is of type polygon
type::is::record() Checks if given value is of type record
type::is::string() Checks if given value is of type string
type::is::uuid() Checks if given value is of type uuid

type::bool

The type::bool function converts a value into a bool, if the value is truthy.

type::bool(any) -> bool

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

RETURN type::bool(12345);
true

This is the equivalent of using <bool> to cast a value to a boolean.

type::datetime

The type::datetime function converts a value into a datetime.

type::datetime(any) -> datetime

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

RETURN type::datetime("2022-04-27T18:12:27+00:00");
"2022-04-27T18:12:27Z"

This is the equivalent of using <datetime> to cast a value to a datetime.

type::decimal

The type::decimal function converts a value into a decimal.

type::decimal(any) -> decimal

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

RETURN type::decimal("12345");
12345.00

This is the equivalent of using <decimal> to cast a value to a decimal.

type::duration

The type::duration function converts a value into a duration.

type::duration(any) -> duration

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

RETURN type::duration("4h");
4h

This is the equivalent of using <duration> to cast a value to a duration.

type::field

The type::field projects a single field within a SELECT statement.

type::field($field)

The following example shows this function, and its output:

CREATE person:test SET title = 'Mr', name.first = 'Tobie', name.last = 'Morgan Hitchcock';

LET $param = 'name.first';

SELECT type::field($param), type::field('name.last') FROM person;

SELECT VALUE { 'firstname': type::field($param), lastname: type::field('name.last') } FROM person;

SELECT VALUE [type::field($param), type::field('name.last')] FROM person;
[
	{
		id: person:test,
		title: 'Mr',
		name: {
			first: 'Tobie',
			last: 'Morgan Hitchcock',
	    }
	}
]

type::fields

The type::fields projects multiple fields within a SELECT statement.

type::fields($fields)

The following example shows this function, and its output

CREATE person:test SET title = 'Mr', name.first = 'Tobie', name.last = 'Morgan Hitchcock';

LET $param = ['name.first', 'name.last'];

SELECT type::fields($param), type::fields(['title']) FROM person;

SELECT VALUE { 'names': type::fields($param) } FROM person;

SELECT VALUE type::fields($param) FROM person;
[
	{
		id: person:test,
		title: 'Mr',
		name: {
			first: 'Tobie',
			last: 'Morgan Hitchcock',
		}
	}
]

type::float

The type::float function converts a value into a float.

type::float(any) -> float

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

RETURN type::float("12345");
12345.0

This is the equivalent of using <float> to cast a value to a float.

type::int

The type::int function converts a value into an integer.

type::int(any) -> int

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

RETURN type::int("12345");
12345

This is the equivalent of using <int> to cast a value to a int.

type::number

The type::number function converts a value into a number.

type::number(any) -> number

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

RETURN type::number("12345");
12345

This is the equivalent of using <number> to cast a value to a number.

type::point

The type::point function converts a value into a geometry point.

type::point(any) -> point

This function also accepts two arguments (longitude and latitude values).

type::point(number, number) -> point

The following examples show this function, and its output, when used in a RETURN statement:

RETURN type::point(51.509865, -0.118092);
{
	"type": "Point",
	"coordinates": [
		-0.10231019499999999,
		51.49576478
	]
}
RETURN type::point([ 51.509865, -0.118092 ]);
{
	"type": "Point",
	"coordinates": [
		-0.10231019499999999,
		51.49576478
	]
}

type::regex

The type::regex function converts a value into a regex.

type::regex(any) -> regex

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

RETURN type::regex("/[A-Z]{3}/");
FIXME

type::string

The type::string function converts a value into a string.

type::string(any) -> string

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

RETURN type::string(12345);
"12345"

This is the equivalent of using <string> to cast a value to a string.

type::table

The type::table function converts a value into a table definition.

type::table(any) -> table

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

LET $table = "person";
RETURN type::table($table);

type::thing

The type::thing function converts a value into a record pointer definition.

type::thing(any, any) -> thing

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

LET $tb = "person";
LET $id = "tobie";
RETURN type::thing($tb, $id);

type::is::array

The type::is::array function checks if the passed value is of type array.

type::is::array(any) -> bool

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

RETURN type::is::array([ 'a', 'b', 'c' ]);
true

type::is::bool

The type::is::bool function checks if the passed value is of type bool.

type::is::bool(any) -> bool

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

RETURN type::is::bool(true);
true

type::is::bytes

The type::is::bytes function checks if the passed value is of type bytes.

type::is::bytes(any) -> bool

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

RETURN type::is::bytes("I am not bytes");
false

type::is::collection

The type::is::collection function checks if the passed value is of type collection.

type::is::collection(any) -> bool

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

RETURN type::is::collection("I am not a collection");
false

type::is::datetime

The type::is::datetime function checks if the passed value is of type datetime.

type::is::datetime(any) -> bool

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

RETURN type::is::datetime(time::now());
true

type::is::decimal

The type::is::decimal function checks if the passed value is of type decimal.

type::is::decimal(any) -> bool

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

RETURN type::is::decimal({{ "<" }}decimal> 13.5719384719384719385639856394139476937756394756);
true

type::is::duration

The type::is::duration function checks if the passed value is of type duration.

type::is::duration(any) -> bool

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

RETURN type::is::duration({{ "<" }}datetime> '1970-01-01T00:00:00');
true

type::is::float

The type::is::float function checks if the passed value is of type float.

type::is::float(any) -> bool

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

RETURN type::is::float({{ "<" }}float> 41.5);
true

type::is::geometry

The type::is::geometry function checks if the passed value is of type geometry.

type::is::geometry(any) -> bool

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

RETURN type::is::geometry((-0.118092, 51.509865));
true

type::is::int

The type::is::int function checks if the passed value is of type int.

type::is::int(any) -> bool

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

RETURN type::is::int({{ "<" }}int> 123);
true

type::is::line

The type::is::line function checks if the passed value is of type line.

type::is::line(any) -> bool

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

RETURN type::is::line("I am not a line");
false

type::is::null

The type::is::null function checks if the passed value is of type null.

type::is::null(any) -> bool

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

RETURN type::is::null(NULL);
null

type::is::multiline

The type::is::multiline function checks if the passed value is of type multiline.

type::is::multiline(any) -> bool

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

RETURN type::is::multiline("I am not a multiline");
false

type::is::multipoint

The type::is::multipoint function checks if the passed value is of type multipoint.

type::is::multipoint(any) -> bool

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

RETURN type::is::multipoint("I am not a multipoint");
false

type::is::multipolygon

The type::is::multipolygon function checks if the passed value is of type multipolygon.

type::is::multipolygon(any) -> bool

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

RETURN type::is::multipolygon("I am not a multipolygon");
false

type::is::number

The type::is::number function checks if the passed value is of type number.

type::is::number(any) -> bool

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

RETURN type::is::number(123);
true

type::is::object

The type::is::object function checks if the passed value is of type object.

type::is::object(any) -> bool

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

RETURN type::is::object({ hello: 'world' });
true

type::is::point

The type::is::point function checks if the passed value is of type point.

type::is::point(any) -> bool

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

RETURN type::is::point((-0.118092, 51.509865));
true

type::is::polygon

The type::is::polygon function checks if the passed value is of type polygon.

type::is::polygon(any) -> bool

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

RETURN type::is::polygon("I am not a polygon");
false

type::is::record

The type::is::record function checks if the passed value is of type record.

type::is::record(any) -> bool

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

RETURN type::is::record(user:tobie);
true

type::is::string

The type::is::string function checks if the passed value is of type string.

type::is::string(any) -> bool

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

RETURN type::is::string("abc");
true

type::is::uuid

The type::is::uuid function checks if the passed value is of type uuid.

type::is::uuid(any) -> bool

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

RETURN type::is::uuid("018a6680-bef9-701b-9025-e1754f296a0f");
true