Skip to content
Developer Edition runs on one host and does not require a product license file. Need multi-host deployment or performance testing at scale? Explore Enterprise Edition

Cast value expression

The cast value expression converts the data type of an expression to a specified target data type.

Syntax

cast_value_expression
CAST ( value_expression NULL AS target_data_type ) 

cast_value_expression ::=
    'CAST' '(' (value_expression | 'NULL') 'AS' target_data_type ')'

Parameters

value_expression

The value expression whose data type is to be converted to the target data type. For more information about the supported conversions between different data types, see the Data type conversions section below.

For more information about data types, see Data types.

target_data_type

The target data type to which the source data type is to be converted.

Data type conversions

Conversions between data types are classified into explicit and implicit conversions.

  • Explicit conversion: Manual conversion between data types using the CAST value expression.
  • Implicit conversion: Automatic conversion between data types, which may result in loss of precision. For example, converting an INT64 to a DOUBLE may result in a loss of precision. If implicit conversion is allowed between two data types, explicit conversion is also allowed. For more information, see the When an implicit conversion occurs section below.

The conventions for explicit and implicit conversions differ by data types. The following rules apply:

  • For predefined data types and constructed data types list and record, both explicit and implicit conversions between them are allowed.
  • For the constructed data type path and node and edge references, only implicit conversion is allowed according to the conversions between the data types of the nodes or edges in the path. For more information, see the Conversions between constructed data types and between node/edge references section below.

Conversions between predefined data types

The following table lists the supported conversions between predefined data types. The leftmost column lists the source data types, and the top row lists the target data types.

FROM/TO NULL BOOLEAN INT8 INT16 INT32 INT64 UINT8 UINT16 UINT32 UINT64 FLOAT DOUBLE DECIMAL DURATION DATE LOCAL TIME ZONED TIME LOCAL DATETIME ZONED DATETIME STRING VECTOR
NULL ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 🚫 ✅ ✅ ✅ ✅ ✅ ✅ ✅
BOOLEAN 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
INT8 🚫 🚫 ✅ ✅ ✅ ➡️ ➡️ ➡️ ➡️ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
INT16 🚫 🚫 ➡️ ✅ ✅ ➡️ ➡️ ➡️ ➡️ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
INT32 🚫 🚫 ➡️ ➡️ ✅ ➡️ ➡️ ➡️ ➡️ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
INT64 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
UINT8 🚫 🚫 ➡️ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
UINT16 🚫 🚫 ➡️ ➡️ ✅ ✅ ➡️ ✅ ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
UINT32 🚫 🚫 ➡️ ➡️ ➡️ ✅ ➡️ ➡️ ✅ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
UINT64 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ✅ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
FLOAT 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ✅ ➡️ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
DOUBLE 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
DECIMAL 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ✅ ✅ 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
DURATION 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ 🚫
DATE 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ➡️ 🚫
LOCAL TIME 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ✅ ✅ ✅ ➡️ 🚫
ZONED TIME 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ ➡️ ✅ ➡️ 🚫
LOCAL DATETIME 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ ➡️ ➡️ ✅ ➡️ 🚫
ZONED DATETIME 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ 🚫
STRING 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ ➡️ 🚫 ➡️ ➡️ ➡️ ➡️ ➡️ 🚫
VECTOR 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫 🚫
  • ➡️ indicates that the explicit conversion from the source data type to the target data type is supported by using the CAST value expression.
  • 🚫 indicates that the conversion from the source data type to the target data type is not allowed.
  • ✅ indicates that implicit conversion from the source data type to the target data type is allowed by the system.

Note

  • The STRING data type in the above list refers to the Character String data type.
  • The null literal can be converted to any data type except DURATION, with its value remaining null.

Conversions involving spatial types

The following table lists the supported conversions involving spatial types.

FROM/TO NULL STRING GEOGRAPHY(ANY) GEOGRAPHY(POINT) GEOGRAPHY(LINESTRING) GEOGRAPHY(POLYGON)
NULL ✅ ✅ ✅ ✅ ✅
STRING 🚫 ➡️ ➡️ ➡️ ➡️
GEOGRAPHY(ANY) 🚫 ➡️ ➡️ ➡️ ➡️
GEOGRAPHY(POINT) 🚫 ➡️ ➡️ 🚫 🚫
GEOGRAPHY(LINESTRING) 🚫 ➡️ ➡️ 🚫 🚫
GEOGRAPHY(POLYGON) 🚫 ➡️ ➡️ 🚫 🚫

