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.

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('anagram')

Result
reverse('anagram')
`"margana"`
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