Casting data values

Cypher® supports a number of functions to cast values to different data types. This section will provide an overview of those functions, as well examples of how to use them in practice.

Functions for converting data values

The following functions are available for casting data values:

Function Description

toBoolean()

Converts a STRING, INTEGER, or BOOLEAN value to a BOOLEAN value.

toBooleanList()

Converts a LIST<ANY> and returns a LIST<BOOLEAN> values. If any values are not convertible to BOOLEAN they will be null in the LIST<BOOLEAN> returned.

toBooleanOrNull()

Converts a STRING, INTEGER or BOOLEAN value to a BOOLEAN value. For any other input value, null will be returned.

toFloat()

Converts an INTEGER, FLOAT, or a STRING value to a FLOAT value. Otherwise null is returned.

toFloatList()

Converts a LIST<ANY> and returns a LIST<FLOAT> values. If any values are not convertible to FLOAT they will be null in the LIST<FLOAT> returned.

toFloatOrNull()

Converts an INTEGER, FLOAT, or a STRING value to a FLOAT. For any other input value, null will be returned.

toInteger()

Converts a BOOLEAN, INTEGER, FLOAT or a STRING value to an INTEGER value.

toIntegerList()

Converts a LIST<ANY> to a LIST<INTEGER> values. If any values are not convertible to INTEGER they will be null in the LIST<INTEGER> returned.

toIntegerOrNull()

Converts a BOOLEAN, INTEGER, FLOAT or a STRING value to an INTEGER value. For any other input value, null will be returned.

toString()

Converts an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME, or ZONED DATETIME value to a STRING value.

toStringList()

Converts a LIST<ANY> and returns a LIST<STRING> values. If any values are not convertible to STRING they will be null in the LIST<STRING> returned.

toStringOrNull()

Converts an INTEGER, FLOAT, BOOLEAN, STRING, POINT, DURATION, DATE, ZONED TIME, LOCAL TIME, LOCAL DATETIME, or ZONED DATETIME value to a STRING. For any other input value, null will be returned.

More information about these, and many other functions, can be found in the section on Functions.

Examples

The following graph is used for the examples below:

values and types converting data graph

To recreate it, run the following query against an empty Neo4j database:

CREATE (keanu:Person {name:'Keanu Reeves', age: 58, active:true}),
       (carrieAnne:Person  {name:'Carrie-Anne Moss', age: 55, active:true}),
       (keanu)-[r:KNOWS {since:1999}]->(carrieAnne)

Returning converted values

In the below query, the function toFloat is used to cast two STRING values. It shows that null is returned if the data casting is not possible.

MATCH (keanu:Person {name:'Keanu Reeves'})
RETURN toFloat(keanu.age), toInteger(keanu.name)
Table 1. Result
toFloat(keanu.age) toInteger(keanu.name)

58.0

null

If the function toFloat is passed an unsupported value (such as a DATE value), it will throw an error:

Query
WITH date({
  year: 2023, month: 5, day: 2
}) AS d
RETURN toFloat(d)
Error message
Type mismatch: expected Float, Integer, Number or String but was Date (line 4, column 16 (offset: 66))
"RETURN toFloat(d)"

However, if the same value is passed to the function toFloatOrNull, null will be returned.

Query
WITH date({
  year: 2023, month: 5, day: 2
}) AS d
RETURN toFloatOrNull(d)
Table 2. Result
toFloatOrNull(d)

null

It is also possible to return casted values as a list. The below query uses the toStringList to cast all passed values into STRING values, and return them in as a LIST<STRING>:

MATCH (keanu:Person {name:'Keanu Reeves'})
RETURN toStringList([keanu.name, keanu.age]) AS keanuList
Table 3. Result
keanuList

["Keanu Reeves", "58"]

Updating property value types

The functions to cast data values can be used to update property values on nodes and relationships. The below query casts the age (INTEGER), active (BOOLEAN), and since(INTEGER) properties to STRING values:

MATCH (keanu:Person {name:'Keanu Reeves'})-[r:KNOWS]-()
SET keanu.age = toString(keanu.age),
    keanu.active = toString(keanu.active),
    r.since = toString(r.since)
RETURN keanu.age, keanu.active, r.since
Table 4. Result
keanu.age keanu.active r.since

"58"

"true"

"1999"