[!NOTE]
Since version 3.0.0-alpha.8, the
::is::
functions (e.g.type::is::record()
) now use underscores (e.g.type::is_record()
) to better match the intent of the function and method syntax.
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::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 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_range() | Checks if given value is of type range |
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 DEFINITIONtype::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 an array.
type::bool
The type::bool
function converts a value into a boolean.
API DEFINITIONtype::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 DEFINITIONtype::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"); -- b"4120666577206279746573"
This is the equivalent of using <bytes>
to cast a value to bytes.
type::datetime
The type::datetime
function converts a value into a datetime.
API DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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', } } ]
Available since: v3.0.0-alpha.8
This function can be used after the OMIT
clause of a SELECT
statement.
LET $omit = "id"; CREATE person SET name = "Galen", surname = "Pathwarden", age = 19; SELECT * OMIT type::field($omit) FROM person;
Output[ { age: 19, name: 'Galen', surname: 'Pathwarden' } ]
type::fields
The type::fields
function projects one or more fields within a SELECT statement.
API DEFINITIONtype::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', } } ]
Available since: v3.0.0-alpha.8
This function can be used after the OMIT
clause of a SELECT
statement.
LET $omit = ["id", "age"]; CREATE person SET name = "Galen", surname = "Pathwarden", age = 19; SELECT * OMIT type::fields($omit) FROM person;
Output[ { name: 'Galen', surname: 'Pathwarden' } ]
type::file
Available since: v3.0.0-alpha.1
The type::file
function converts two strings representing a bucket name and a key into a file pointer.
API DEFINITIONtype::file(bucket: string, key: string) -> file
An example of a file pointer created using this function:
type::file("my_bucket", "file_name")
Outputf"my_bucket:/file_name"
The following query shows the equivalent file pointer when created using the f
prefix:
type::file("my_bucket", "file_name") == f"my_bucket:/file_name"; -- true
Once a bucket has been defined, operations using one of the file functions can be performed on the file pointer.
DEFINE BUCKET my_bucket BACKEND "memory"; type::file("my_bucket", "file_name").put("Some data inside"); type::file("my_bucket", "file_name").get();
Outputb"536F6D65206461746120696E73696465"
type::float
The type::float
function converts a value into a float.
API DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 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 DEFINITIONtype::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 DEFINITIONtype::record(record | string, option<string>) -> 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 any value except NONE
, NULL
, and bytes
into a string.
API DEFINITIONtype::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::string_lossy
Available since: v3.0.0-alpha.1
The type::string_lossy
function converts any value except NONE
, NULL
, and bytes
into a string. In the case of bytes, it will not return an error if the bytes are not valid UTF-8. Instead, invalid bytes will be replaced with the character �
(U+FFFD REPLACEMENT CHARACTER
, used in Unicode to represent a decoding error).
API DEFINITIONtype::string(any) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
-- Contains some invalid bytes type::string_lossy(<bytes>[83, 117, 114, 255, 114, 101, 97, 254, 108, 68, 66]); -- valid bytes type::string_lossy(<bytes>[ 83, 117, 114, 114, 101, 97, 108, 68, 66 ]);
Output-------- Query -------- 'Sur�rea�lDB' -------- Query -------- 'SurrealDB'
This is similar to using <string>
to cast a value to a string, except that an input of bytes will not fail.
type::table
The type::table
function converts a value into a table name.
API DEFINITIONtype::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 ]
Output (V2.x)[ `55`, cat, dog, `dog:two` ]
type::thing
The type::thing
function converts a value into a record pointer definition.
API DEFINITIONtype::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);
An example of this function being used to turn an array of objects into records to be created or upserted:
FOR $data IN [ { id: 9, name: 'Billy' }, { id: 10, name: 'Bobby' } ] { UPSERT type::thing('person', $data.id) CONTENT $data; };
An example of the same except in which the num
field is to be used as the record’s ID. In this case, it can be mapped with the array::map()
function to rename num
as id
so that the following CONTENT
clause does not create both a num
and an id
with the same value.
FOR $data IN [ { name: 'Billy', num: 9 }, { name: 'Bobby', num: 10 }, ].map(|$o| { id: $o.num, name: $o.name }) { UPSERT type::thing('person', $data.id) CONTENT $data; };
If the second argument passed into type::thing
is a record ID, the latter part of the ID (the record identifier) will be extracted and used.
type::thing("person", person:mat); -- person:mat
The output of the above function call will thus be person:mat
, not person:person:mat
.
type::uuid
The type::uuid
function converts a value into a UUID.
API DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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 DEFINITIONtype::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_range
The type::is_range
function checks if the passed value is of type range
.
API DEFINITIONtype::is_range(any) -> bool
type::is_range(0..1); true // method syntax (0..1).is_range(); true
type::is_record
The type::is_record
function checks if the passed value is of type record
.
API DEFINITIONtype::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
Available since: v1.1.0
Check if user:tobie is a record on the test tableRETURN 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 DEFINITIONtype::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 DEFINITIONtype::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
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");
Responsefalse