Conversions between constructed data types and between node/edge references

  • List: Explicit and implicit conversions are allowed if the source list element type can be cast to the target list element type.
  • Set: Explicit and implicit conversions are allowed if the source set element type can be cast to the target set element type.
  • Map: Explicit and implicit conversions are allowed if both the key and value types in the source map can be cast to those in the target map.
  • Record: Explicit and implicit conversions are allowed if the source and target record types have the same field names, and every field type in the source record can be cast to the corresponding field type in the target record.
  • Path: Implicit conversion is allowed if every node/edge type in the source path can be cast to at least one node/edge type in the target path.
  • Node/Edge: Implicit conversion is allowed if the source node/edge type's property names are a subset of the target's, and every property type in the source node/edge can be cast to the corresponding property type in the target node/edge.

Conversions of special values

GQL supports casting string representations of special values to FLOAT(FLOAT32), DOUBLE (FLOAT64), and DECIMAL types.

The following table lists the supported string representations of special values.

Special value Supported string formats (case-insensitive)
Positive infinity 'Inf', '+Inf', 'Infinity', '+Infinity'
Negative infinity '-Inf', '-Infinity'
Not a number 'NaN'

Note

Leading and trailing spaces are automatically trimmed.

For information about examples of casting these special values, see the below Cast special values section.

When an implicit conversion occurs

We try to do implicit conversion if there is a need. For example:

  • In function value expressions, when input argument types differ from declared parameter types.
  • In list value expressions, when input types differ.
  • In case/when value expressions, when then/else branch types differ.
  • In union operators, when input types for the same output column differ.
  • In INSERT or SET statements, when data types differ from those specified by the graph type.
  • In CALL procedure statements, when input argument types differ from declared parameter types.

An error occurs if an implicit conversion is required, but the corresponding type of implicit conversion is not permitted.

Examples

Cast null to a specified data type

'''
RETURN CAST (null AS INT8) AS i8, 
       CAST (null AS INT16) AS i16, 
       CAST (null AS INT32) AS i32, 
       CAST (null AS INT64) AS i64, 
       CAST (null AS UINT8) AS u8, 
       CAST (null AS UINT16) AS u16, 
       CAST (null AS UINT32) AS u32, 
       CAST (null AS UINT64) AS u64, 
       CAST (null AS FLOAT) AS f1, 
       CAST (null AS DOUBLE) AS d2, 
       CAST (null AS DECIMAL) AS d3, 
       CAST (null AS BOOLEAN) AS b1, 
       CAST (null AS STRING) AS s1, 
       CAST (null AS LOCAL DATETIME) AS ld, 
       CAST (null AS ZONED DATETIME) AS zd, 
       CAST (null AS DATE) AS d1, 
       CAST (null AS LOCAL TIME) AS lt, 
       CAST (null AS ZONED TIME) AS zt, 
       CAST (null AS LIST<INT>) AS e,
       CAST (null AS VECTOR<3, FLOAT>) AS v,
       CAST (null AS GEOGRAPHY(any)) AS g1, 
       CAST (null AS GEOGRAPHY(POINT)) AS g2
'''

The preceding example converts the null literal to the specified data type.

Return:

+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+
| i8   | i16  | i32  | i64  | u8   | u16  | u32  | u64  | f1   | d2   | d3   | b1   | s1   | ld   | zd   | d1   | lt   | zt   | e    | v    | g1   | g2   |
+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+
| null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null | null |
+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+------+

Cast a data type to a string type

'''
RETURN CAST (1 AS STRING) AS i1, 
       CAST (2378737378237 AS STRING) AS i2, 
       CAST (true AS STRING) AS b1, 
       CAST (DATETIME "2012-03-04T05:06:07.0890" AS STRING) AS d1, 
       CAST (DATE "2012-03-04" AS STRING) AS d2, 
       CAST (TIME "05:06:07.0890" AS STRING) AS d3, 
       CAST (zoned_time("05:06:07.0890 -0200") AS STRING) AS d4, 
       CAST (zoned_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS STRING) AS d5, 
       CAST (duration({seconds:4, milliseconds:5, microseconds:6}) AS STRING) AS d6
'''

