These functions can be used when working with and manipulating text and string values.
Function | Description |
---|---|
string::concat() | Concatenates strings together |
string::contains() | Check whether a string contains another string |
string::ends_with() | Checks whether a string ends with another string |
string::join() | Joins strings together with a delimiter |
string::len() | Returns the length of a string |
string::lowercase() | Converts a string to lowercase |
string::matches() | Performs a regex match on a string |
string::repeat() | Repeats a string a number of times |
string::replace() | Replaces an occurrence of a string with another string |
string::reverse() | Reverses a string |
string::slice() | Extracts and returns a section of a string |
string::slug() | Converts a string into human and URL-friendly string |
string::split() | Divides a string into an ordered list of substrings |
string::starts_with() | Checks whether a string starts with another string |
string::trim() | Removes whitespace from the start and end of a string |
string::uppercase() | Converts a string to uppercase |
string::words() | Splits a string into an array of separate words |
string::html::encode() | Encodes special characters into HTML entities to prevent HTML injection |
string::html::sanitize() | Sanitizes HTML code to prevent the most dangerous subset of HTML injection |
string::is::alphanum() | Checks whether a value has only alphanumeric characters |
string::is::alpha() | Checks whether a value has only alpha characters |
string::is::ascii() | Checks whether a value has only ascii characters |
string::is::datetime() | Checks whether a string representation of a date and time matches a specified format |
string::is::domain() | Checks whether a value is a domain |
string::is::email() | Checks whether a value is an email |
string::is::hexadecimal() | Checks whether a value is hexadecimal |
string::is::ip() | Checks whether a value is an IP address |
string::is::ipv4() | Checks whether a value is an IP v4 address |
string::is::ipv6() | Checks whether a value is an IP v6 address |
string::is::latitude() | Checks whether a value is a latitude value |
string::is::longitude() | Checks whether a value is a longitude value |
string::is::numeric() | Checks whether a value has only numeric characters |
string::is::record() | Checks whether a string is a Record ID, optionally of a certain table |
string::is::semver() | Checks whether a value matches a semver version |
string::is::url() | Checks whether a value is a valid URL |
string::is::uuid() | Checks whether a string is a UUID |
string::semver::compare() | Performs a comparison between two semver strings |
string::semver::major() | Extract the major version from a semver string |
string::semver::minor() | Extract the minor version from a semver string |
string::semver::patch() | Extract the patch version from a semver string |
string::semver::inc::major() | Increment the major version of a semver string |
string::semver::inc::minor() | Increment the minor version of a semver string |
string::semver::inc::patch() | Increment the patch version of a semver string |
string::semver::set::major() | Set the major version of a semver string |
string::semver::set::minor() | Set the minor version of a semver string |
string::semver::set::patch() | Set the patch version of a semver string |
string::similarity::fuzzy() | Return the similarity score of fuzzy matching strings |
string::concat
The string::concat
function concatenates strings together.
API DEFINITIONstring::concat(string, ...) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::concat('this', ' ', 'is', ' ', 'a', ' ', 'test'); "this is a test"
string::contains
The string::contains
function checks whether a string contains another string.
API DEFINITIONstring::contains(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::contains('abcdefg', 'cde'); true
string::ends_with
Available since: v2.0.0
NoteThis function was known as
string::endsWith
in versions of SurrrealDB before 2.0. The behaviour has not changed.
The string::ends_with
function checks whether a string ends with another string.
API DEFINITIONstring::ends_with(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::ends_with('some test', 'test'); true
string::join
The string::join
function joins strings together with a delimiter.
API DEFINITIONstring::join(string, string...) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::join(', ', 'a', 'list', 'of', 'items'); "a, list, of, items"
string::len
The string::len
function returns the length of a given string.
API DEFINITIONstring::len(string) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::len('this is a test'); 14
string::lowercase
The string::lowercase
function converts a string to lowercase.
API DEFINITIONstring::lowercase(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::lowercase('THIS IS A TEST'); "this is a test"
string::matches
The string::matches
function performs a regex match on a string.
API DEFINITIONstring::matches(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN [ string::matches("grey", "gr(a|e)y"), string::matches("gray", "gr(a|e)y") ]; [ true, true ]
string::repeat
The string::repeat
function repeats a string a number of times.
API DEFINITIONstring::repeat(string, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::repeat('test', 3); "testtesttest"
string::replace
The string::replace
function replaces an occurrence of a string with another string.
API DEFINITIONstring::replace(string, string, string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::replace('this is a test', 'a test', 'awesome'); "this is awesome"
string::reverse
The string::reverse
function reverses a string.
API DEFINITIONstring::reverse(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::reverse('this is a test'); "tset a si siht"
string::slice
The string::slice
function extracts and returns a section of a string.
API DEFINITIONstring::slice(string, number, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::slice('this is a test', 10, 4); "test"
string::slug
The string::slug
function converts a string into a human and URL-friendly string.
API DEFINITIONstring::slug(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::slug('SurrealDB has launched #database #awesome'); "surrealdb-has-launched-database-awesome"
string::split
The string::split
function splits a string by a given delimiter.
API DEFINITIONstring::split(string, string) -> array
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::split('this, is, a, list', ', '); ["this", "is", "a", "list"]
string::starts_with
Available since: v2.0.0
NoteThis function was known as
string::startsWith
in versions of SurrrealDB before 2.0. The behaviour has not changed.
The string::starts_with
function checks whether a string starts with another string.
API DEFINITIONstring::starts_with(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::starts_with('some test', 'some'); true
string::trim
The string::trim
function removes whitespace from the start and end of a string.
API DEFINITIONstring::trim(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::trim(' this is a test '); "this is a test"
string::uppercase
The string::uppercase
function converts a string to uppercase.
API DEFINITIONstring::uppercase(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::uppercase('this is a test'); "THIS IS A TEST"
string::words
The string::words
function splits a string into an array of separate words.
API DEFINITIONstring::words(string) -> array
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::words('this is a test'); ["this", "is", "a", "test"]
string::html::encode
Available since: v2.0.0
The string::html::encode
function encodes special characters into HTML entities to prevent HTML injection. It is recommended to use this function in most cases when retrieving any untrusted content that may be rendered inside of an HTML document. You can learn more about its behavior from the original implementation.
API DEFINITIONstring::html::encode(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::html::encode("<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>"); ['<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>']
string::html::sanitize
Available since: v2.0.0
The string::html::sanitize
function sanitizes HTML code to prevent the most dangerous subset of HTML injection that can lead to attacks like cross-site scripting, layout breaking or clickjacking. This function will keep any other HTML syntax intact in order to support user-generated content that needs to contain HTML styling. It is only recommended to rely on this function if you want to allow the creators of the content to have some control over its HTML styling. You can learn more about its behavior from the original implementation.
API DEFINITIONstring::html::sanitize(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::html::sanitize("<h1>Safe Title</h1><script>alert('XSS')</script><p>Safe paragraph. Not safe <span onload='logout()'>event</span>.</p>"); ['<h1>Safe Title</h1><p>Safe paragraph. Not safe <span>event</span>.</p>']
string::is::alphanum
The string::is::alphanum
function checks whether a value has only alphanumeric characters.
API DEFINITIONstring::is::alphanum(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::alphanum("ABC123"); true
string::is::alpha
The string::is::alpha
function checks whether a value has only alpha characters.
API DEFINITIONstring::is::alpha(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::alpha("ABCDEF"); true
string::is::ascii
The string::is::ascii
function checks whether a value has only ascii characters.
API DEFINITIONstring::is::ascii(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::ascii("ABC123"); true
string::is::datetime
The string::is::datetime
function checks whether a string representation of a date and time matches a specified format.
API DEFINITIONstring::is::datetime(string, string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::datetime("2015-09-05 23:56:04", "%Y-%m-%d %H:%M:%S");
Responsetrue
This can be useful when validating datetimes obtained from other sources that do not use the ISO 8601 format.
RETURN string::is::datetime("5sep2024pm012345.6789", "%d%b%Y%p%I%M%S%.f");
Responsetrue
RETURN string::is::datetime("23:56:00 2015-09-05", "%Y-%m-%d %H:%M");
Responsefalse
string::is::domain
The string::is::domain
function checks whether a value is a domain.
API DEFINITIONstring::is::domain(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::domain("surrealdb.com"); true
string::is::email
The string::is::email
function checks whether a value is an email.
API DEFINITIONstring::is::email(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::email("info@surrealdb.com"); true
string::is::hexadecimal
The string::is::hexadecimal
function checks whether a value is hexadecimal.
API DEFINITIONstring::is::hexadecimal(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::hexadecimal("ff009e"); true
string::is::ip
Available since: v2.0.0
The string::is::ip
function checks whether a value is an IP address.
API DEFINITIONstring::is::ip(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::ip("192.168.0.1"); true
string::is::ipv4
Available since: v2.0.0
The string::is::ipv4
function checks whether a value is an IP v4 address.
API DEFINITIONstring::is::ipv4(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::ipv4("192.168.0.1"); true
string::is::ipv6
Available since: v2.0.0
The string::is::ipv6
function checks whether a value is an IP v6 address.
API DEFINITIONstring::is::ipv6(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::ipv6("2001:0db8:85a3:0000:0000:8a2e:0370:7334"); true
string::is::latitude
The string::is::latitude
function checks whether a value is a latitude value.
API DEFINITIONstring::is::latitude(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::latitude("-0.118092"); true
string::is::longitude
The string::is::longitude
function checks whether a value is a longitude value.
API DEFINITIONstring::is::longitude(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::longitude("51.509865"); true
string::is::numeric
The string::is::numeric
function checks whether a value has only numeric characters.
API DEFINITIONstring::is::numeric(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::numeric("1484091748"); true
string::is::semver
The string::is::semver
function checks whether a value matches a semver version.
API DEFINITIONstring::is::semver(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::semver("1.0.0"); true
string::is::url
The string::is::url
function checks whether a value is a valid URL.
API DEFINITIONstring::is::url(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::url("https://surrealdb.com"); true
string::is::record
The string::is::record
function checks whether a string is a Record ID.
API DEFINITIONstring::is::record(string, option<string | table>) -> bool
NoteThe second argument is optional and can be used to specify the table name that the record ID should belong to. If the table name is provided, the function will check if the record ID belongs to that table only.
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::record("person:test"); -- true RETURN string::is::record("person:test", "person"); -- true RETURN string::is::record("person:test", "other"); -- false RETURN string::is::record("not a record id"); -- false
string::is::uuid
The string::is::uuid
function checks whether a string is a UUID.
API DEFINITIONstring::is::uuid(string) -> bool
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::is::uuid("018a6680-bef9-701b-9025-e1754f296a0f"); true
string::semver::compare
Available since: v1.2.0
The string::semver::compare
function performs a comparison on two semver strings and returns a number. A value of -1
indicates the first version is lower than the second, 0
indicates both versions are equal, and 1
indicates the first version is higher than the second.
API DEFINITIONstring::semver::compare(string, string) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::compare("1.0.0", "1.3.5"); -1
string::semver::major
Available since: v1.2.0
The string::semver::major
function extracts the major number out of a semver string.
API DEFINITIONstring::semver::major(string) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::major("3.2.6"); 3
string::semver::minor
Available since: v1.2.0
The string::semver::minor
function extracts the minor number out of a semver string.
API DEFINITIONstring::semver::minor(string) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::minor("3.2.6"); 2
string::semver::patch
Available since: v1.2.0
The string::semver::patch
function extracts the patch number out of a semver string.
API DEFINITIONstring::semver::patch(string) -> number
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::patch("3.2.6"); 6
string::semver::inc::major
Available since: v1.2.0
The string::semver::inc::major
function increments the major number of a semver string. As a result, the minor and patch numbers are reset to zero.
API DEFINITIONstring::semver::inc::major(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::inc::major("1.2.3"); "2.0.0"
string::semver::inc::minor
Available since: v1.2.0
The string::semver::inc::minor
function increments the minor number of a semver string. As a result, the patch number is reset to zero.
API DEFINITIONstring::semver::inc::minor(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::inc::minor("1.2.3"); "1.3.0"
string::semver::inc::patch
Available since: v1.2.0
The string::semver::inc::patch
function increments the patch number of a semver string.
API DEFINITIONstring::semver::inc::patch(string) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::inc::patch("1.2.3"); "1.2.4"
string::semver::set::major
Available since: v1.2.0
The string::semver::set::major
function sets the major number of a semver string without changing the minor and patch numbers.
API DEFINITIONstring::semver::set::major(string, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::set::major("1.2.3", 9); "9.2.3"
string::semver::set::minor
Available since: v1.2.0
The string::semver::set::minor
function sets the minor number of a semver string without changing the major and patch numbers.
API DEFINITIONstring::semver::set::minor(string, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::set::minor("1.2.3", 9); "1.9.3"
string::semver::set::patch
Available since: v1.2.0
The string::semver::set::patch
function sets the patch number of a semver string without changing the major and minor numbers.
API DEFINITIONstring::semver::set::patch(string, number) -> string
The following example shows this function, and its output, when used in a RETURN
statement:
RETURN string::semver::set::patch("1.2.3", 9); "1.2.9"
string::similarity::fuzzy
While the ~ operator is a quick go-to to see if two strings are a fuzzy match, it returns a boolean that does not indicate relative similarity.
RETURN "SurrealDB" ~ "db"; -- true RETURN "SurrealDB" ~ "surrealdb" -- true
The string::similarity::fuzzy
function allows a comparison of similarity to be made. Any value that is greater than 0 is considered a fuzzy match.
-- returns 51 RETURN string::similarity::fuzzy("DB", "DB"); -- returns 47 RETURN string::similarity::fuzzy("DB", "db");
The similarity score is not based on a single score such as 1 to 100, but is built up over the course of the algorithm used to compare one string to another and will be higher for longer strings. As a result, similarity can only be compared from a single string to a number of possible matches, but not multiple strings to a number of possible matches.
While the first two uses of the function in the following example compare identical strings, the longer string returns a much higher fuzzy score.
-- returns 51 RETURN string::similarity::fuzzy("DB", "DB"); -- returns 2997 RETURN string::similarity::fuzzy( "Surreal Cloud Beta is now live! We are excited to announce that we are inviting users from the waitlist to join. Stay tuned for your invitation!", "Surreal Cloud Beta is now live! We are excited to announce that we are inviting users from the waitlist to join. Stay tuned for your invitation!" ); -- returns 151 despite nowhere close to exact match RETURN string::similarity::fuzzy( "Surreal Cloud Beta is now live! We are excited to announce that we are inviting users from the waitlist to join. Stay tuned for your invitation!", "Surreal" );
A longer example showing a comparison of similarity scores to one another:
LET $original = "SurrealDB"; LET $strings = ["SurralDB", "surrealdb", "DB", "Surreal", "real", "basebase", "eel", "eal"]; FOR $string IN $strings { LET $score = string::similarity::fuzzy($original, $string); IF $score > 0 { CREATE comparison SET of = $original + '\t' + $string, score = $score }; }; SELECT of, score FROM comparison ORDER BY score DESC;
Response[ { of: 'SurrealDB surrealdb', score: 187 }, { of: 'SurrealDB SurralDB', score: 165 }, { of: 'SurrealDB Surreal', score: 151 }, { of: 'SurrealDB real', score: 75 }, { of: 'SurrealDB eal', score: 55 }, { of: 'SurrealDB DB', score: 41 } ]
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 string::is::alphanum("MyStrongPassword123"); -- Method chaining syntax "MyStrongPassword123".is_alphanum();
Responsetrue
This is particularly useful for readability when a function is called multiple times.
-- Traditional syntax string::concat( string::uppercase( string::replace( string::replace("I'll send you a check for the catalog", "ck", "que") , "og", "ogue") ) , "!!!!"); -- Method chaining syntax "I'll send you a check for the catalog" .replace("ck", "que") .replace("og", "ogue") .uppercase() .concat("!!!!");
Response'I'LL SEND YOU A CHEQUE FOR THE CATALOGUE!!!!'