Strings
Strings can be used to store text values. All text fields can include unicode values, emojis, and tabular and multine breaks.
CREATE person SET text = 'Lorem ipsum dolor sit amet';
Strings can be created using single quotation marks, or double quotation marks.
CREATE person SET text = "Lorem ipsum dolor sit amet";
Any string in SurrealDB can include unicode text.
CREATE person SET text = "I ❤️ SurrealDB";
Strings can also include line breaks.
CREATE person SET text = "This
is
over
multiple
lines";
String prefixes Since 1.1.0
In SurrealQL, strings can be enthusiastically converted into Record IDs, Datetimes or to UUIDs. String prefixes are a solution to this problem, in that you as the developer get to specify what the "string" contains.
Overview
Here are a couple of examples of how string prefixes work:
RETURN s"5:20";
RETURN r"person:tobie";
s -> string
The most commonly used string prefix, s tells the parser that the contents of this string is just a string. The s prefix shows up in the database output to make it clear to the viewer as well that the output is a string.
For example, the following query will be returned as a record ID:
-- Will be interpreted as a record ID, because of the structure with the semicolon:
RETURN "5:20";
Response⟨5⟩:20
However, if the s prefix is used, the output will be returned as a string:
-- Forcefully parsed as just a string
RETURN s"5:20";
Responses'5:20'
Another example is in the case of a datetime with a time zone offset, this will be eagerly turned into a UTC datetime:
RETURN "2024-04-24T03:07:32+09:00";
UTC output instead of +09:00 timezone'2024-04-23T18:07:32Z'
The s prefix can be used to maintain the original format.
RETURN s"2024-04-24T03:07:32+09:00";
Responses'2024-04-24T03:07:32+09:00'
r -> record
The r prefix tells the parser that the contents of this string is a record ID.
RETURN r"person:john";
d -> datetime
The d prefix tells the parser that the contents of this string is a DateTime.
RETURN d"2023-11-28T11:41:20.262Z";
u -> UUID
The u prefix tells the parser that the contents of this string is a UUID.
RETURN u"8c54161f-d4fe-4a74-9409-ed1e137040c1";
String prefixes vs. casting
String prefixes seem outwardly similar to casting, but differ in behaviour. A string prefix is an instruction to the parser to treat an input in a certain way, whereas a cast is an instruction to the database to convert one type into another.
As a result, incorrect input with a cast will generate an error:
// Change _ to - in both examples to fix the input
RETURN <uuid>"018f0e6a_9b95-7ecc-8a38-aea7bf3627dd";
RETURN <datetime>"2024_06-06T12:00:00Z";
Response-------- Query 1 --------
"Expected a uuid but cannot convert '018f0e6a-9b95-7ecc-8a38-aea7bf3627d' into a uuid"
-------- Query 2 --------
"Expected a datetime but cannot convert '2024-06-06T12:00:00' into a datetime"
But the same input using a string prefix will not even parse until the input is valid.
// Will not parse in either case until _ is changed to -
RETURN u"018f0e6a_9b95-7ecc-8a38-aea7bf3627dd";
RETURN d"2024_06-06T12:00:00Z";
This also allows for immediate error messages on which part of the input is incorrect. As seen in the image below, the parser is able to inform the user that an underscore at column 18 is the issue.