The preceding example converts the specified data type to a string.

Return:

+----+---------------+------+----------------------------+------------+-----------------+-----------------------+----------------------------------+-------------------+
| i1 | i2            | b1   | d1                         | d2         | d3              | d4                    | d5                               | d6                |
+----+---------------+------+----------------------------+------------+-----------------+-----------------------+----------------------------------+-------------------+
| 1  | 2378737378237 | true | 2012-03-04T05:06:07.089000 | 2012-03-04 | 05:06:07.089000 | 07:06:07.089000 +0000 | 2012-03-04T05:06:07.089000 +0000 | P0DT0H0M4.005006S |
+----+---------------+------+----------------------------+------------+-----------------+-----------------------+----------------------------------+-------------------+

Cast a string type to a temporal type

'''
RETURN CAST ("2025-01-04" AS DATE) AS d1, 
       CAST ("23:23:23.000000" AS LOCAL TIME) AS lt,
       CAST ("2025-01-04T23:23:23.000000" AS LOCAL DATETIME) AS ld, 
       CAST ("23:23:23.000000 +0800" AS ZONED TIME) AS zt, 
       CAST ("2025-01-04T23:23:23.000000 +0800" AS ZONED DATETIME) AS zd
'''

Note

When a string type is converted to a temporal type, the input must match the format of the temporal type configured for the current session. To view the formats in effect, see SHOW CURRENT_SESSION TIME FORMATS.

Return:

+------------+-----------------+----------------------------+------------------+-----------------------------+
| d1         | lt              | ld                         | zt               | zd                          |
+------------+-----------------+----------------------------+------------------+-----------------------------+
| 2025-01-04 | 23:23:23.000000 | 2025-01-04T23:23:23.000000 | 15:23:23.000000Z | 2025-01-04T15:23:23.000000Z |
+------------+-----------------+----------------------------+------------------+-----------------------------+

Cast a data type to a numeric type

'''
RETURN CAST (1 AS INT8) AS i1, 
       CAST (1.3 AS INT16) AS i2, 
       CAST (13 AS INT32) AS i3, 
       CAST (1.3 AS INT64) AS i4, 
       CAST (1 AS UINT8) AS ui1, 
       CAST (1.3 AS UINT16) AS ui2, 
       CAST (13 AS UINT32) AS ui3, 
       CAST (1.3 AS UINT64) AS ui4, 
       CAST (13 AS FLOAT32) AS f1, 
       CAST (13 AS FLOAT64) AS f2, 
       CAST (13 AS DECIMAL) AS d1
'''

The preceding example converts the specified data type to a numeric value.

Return:

+----+----+----+----+-----+-----+-----+-----+------+------+----+
| i1 | i2 | i3 | i4 | ui1 | ui2 | ui3 | ui4 | f1   | f2   | d1 |
+----+----+----+----+-----+-----+-----+-----+------+------+----+
| 1  | 1  | 13 | 1  | 1   | 1   | 13  | 1   | 13.0 | 13.0 | 13 |
+----+----+----+----+-----+-----+-----+-----+------+------+----+

Cast list elements to a specified data type

RETURN CAST ([1.4, 1.5] AS LIST<INT8>) AS a

The preceding example converts the decimals in the list to integers.

Return:

+-------+
| a     |
+-------+
| [1,2] |
+-------+

Cast record fields to a specified data type

RETURN CAST ({p: LIST [1.4, 1.5]} AS RECORD {p LIST<INT32>}) AS a

The preceding example converts the decimals in the list field of the record to integers.

Return:

+-----------+
| a         |
+-----------+
| {p:[1,2]} |
+-----------+

Cast the generic spatial type to a string type

'''
RETURN CAST(ST_GeogFromText('POINT(0 0)') AS STRING) AS a, 
       CAST(ST_GeogFromText('LINESTRING(1 2, 2 4, 4 8, 8 16)') AS STRING) AS b, 
       CAST(ST_GeogFromText('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))') AS STRING) AS c
'''

