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

Function	Description
`toBoolean()`	Converts a string, integer, or boolean value to a boolean value.
`toBooleanList()`	Converts a list of values and returns a list of boolean values. If any values are not convertible to boolean they will be `null` in the list 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, floating point, or a string value to a floating point number value. Otherwise `null` is returned.
`toFloatList()`	Converts a list of values and returns a list of floating point values. If any values are not convertible to floating point they will be `null` in the list returned.
`toFloatOrNull()`	Converts an integer, floating point, or a string value to a floating point number. For any other input value, `null` will be returned.
`toInteger()`	Converts a boolean, integer, floating point or a string value to an integer value.
`toIntegerList()`	Converts a list of values and returns a list of integer values. If any values are not convertible to integer they will be `null` in the list returned.
`toIntegertOrNull()`	Converts a boolean, integer, floating point 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, time, localtime, localdatetime, or datetime value to a string value.
`toStringList()`	Converts a list of values and returns a list of string values. If any values are not convertible to string they will be `null` in the list returned.
`toStringOrNull()`	Converts an integer, float, boolean, string, point, duration, date, time, localtime, localdatetime, or datetime value to a string. For any other input value, `null` will be returned.

toBoolean()

Converts a string, integer, or boolean value to a boolean value.

toBooleanList()

Converts a list of values and returns a list of boolean values. If any values are not convertible to boolean they will be null in the list 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, floating point, or a string value to a floating point number value. Otherwise null is returned.

toFloatList()

Converts a list of values and returns a list of floating point values. If any values are not convertible to floating point they will be null in the list returned.

toFloatOrNull()

Converts an integer, floating point, or a string value to a floating point number. For any other input value, null will be returned.

toInteger()

Converts a boolean, integer, floating point or a string value to an integer value.

toIntegerList()

Converts a list of values and returns a list of integer values. If any values are not convertible to integer they will be null in the list returned.

toIntegertOrNull()

Converts a boolean, integer, floating point 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, time, localtime, localdatetime, or datetime value to a string value.

toStringList()

Converts a list of values and returns a list of string values. If any values are not convertible to string they will be null in the list returned.

toStringOrNull()

Converts an integer, float, boolean, string, point, duration, date, time, localtime, localdatetime, or 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:

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), 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 strings, and return them in a list:

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"`

Was this page helpful?