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.

left()

left() returns a STRING containing the specified number of leftmost characters of the given STRING.

Syntax:

left(original, length)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

length

An expression that returns a positive INTEGER.

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 1. left()
Query
RETURN left('hello', 3)
Table 1. Result
left('hello', 3)

"hel"

Rows: 1

ltrim()

ltrim() returns the original STRING with leading whitespace removed.

Syntax:

ltrim(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

ltrim(null) returns null.

Example 2. ltrim()
Query
RETURN ltrim('   hello')
Table 2. Result
ltrim(' hello')

"hello"

Rows: 1

normalize()

This feature was introduced in Neo4j 5.17.

normalize() returns the given STRING normalized using the NFC Unicode normalization form.

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.

Syntax:

normalize(input)

Returns:

STRING

Arguments:

Name Description

input

An expression that returns a STRING.

Considerations:

normalize(null) returns null.

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

true

Rows: 1

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

normalize(), with specified normal form

This feature was introduced in Neo4j 5.17.

normalize() returns the given STRING normalized using the specified normalization form. The normalization form can be of type NFC, NFD, NFKC or NFKD.

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.

Syntax:

normalize(input, normalForm)

Returns:

STRING

Arguments:

Name Description

input

An expression that returns a STRING.

normalForm

A keyword specifying the normal form, can be NFC, NFD, NFKC or NFKD.

Considerations:

normalize(null, NFC) returns null.

Example 4. normalize()
Query
RETURN normalize('\uFE64', NFKC) = '\u003C' AS result
Table 4. Result
result

true

Rows: 1

To check if a STRING is normalized in a specific Unicode normal form, use the IS NORMALIZED operator with a specified normalization form.

replace()

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

Syntax:

replace(original, search, replace)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

search

An expression that specifies the STRING to be replaced in original.

replace

An expression that specifies the replacement STRING.

Considerations:

If any argument is null, null will be returned.

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

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

"hewwo"

Rows: 1

reverse()

reverse() returns a STRING in which the order of all characters in the given STRING have been reversed.

Syntax:

reverse(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

reverse(null) returns null.

Example 6. reverse
Query
RETURN reverse('anagram')
Table 6. Result
reverse('anagram')

"margana"

Rows: 1

right()

right() returns a STRING containing the specified number of rightmost characters in the given STRING.

Syntax:

right(original, length)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

length

An expression that returns a positive INTEGER.

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 7. right()
Query
RETURN right('hello', 3)
Table 7. Result
right('hello', 3)

"llo"

Rows: 1

rtrim()

rtrim() returns the given STRING with trailing whitespace removed.

Syntax:

rtrim(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

rtrim(null) returns null.

Example 8. rtrim()
Query
RETURN rtrim('hello   ')
Table 8. Result
rtrim('hello ')

"hello"

Rows: 1

split()

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

Syntax:

split(original, splitDelimiter)

Returns:

LIST<STRING>

Arguments:

Name Description

original

An expression that returns a STRING.

splitDelimiter

The STRING with which to split original.

Considerations:

split(null, splitDelimiter) return null.

split(original, null) return null

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

["one","two"]

Rows: 1

substring()

substring() returns a substring of the given STRING, beginning with a zero-based index start and length.

Syntax:

substring(original, start [, length])

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

start

An expression that returns a positive INTEGER, denoting the position at which the substring will begin.

length

An expression that returns a positive INTEGER, denoting how many characters of original will be returned.

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 10. substring()
Query
RETURN substring('hello', 1, 3), substring('hello', 2)
Table 10. Result
substring('hello', 1, 3) substring('hello', 2)

"ell"

"llo"

Rows: 1

toLower()

toLower() returns the given STRING in lowercase.

Syntax:

toLower(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

toLower(null) returns null.

Example 11. toLower()
Query
RETURN toLower('HELLO')
Table 11. Result
toLower('HELLO')

"hello"

Rows: 1

toString()

toString() converts an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME or ZONED DATETIME value to a STRING.

Syntax:

toString(expression)

Returns:

STRING

Arguments:

Name Description

expression

An expression that returns an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME or ZONED DATETIME value.

Considerations:

toString(null) returns null.

If expression 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 12. 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
Table 12. 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()

The function toStringOrNull() converts an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME or ZONED DATETIME value to a STRING.

Syntax:

toStringOrNull(expression)

Returns:

STRING or null.

Arguments:

Name Description

expression

Any expression that returns a value.

Considerations:

toStringOrNull(null) returns null.

If the expression 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 13. 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
Table 13. 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()

toUpper() returns the given STRING in uppercase.

Syntax:

toUpper(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

toUpper(null) returns null.

Example 14. toUpper()
Query
RETURN toUpper('hello')
Table 14. Result
toUpper('hello')

"HELLO"

Rows: 1

trim()

trim() returns the given STRING with leading and trailing whitespace removed.

Syntax:

trim(original)

Returns:

STRING

Arguments:

Name Description

original

An expression that returns a STRING.

Considerations:

trim(null) returns null.

Example 15. trim()
Query
RETURN trim('   hello   ')
Table 15. Result
trim(' hello ')

"hello"

Rows: 1