String functions

String functions operate on string expressions only, and will return an error if used on any other values. The exception to this rule is toString(), which also accepts numbers, booleans and temporal values (i.e. DATE, ZONED TIME` LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION values).

Functions taking a STRING as input all operate on Unicode characters rather than on a standard char[]. For example, the size() function applied to any Unicode character will return 1, even if the character does not fit in the 16 bits of one char.

When toString() is applied to a temporal value, it returns a STRING representation suitable for parsing by the corresponding temporal functions. This STRING will therefore be formatted according to the ISO 8601 format.

See also String operators.

btrim()

Details

Syntax

btrim(input[, trimCharacterString])

Description

Returns the given STRING with leading and trailing whitespace removed, optionally specifying a trimCharacterString to remove.

Arguments

Name

Type

Description

input

STRING

A value from which the leading and trailing trim character will be removed.

trimCharacterString

STRING

A character to be removed from the start and end of the given string.

Returns

STRING

Considerations

btrim(null) returns null.

btrim(null, null) returns null.

btrim("hello", null) returns null.

btrim(null, ' ') returns null.

If trimCharacterString is not specified then all leading and trailing whitespace will be removed.

Example 1. btrim()
Query
RETURN btrim('   hello    '), btrim('xxyyhelloxyxy', 'xy')
Result
btrim(' hello') btrim('xxyyhelloxyxy', 'xy')

"hello"

"hello"

Rows: 1

left()

Details

Syntax

left(original, length)

Description

Returns a STRING containing the specified number (INTEGER) of leftmost characters in the given STRING.

Arguments

Name

Type

Description

original

STRING

A string value whose rightmost characters will be trimmed.

length

INTEGER

The length of the leftmost characters to be returned.

Returns

STRING

Considerations

left(null, length) return null.

left(null, null) return null.

left(original, null) will raise an error.

If length is not a positive INTEGER, an error is raised.

If length exceeds the size of original, original is returned.

Example 2. left()
Query
RETURN left('hello', 3)
Result
left('hello', 3)

"hel"

Rows: 1

lower()

Details

Syntax

lower(input)

Description

Returns the given STRING in lowercase.

Arguments

Name

Type

Description

input

STRING

A string to be converted into lowercase.

Returns

STRING

This function is an alias to the toLower() function, and it was introduced as part of Cypher®'s GQL conformance.

Considerations

lower(null) returns null.

Example 3. lower()
Query
RETURN lower('HELLO')
Result
lower('HELLO')

"hello"

Rows: 1

ltrim()

Details

Syntax

ltrim(input[, trimCharacterString])

Description

Returns the given STRING with leading whitespace removed, optionally specifying a trimCharacterString to remove.

Arguments

Name

Type

Description

input

STRING

A value from which the leading trim character will be removed.

trimCharacterString

STRING

A character to be removed from the start of the given string.

Returns

STRING

Considerations

ltrim(null) returns null.

ltrim(null, null) returns null.

ltrim("hello", null) returns null.

ltrim(null, ' ') returns null.

As of Neo4j 5.20, a trimCharacterString can be specified. If this is not specified all leading whitespace will be removed.

Example 4. ltrim()
Query
RETURN ltrim('   hello'), ltrim('xxyyhelloxyxy', 'xy')
Result
ltrim(' hello') ltrim('xxyyhelloxyxy', 'xy')

"hello"

"helloxyxy"

Rows: 1

normalize()

Details

Syntax

normalize(input[, normalForm])

Description

Normalize a STRING, optionally specifying a normalization form.

Arguments

Name

Type

Description

input

STRING

A value to be normalized.

normalForm

[NFC, NFD, NFKC, NFKD]

A keyword specifying any of the normal forms; NFC, NFD, NFKC or NFKD.

Returns

STRING

Unicode normalization is a process that transforms different representations of the same string into a standardized form. For more information, see the documentation for Unicode normalization forms.

The normalize() function is useful for converting STRING values into comparable forms. When comparing two STRING values, it is their Unicode codepoints that are compared. In Unicode, a codepoint for a character that looks the same may be represented by two, or more, different codepoints. For example, the character < can be represented as \uFE64 (﹤) or \u003C (<). To the human eye, the characters may appear identical. However, if compared, Cypher will return false as \uFE64 does not equal \u003C. Using the normalize() function, it is possible to normalize the codepoint \uFE64 to \u003C, creating a single codepoint representation, allowing them to be successfully compared.

Considerations

normalize(null) returns null.

Example 5. normalize()
Query
RETURN normalize('\u212B') = '\u00C5' AS result
Result
result

true

Rows: 1

To check if a STRING is normalized, use the IS NORMALIZED operator.

normalize() with specified normal form

There are two main types of normalization forms:

  • Canonical equivalence: The NFC (default) and NFD are forms of canonical equivalence. This means that codepoints that represent the same abstract character will be normalized to the same codepoint (and have the same appearance and behavior). The NFC form will always give the composed canonical form (in which the combined codes are replaced with a single representation, if possible). The`NFD` form gives the decomposed form (the opposite of the composed form, which converts the combined codepoints into a split form if possible).

  • Compatability normalization: NFKC and NFKD are forms of compatibility normalization. All canonically equivalent sequences are compatible, but not all compatible sequences are canonical. This means that a character normalized in NFC or NFD should also be normalized in NFKC and NFKD. Other characters with only slight differences in appearance should be compatibly equivalent.

For example, the Greek Upsilon with Acute and Hook Symbol ϓ can be represented by the Unicode codepoint: \u03D3.

  • Normalized in NFC: \u03D3 Greek Upsilon with Acute and Hook Symbol (ϓ)

  • Normalized in NFD: \u03D2\u0301 Greek Upsilon with Hook Symbol + Combining Acute Accent (ϓ)

  • Normalized in NFKC: \u038E Greek Capital Letter Upsilon with Tonos (Ύ)

  • Normalized in NFKD: \u03A5\u0301 Greek Capital Letter Upsilon + Combining Acute Accent (Ύ)

In the compatibility normalization forms (NFKC and NFKD) the character is visibly different as it no longer contains the hook symbol.

Example 6. normalize() with specified normalization form
Query
RETURN normalize('\uFE64', NFKC) = '\u003C' AS result
Result
result

true

Rows: 1

replace()

Details

Syntax

replace(original, search, replace)

Description

Returns a STRING in which all occurrences of a specified search STRING in the given STRING have been replaced by another (specified) replacement STRING.

Arguments

Name

Type

Description

original

STRING

The string to be modified.

search

STRING

The value to replace in the original string.

replace

STRING

The value to be inserted in the original string.

Returns

STRING

Considerations

If any argument is null, null will be returned.

If search is not found in original, original will be returned.

Example 7. replace()
Query
RETURN replace("hello", "l", "w")
Result
replace("hello", "l", "w")

"hewwo"

Rows: 1

reverse()

Details

Syntax

reverse(input)

Description

Returns a STRING or LIST<ANY> in which the order of all characters or elements in the given STRING or LIST<ANY> have been reversed.

Arguments

Name

Type

Description

input

STRING | LIST<ANY>

The string or list to be reversed.

Returns

STRING | LIST<ANY>

Considerations

reverse(null) returns null.

See also List functions → reverse.

Example 8. reverse
Query
RETURN reverse('palindrome')
Result
reverse('palindrome')

"emordnilap"

Rows: 1

right()

Details

Syntax

right(original, length)

Description

Returns a STRING containing the specified number of rightmost characters in the given STRING.

Arguments

Name

Type

Description

original

STRING

A string value whose leftmost characters will be trimmed.

length

INTEGER

The length of the rightmost characters to be returned.

Returns

STRING

Considerations

right(null, length) return null.

right(null, null) return null.

right(original, null) will raise an error.

If length is not a positive INTEGER, an error is raised.

If length exceeds the size of original, original is returned.

Example 9. right()
Query
RETURN right('hello', 3)
Result
right('hello', 3)

"llo"

Rows: 1

rtrim()

Details

Syntax

rtrim(input[, trimCharacterString])

Description

Returns the given STRING with trailing whitespace characters to remove, optionally specifying a trimCharacterString of characters to remove.

Arguments

Name

Type

Description

input

STRING

A value from which the leading and trailing trim character will be removed.

trimCharacterString

STRING

A character to be removed from the start and end of the given string.

Returns

STRING

Considerations

rtrim(null) returns null.

rtrim(null, null) returns null.

rtrim("hello", null) returns null.

rtrim(null, ' ') returns null.

As of Neo4j 5.20, a trimCharacterString can be specified. If this is not specified all trailing whitespace will be removed.

Example 10. rtrim()
Query
RETURN rtrim('hello   '), rtrim('xxyyhelloxyxy', 'xy')
Result
rtrim('hello ') rtrim('xxyyhelloxyxy', 'xy')

"hello"

"xxyyhello"

Rows: 1

split()

Details

Syntax

split(original, splitDelimiters)

Description

Returns a LIST<STRING> resulting from the splitting of the given STRING around matches of the given delimiter(s).

Arguments

Name

Type

Description

original

STRING

The string to be split.

splitDelimiters

STRING | LIST<STRING>

The string with which to split the original string.

Returns

LIST<STRING>

Considerations

split(null, splitDelimiter) return null.

split(original, null) return null

Example 11. split()
Query
RETURN split('one,two', ',')
Result
split('one,two', ',')

["one","two"]

Rows: 1

substring()

Details

Syntax

substring(original, start, length)

Description

Returns a substring of a given length from the given STRING, beginning with a 0-based index start.

Arguments

Name

Type

Description

original

STRING

The string to be shortened.

start

INTEGER

The start position of the new string.

length

INTEGER

The length of the new string.

Returns

STRING

Considerations

start uses a zero-based index.

If length is omitted, the function returns the substring starting at the position given by start and extending to the end of original.

If original is null, null is returned.

If either start or length is null or a negative integer, an error is raised.

If start is 0, the substring will start at the beginning of original.

If length is 0, the empty STRING will be returned.

Example 12. substring()
Query
RETURN substring('hello', 1, 3), substring('hello', 2)
Result
substring('hello', 1, 3) substring('hello', 2)

"ell"

"llo"

Rows: 1

toLower()

Details

Syntax

toLower(input)

Description

Returns the given STRING in lowercase.

Arguments

Name

Type

Description

input

STRING

A string to be converted into lowercase.

Returns

STRING

Considerations

toLower(null) returns null.

Example 13. toLower()
Query
RETURN toLower('HELLO')
Result
toLower('HELLO')

"hello"

Rows: 1

toString()

Details

Syntax

toString(input)

Description

Converts an INTEGER, FLOAT, BOOLEAN, POINT or temporal type (i.e. DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION) value to a STRING.

Arguments

Name

Type

Description

input

ANY

A value to be converted into a string.

Returns

STRING

Considerations

toString(null) returns null.

If input is a STRING, it will be returned unchanged.

This function will return an error if provided with an expression that is not an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME or ZONED DATETIME value.

Example 14. toString()
Query
RETURN
  toString(11.5),
  toString('already a string'),
  toString(true),
  toString(date({year: 1984, month: 10, day: 11})) AS dateString,
  toString(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
  toString(duration({minutes: 12, seconds: -60})) AS durationString
Result
toString(11.5) toString('already a string') toString(true) dateString datetimeString durationString

"11.5"

"already a string"

"true"

"1984-10-11"

"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"

"PT11M"

Rows: 1

toStringOrNull()

Details

Syntax

toStringOrNull(input)

Description

Converts an INTEGER, FLOAT, BOOLEAN, POINT or temporal type (i.e. DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME or DURATION) value to a STRING, or null if the value cannot be converted.

Arguments

Name

Type

Description

input

ANY

A value to be converted into a string or null.

Returns

STRING

Considerations

toStringOrNull(null) returns null.

If the input is not an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME or ZONED DATETIME value, null will be returned.

Example 15. toStringOrNull()
Query
RETURN toStringOrNull(11.5),
toStringOrNull('already a string'),
toStringOrNull(true),
toStringOrNull(date({year: 1984, month: 10, day: 11})) AS dateString,
toStringOrNull(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
toStringOrNull(duration({minutes: 12, seconds: -60})) AS durationString,
toStringOrNull(['A', 'B', 'C']) AS list
Result
toStringOrNull(11.5) toStringOrNull('already a string') toStringOrNull(true) dateString datetimeString durationString list

"11.5"

"already a string"

"true"

"1984-10-11"

"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"

"PT11M"

<null>

Rows: 1

toUpper()

Details

Syntax

toUpper(input)

Description

Returns the given STRING in uppercase.

Arguments

Name

Type

Description

input

STRING

A string to be converted into uppercase.

Returns

STRING

Considerations

toUpper(null) returns null.

Example 16. toUpper()
Query
RETURN toUpper('hello')
Result
toUpper('hello')

"HELLO"

Rows: 1

trim()

Details

Syntax

trim(trimSpecification, trimCharacterString, input)

Description

Returns the given STRING with leading and/or trailing trimCharacterString removed.

Arguments

Name

Type

Description

trimSpecification

[LEADING, TRAILING, BOTH]

The parts of the string to trim; LEADING, TRAILING, BOTH

trimCharacterString

STRING

The characters to be removed from the start and/or end of the given string.

input

STRING

A value from which all leading and/or trailing trim characters will be removed.

Returns

STRING

Considerations

trim(null) returns null.

trim(null FROM "hello") returns null.

trim(" " FROM null) returns null.

trim(BOTH null FROM null) returns null.

As of Neo4j 5.20, a trimSpecification and a trimCharacterString can be specified. If these are not specified all leading and/or trailing whitespace will be removed.

Example 17. trim()
Query
RETURN trim('   hello   '), trim(BOTH 'x' FROM 'xxxhelloxxx')
Result
trim(' hello ') trim(BOTH 'x' FROM 'xxxhelloxxx')

"hello"

"hello"

Rows: 1

upper()

Details

Syntax

upper(input)

Description

Returns the given STRING in uppercase.

Arguments

Name

Type

Description

input

STRING

A string to be converted into uppercase.

Returns

STRING

This function is an alias to the toUpper() function, and it was introduced as part of Cypher’s GQL conformance.

Considerations

upper(null) returns null.

Example 18. upper()
Query
RETURN upper('hello')
Result
upper('hello')

"HELLO"

Rows: 1