The preceding example converts the generic spatial type GEOGRAPHY(ANY) to a string.

Return:

+------------+---------------------------------+----------------------------------------+
| a          | b                               | c                                      |
+------------+---------------------------------+----------------------------------------+
| POINT(0 0) | LINESTRING(1 2, 2 4, 4 8, 8 16) | POLYGON((0 0, 0 10, 10 10, 10 0, 0 0)) |
+------------+---------------------------------+----------------------------------------+

Cast a string type to a spatial type

'''
RETURN CAST('POINT(0 1)' as GEOGRAPHY(POINT)) AS a, 
       CAST('LINESTRING(1 2, 2 4, 4 8, 8 16)' as GEOGRAPHY(LINESTRING)) AS b, 
       CAST('POLYGON((0 0, 0 10, 10 10, 10 0, 0 0))' as GEOGRAPHY(POLYGON)) AS c, 
       CAST('POINT(0 1)' as GEOGRAPHY(ANY)) AS d
'''

The preceding example converts a string type to a spatial type.

Return:

+----------------+-------------------------------------------------+------------------------------------------------------------+----------------+
| a              | b                                               | c                                                          | d              |
+----------------+-------------------------------------------------+------------------------------------------------------------+----------------+
| POINT(0.0 1.0) | LINESTRING(1.0 2.0, 2.0 4.0, 4.0 8.0, 8.0 16.0) | POLYGON((0.0 0.0, 0.0 10.0, 10.0 10.0, 10.0 0.0, 0.0 0.0)) | POINT(0.0 1.0) |
+----------------+-------------------------------------------------+------------------------------------------------------------+----------------+

Cast the generic spatial type to a specified spatial type

'''
RETURN CAST(ST_GeogFromText('POINT(37.7749 -12.4194)') AS GEOGRAPHY(POINT)) AS a, 
       CAST(ST_GeogFromText('LINESTRING(30 10, 10 30, 40 40)') AS GEOGRAPHY(LINESTRING)) AS b, 
       CAST(ST_GeogFromText('POLYGON((30 10, 40 40, 20 40, 10 20, 30 10))') AS GEOGRAPHY(POLYGON)) AS c
'''

The preceding example converts the generic spatial type GEOGRAPHY(ANY) to a specified spatial type.

Return:

+-------------------------+---------------------------------------------+------------------------------------------------------------------+
| a                       | b                                           | c                                                                |
+-------------------------+---------------------------------------------+------------------------------------------------------------------+
| POINT(37.7749 -12.4194) | LINESTRING(30.0 10.0, 10.0 30.0, 40.0 40.0) | POLYGON((30.0 10.0, 40.0 40.0, 20.0 40.0, 10.0 20.0, 30.0 10.0)) |
+-------------------------+---------------------------------------------+------------------------------------------------------------------+

Cast a specific spatial type to the generic spatial type

RETURN CAST(ST_Point(37.7749, -12.4194) AS GEOGRAPHY(ANY)) AS a

The preceding example converts the GEOGRAPHY(POINT) type to the generic spatial type GEOGRAPHY(ANY).

Return:

+-------------------------+
| a                       |
+-------------------------+
| POINT(37.7749 -12.4194) |
+-------------------------+

Cast special values to FLOAT (FLOAT32) / DOUBLE (FLOAT64) / DECIMAL types 

'''
RETURN CAST('Inf' AS FLOAT) AS f32_inf,
       CAST('-Infinity' AS FLOAT32) AS f32_ninfinity,
       CAST('nan' AS FLOAT64) AS f64_nan,
       CAST('  NaN  ' AS DOUBLE) AS space_nan,
       CAST('+Infinity' AS DECIMAL(128, 10)) AS inf_with_scale
'''

Return:

+---------+---------------+---------+-----------+----------------+
| f32_inf | f32_ninfinity | f64_nan | space_nan | inf_with_scale |
+---------+---------------+---------+-----------+----------------+
| +Inf    | -Inf          | NaN     | NaN       | Infinity       |
+---------+---------------+---------+-----------+----------------+