SurrealDB Docs Logo

Enter a search query

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.

FunctionDescription
type::array()Converts a value into an array
type::bool()Converts a value into a boolean
type::bytes()Converts a value into bytes
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::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::range()Converts a value into a record range
type::record()Converts a value into a record
type::uuid()Converts a value into a UUID
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::none()Checks if given value is of type none
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::array

The type::array function converts a value into an array.

API DEFINITION
type::array(array | range) -> bool

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

RETURN type::array(1..=3); [1, 2, 3]

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

type::bool

The type::bool function converts a value into a boolean.

API DEFINITION
type::bool(bool | string) -> bool

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

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

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


type::bytes

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

API DEFINITION
type::bytes(bytes | string) -> bool

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

RETURN type::bytes("A few bytes"); -- encoding::base64::decode("QSBmZXcgYnl0ZXM")

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.

API DEFINITION
type::datetime(datetime | string) -> 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"); d"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.

API DEFINITION
type::decimal(decimal | float | int | number | string) -> 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.

API DEFINITION
type::duration(duration | string) -> 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 function projects a single field within a SELECT statement.

API DEFINITION
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 function projects one or more fields within a SELECT statement.

API DEFINITION
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.

API DEFINITION
type::float(decimal | float | int | number | string) -> 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.

API DEFINITION
type::int(decimal | float | int | number | string) -> 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.

API DEFINITION
type::number(decimal | float | int | number | string) -> 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.

API DEFINITION
type::point(array | point) -> point

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

RETURN type::point([ 51.509865, -0.118092 ]); -- (51.509865, -0.118092)

type::range

Available since: v2.0.0

The type::range function converts a value into a record range. It accepts a single argument, either a range or an array with two values. If the argument is an array, it will be converted into a range, similar to casting.

API DEFINITION
type::range(range | array) -> range<record>

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

RETURN type::range([1, 2]); [1..2] RETURN type::range(1..10) [1..10] RETURN type::range([1,9,4]); ['Expected a range but cannot convert [1, 9, 4] into a range']

type::record

Available since: v2.0.0

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

API DEFINITION
type::record(record | string, option<string>) -> range<record>

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

RETURN type::record("cat:one"); cat:one

The optional second argument can be used to ensure that the output is of a certain record type.

LET $good_input = "person:one"; LET $bad_input = "purrson:one"; RETURN type::record($good_input, "person"); RETURN type::record($bad_input, "person");
Output
-------- Query 1 -------- person:one -------- Query 2 -------- "Expected a record<person> but cannot convert 'purrson:one' into a record<person>"

type::string

The type::string function converts an value except NONE, NULL, and bytes into a string.

API DEFINITION
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 name.

API DEFINITION
type::table(record | string) -> string

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

RETURN [ type::table("person"), type::table(cat:one) ]; [ person, cat ]

As of version 2.0, SurrealDB no longer eagerly parses strings into record IDs. As such, the output of the last item (“dog:two”) in the following example will differ. In version 1.x, it will be eagerly parsed into a record ID after which the dog table name will be returned, while in version 2.x it will be treated as a string and converted into the table name dog:two.

RETURN [ type::table(55), type::table(cat:one), type::table("dog"), type::table("dog:two"), ];
Output (V1.x)
[ `55`, cat, dog, dog ]

type::thing

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

API DEFINITION
type::thing(any, any) -> record

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::uuid

The type::uuid function converts a value into a UUID.

API DEFINITION
type::uuid(string | uuid) -> uuid

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

RETURN type::uuid("0191f946-936f-7223-bef5-aebbc527ad80"); u'0191f946-936f-7223-bef5-aebbc527ad80'

type::is::array

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

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

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

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

RETURN type::is::duration('1970-01-01T00:00:00'); false

type::is::float

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

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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::none

Available since: v1.1.0

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

API DEFINITION
type::is::none(any) -> bool

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

RETURN type::is::none(NONE); true

type::is::null

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

API DEFINITION
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); true

type::is::multiline

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

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
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.

API DEFINITION
type::is::record(any, any) -> bool

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

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

Validate a table

Available since: v1.1.0

Check if user:tobie is a record on the test table
RETURN type::is::record(user:tobie, 'test'); false

type::is::string

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

API DEFINITION
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.

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

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

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


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 type::is::record(r"person:aeon", "cat") -- Method chaining syntax r"person:aeon".is_record("cat");
Response
false
© SurrealDB GitHub Discord Community Cloud Features Releases Install