SurrealDB Docs Logo

Enter a search query

String Functions

These functions can be used when working with and manipulating text and string values.

FunctionDescription
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 DEFINITION
string::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 DEFINITION
string::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

Note

This 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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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

Note

This 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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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>"); ['&lt;h1&gt;Safe&#32;Title&lt;&#47;h1&gt;&lt;script&gt;alert(&apos;XSS&apos;)&lt;&#47;script&gt;&lt;p&gt;Safe&#32;paragraph.&#32;Not&#32;safe&#32;&lt;span&#32;onload&#61;&apos;logout()&apos;&gt;event&lt;&#47;span&gt;.&lt;&#47;p&gt;']

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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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");
Response
true

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");
Response
true
RETURN string::is::datetime("23:56:00 2015-09-05", "%Y-%m-%d %H:%M");
Response
false

View all format options


string::is::domain

The string::is::domain function checks whether a value is a domain.

API DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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::numericfunction checks whether a value has only numeric characters.

API DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::is::record(string, option<string | table>) -> bool
Note

The 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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 DEFINITION
string::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 } ]

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 string::is::alphanum("MyStrongPassword123"); -- Method chaining syntax "MyStrongPassword123".is_alphanum();
Response
true

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!!!!'
© SurrealDB GitHub Discord Community Cloud Features Releases Install