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

Literals

Literals are fixed values used directly in GQL queries. These values can be numbers, strings, dates, booleans, etc., and are written directly in the query rather than referencing columns in a table. The type of a literal is determined by its form when declared. For example, double quotes (") are used to identify string literals, while numeric literals do not require quotes; DATETIME is used to identify temporal literals.

The following reference lists the literals supported in GQL.

Numeric literals

Numeric literals are integers, floating-point numbers, or arbitrary-precision numbers. For more information, see Data types.

Integer literals

When a numeric literal is an integer:

  • Its default data type is INT32, with a range from -2147483648 to 2147483647.
  • If the integer value exceeds the range of INT32, GQL automatically converts it to INT64, with a range from -9223372036854775808 to 9223372036854775807.
  • If the integer value exceeds the range of INT64, GQL automatically converts it to DECIMAL. For more information, see Arbitrary-precision literals.

For example:

(root@nebula)> RETURN 2147483647   // 2147483647 is the maximum value for INT32.
+------------+
| 2147483647 |
+------------+
| 2147483647 |
+------------+

(root@nebula)> RETURN 2147483648  // 2147483648 exceeds the maximum value for INT32 and is automatically converted to INT64.
+------------+
| 2147483648 |
+------------+
| 2147483648 |
+------------+

(root@nebula)> RETURN 9223372036854775808  // 9223372036854775808 exceeds the maximum value for INT64 and is automatically converted to DECIMAL.
+---------------------+
| 9223372036854775808 |
+---------------------+
| 9223372036854775808 |
+---------------------+

However, in expressions, if the numeric value exceeds the maximum value of its data type, GQL reports an error. For example:

(root@nebula)> RETURN 2147483647+1
Error: [22003]: Numeric value out of range: `2147483647 + 1`, type: `INT32`

To solve this, explicitly cast the INT32 value to INT64, for example:

(root@nebula)> RETURN CAST(2147483647 AS INT64) + 1
+-------------------------------+
| CAST(2147483647 AS INT64) + 1 |
+-------------------------------+
| 2147483648                    |
+-------------------------------+

Or:

(root@nebula)> RETURN 2147483647 + CAST(1 AS INT64)
+-------------------------------+
| 2147483647 + CAST(1 AS INT64) |
+-------------------------------+
| 2147483648                    |
+-------------------------------+

Floating-point literals

To explicitly specify the data type of the floating-point literals, use the suffix F or f for data type FLOAT and D or d for data type DOUBLE. For example:

(root@nebula)> RETURN cast(666.66 AS FLOAT) = 666.66F
+---------------------------------+
| cast(666.66 AS FLOAT) = 666.66F |
+---------------------------------+
| true                            |
+---------------------------------+

(root@nebula)> RETURN cast(666.66 AS DOUBLE) = 666.66d
+----------------------------------+
| cast(666.66 AS DOUBLE) = 666.66d |
+----------------------------------+
| true                             |
+----------------------------------+

Arbitrary-precision literals

The data type of arbitrary-precision literals is DECIMAL, with a precision range of 1 ~ 256 and a scale range of 0 ~ 128. To explicitly specify arbitrary-precision literals, use the suffix M or m. For example:

(root@nebula)> RETURN 9223372036854775807M+1
+------------------------+
| 9223372036854775807M+1 |
+------------------------+
| 9223372036854775808    |
+------------------------+

In GQL, if no suffix is specified for a number with decimal places, the data type defaults to DECIMAL and can be converted implicitly or explicitly to FLOAT or DOUBLE. For more information, see Conversions between predefined data types.

(root@nebula)> RETURN cast(666.66 AS FLOAT) = 666.66
+--------------------------------+
| cast(666.66 AS FLOAT) = 666.66 |
+--------------------------------+
| true                           |
+--------------------------------+

(root@nebula)> RETURN cast(666.66 AS DOUBLE) = 666.66
+---------------------------------+
| cast(666.66 AS DOUBLE) = 666.66 |
+---------------------------------+
| true                            |
+---------------------------------+

String literals

String literals are combinations of zero or more characters enclosed in double quotes (") or single quotes ('). Strings must use matching types of quotes, either paired single quotes or paired double quotes.

In runtime contexts such as expression evaluation, string values are limited to 2³²−1 bytes. For more information, see String types.

Single-quoted string literals

RETURN 'Hello, World!'
RETURN '12345'
RETURN 'A single quoted string'

Double-quoted string literals

RETURN "Hello, World!"
RETURN "12345"
RETURN "A double quoted string"

Nested quotes

You can use double quotes within single-quoted strings or single quotes within double-quoted strings without escapes, for example:

RETURN 'He said: "Hello, World!"'
RETURN "It's a beautiful day!"

String concatenation

You can concatenate multiple string literals using the || operator, for example:

(root@nebula)> RETURN 'Hello, ' || 'World!' as _str
+---------------+
| _str          |
+---------------+
| Hello, World! |
+---------------+

Character escaping

Certain characters in string literals need to be escaped using a backslash (\) to avoid syntax conflicts. These characters include single quotes ('), backslashes (\), and other special characters.

Here are some common escape sequences:

Escape sequence Description
\\ Backslash
\' Single quote (Escaping required only within single-quoted strings)
\" Double quote (Escaping required only within double-quoted strings)
\t Tab
\b Backspace
\n Newline
\r Carriage return
\f Form feed
\uXXXX Unicode character, where \u is followed by exactly four hexadecimal digits.
\UXXXXXXXX Unicode character, where \U is followed by exactly eight hexadecimal digits.

Examples:

(root@nebula)> RETURN "'\n\"\n\\"
+-------------+
| "'\n\"\n\\" |
+-------------+
| '\n\"\n\    |
+-------------+
(root@nebula)> RETURN "a\tb\tc\n1\t2\t3"
+--------------------+
| "a\tb\tc\n1\t2\t3" |
+--------------------+
| a\tb\tc\n1\t2\t3   |
+--------------------+

Boolean literals

Boolean literals have three values:

  • TRUE: Represents true.
  • FALSE: Represents false.
  • UNKNOWN: Represents unknown.

NULL literal

The NULL literal represents the absence of a value. It is different from an empty string, the number 0, or an empty container. The inferred type of the NULL literal is NULL. When the literal is used in a context with a specific type, the system handles the null value according to that context.

RETURN NULL, typeof(NULL)

For the distinction among the null value, the NULL type, and nullability, see NULL type.

Temporal literals

Temporal instant literals

Temporal instant literals are combinations of date and time enclosed in single quotes (') or double quotes ("), declared with keywords like DATETIME or DATE. The declaration of temporal instant literals is as follows:

Type Declaration keyword Default format
Date DATE YYYY-MM-DD
Time TIME HH:MM:SS[.SSSSSS][-1200 ~ +1400]
DateTime DATETIME YYYY-MM-DDTHH:MM:SS[.SSSSSS][-1200 ~ +1400]
  • If the literal does not include microseconds (.SSSSSS), GQL defaults it to 000000. If it includes microseconds but is less than 6 digits, GQL pads it with zeros.
  • If the literal does not include timezone information (-1200 ~ +1400), GQL defaults to the current session's timezone. If it includes timezone information, the result is converted to the current session's time by adding the timezone offset of the current session to the UTC time.

Example:

(root@nebula)>  '''
                RETURN DATE '2022-12-31' AS _date, 
                               TIME '12:34:56' AS _time, 
                               TIME '12:34:56+0900' AS _zoned_time , 
                               DATETIME '2022-12-31T12:34:56' AS _datetime, 
                               DATETIME '2022-12-31T12:34:56.123+0900' AS _zoned_datetime
                '''
+------------+-----------------+------------------+----------------------------+-----------------------------+
| _date      | _time           | _zoned_time      | _datetime                  | _zoned_datetime             |
+------------+-----------------+------------------+----------------------------+-----------------------------+
| 2022-12-31 | 12:34:56.000000 | 03:34:56.000000Z | 2022-12-31T12:34:56.000000 | 2022-12-31T03:34:56.123000Z |
+------------+-----------------+------------------+----------------------------+-----------------------------+

Temporal duration literals

Temporal duration literals are combinations of durations enclosed in single quotes (') or double quotes (") and declared with the keyword DURATION.

DURATION literals can be represented in the following two formats:

  • P[nY][nM] format: Represents the duration of years and months. For example, P1Y2M represents the duration of 1 year and 2 months.
    • P: Prefix indicating the duration.
    • nY: Represents n years.
    • nM: Represents n months.
  • P[nD]T[nH][nM][nS] format: Represents the duration of days, hours, minutes, and seconds. For example, P3DT4H30M5S represents an duration of 3 days, 4 hours, 30 minutes, and 5 seconds.
    • P: Prefix indicating the duration.
    • nD: Represents n days.
    • T: Prefix indicating the time part (if there are hours, minutes, or seconds).
    • nH: Represents n hours.
    • nM: Represents n minutes.
    • nS: Represents n seconds and can include fractional parts.

Example:

(root@nebula)>  '''
                RETURN DURATION 'P1Y' AS _year, 
                               DURATION 'P2M' AS _month, 
                               DURATION 'P1Y2M' AS _duration1, 
                               DURATION 'P3D' AS _day, 
                               DURATION 'PT4H30M5S' AS _duration2, 
                               DURATION 'P3DT4H30M5S' AS _duration3, 
                               DURATION 'P3DT4H30M5.123S' AS _duration4
                '''
+-------+--------+------------+------+------------+-------------+-----------------+
| _year | _month | _duration1 | _day | _duration2 | _duration3  | _duration4      |
+-------+--------+------------+------+------------+-------------+-----------------+
| P1Y   | P2M    | P1Y2M      | P3D  | PT4H30M5S  | P3DT4H30M5S | P3DT4H30M5.123S |
+-------+--------+------------+------+------------+-------------+-----------------+

Operations on temporal instant and duration literals

You can perform addition and subtraction operations between temporal instant literals and duration literals, for example:

(root@nebula)> RETURN DATETIME '2022-12-31T12:34:56' + DURATION 'P1Y2M' AS _datetime
+----------------------------+
| _datetime                  |
+----------------------------+
| 2024-02-29T12:34:56.000000 |
+----------------------------+

For more information on operations between temporal instant and duration literals, see Operators or functions for temporal type values.

Vector literals

The declaration of vector literals is as follows:

VECTOR<dimension, coordinate_type>([coordinate1, coordinate2, ...])

or

VECTOR(coordinate1, coordinate2, ...)
  • dimension: The number of dimensions in the vector literal, which must be in the range of 1 to 2,147,483,647. If not specified, the number of dimensions is automatically inferred from the number of coordinates in the vector literal.
  • coordinate_type: The data type of the coordinates in the vector literal, which must be FLOAT. If not specified, the data type defaults to FLOAT.
  • coordinate1, coordinate2, ...: The values of coordinates in the vector literal. The number of coordinates must equal the number of dimensions specified by dimension. The value of each coordinate cannot be NULL.

Example:

(root@nebula)> RETURN VECTOR<3, FLOAT>([1.0, 2.0, 3.0]) AS v1, VECTOR(1, 2, 3) AS v2

Operations between vector literals

You can perform addition and subtraction operations between vector literals, for example:

(root@nebula)> LET x = VECTOR<3, FLOAT>([10.1, 20.2, 30.3]), y = VECTOR<3, FLOAT>([2.2, 3.3, 4.4]), z = VECTOR<3, FLOAT>([1.2, 2.3, 3.3]) RETURN x + y -z AS w
+-----------------------+
| w                     |
+-----------------------+
| [11.1,21.2,31.400002] |
+-----------------------+

For more information on operation rules between vector literals, see Supported arithmetic operations.

List literals

List literals are combinations of zero or more values enclosed in square brackets ([]). The square brackets can be optionally preceded by a type declaration. The declaration of list literals is as follows:

type? [value1, value2, ...]
  • type: The keyword to declare the list, which can be LIST or ARRAY.
  • The values in the list literal can be any type of literal or the result of an expression, but all values in the list must be of the same type.

Example:

(root@nebula)>  '''
                RETURN [1+2, 2+3, 3+4] AS _list, 
                      LIST [true, false, unknown] AS _list1, 
                      ARRAY ['a', 'b', 'c'] AS _list2, 
                      [ RECORD {a :123, b: true }, RECORD {a:456, b: false} ] AS _list3, 
                      [ VECTOR<3, FLOAT>([1.0, 2.0, 3.0]), VECTOR<3, FLOAT>([4.0, 5.0, 6.0]) ] AS _list4 
                '''
+---------+-------------------+---------+----------------------------------+-------------------------------+
| _list   | _list1            | _list2  | _list3                           | _list4                        |
+---------+-------------------+---------+----------------------------------+-------------------------------+
| [3,5,7] | [true,false,null] | [a,b,c] | [{a:123,b:true},{a:456,b:false}] | [[1.0,2.0,3.0],[4.0,5.0,6.0]] |
+---------+-------------------+---------+----------------------------------+-------------------------------+

To concatenate multiple list literals, use the operator || . The types of the list literals must be the same, for example:

(root@nebula)> RETURN [1, 2, 3] || [4, 5, 6] AS _list
+---------------+
| _list         |
+---------------+
| [1,2,3,4,5,6] |
+---------------+

For more information on list literals, see List type.

Set literals

The declaration of set literals is as follows:

SET {value, value, ...}
  • The values in a set literal can be any literal or the result of an expression, but all values in the set must be of the same type.
  • Elements in a set are unordered and unique. If duplicate values are provided when a set is constructed, they are automatically deduplicated.

Example:

(root@nebula)> ''' 
               RETURN SET {} AS _set, 
                      SET {true, false, unknown} AS _set1, 
                      SET {"a", "b", "c"} AS _set2,
                      SET {RECORD {a :123, b: true }, RECORD {a:456, b: false} } AS _set3,
                      SET {VECTOR<3, FLOAT>([1.0, 2.0, 3.0]), VECTOR<3, FLOAT>([4.0, 5.0, 6.0]) } AS _set4
               '''
+------+-------------------+---------+------------------------------------+-------------------------------+
| _set | _set1             | _set2   | _set3                              | _set4                         |
+------+-------------------+---------+------------------------------------+-------------------------------+
| {}   | {null,false,true} | {c,b,a} | { {a:456,b:false},{a:123,b:true} } | {[4.0,5.0,6.0],[1.0,2.0,3.0]} |
+------+-------------------+---------+------------------------------------+-------------------------------+

Operations between set literals

Set literals support union, for example:

(root@nebula)> RETURN set{}||set{} AS a, set{}||set{1,2,3} AS b, set{1,2,3}||set{} AS c
+----+---------+---------+
| a  | b       | c       |
+----+---------+---------+
| {} | {1,2,3} | {1,2,3} |
+----+---------+---------+

For more information, see Supported operators.

Map literals

The declaration of map literals is as follows:

MAP {key1: value1, key2: value2, ...}
  • The keys in a map literal can be any literal or the result of an expression that does not depend on variables. All keys in a map must be unique and of the same type. If duplicate keys are provided when a map literal is constructed, the first key and its corresponding value are retained.
  • The values in a map literal can be any literal or the result of an expression that does not depend on variables. All values in a map must be of the same type.

Example:

(root@nebula)>  '''
                RETURN MAP { 'a': 1, 'b': 2, 'c': 3 } AS _map, 
                       MAP { 1: DATE '2022-12-31', 2: DATETIME '2022-12-31T12:34:56' } AS _map1,
                       MAP { true: DURATION 'P1Y2M', false: DURATION 'P3DT4H' } AS _map2,
                       MAP { [1,2]: VECTOR<3, FLOAT>([1.0, 2.0, 3.0]), [4,5]: VECTOR<3, FLOAT>([4.0, 5.0, 6.0]) } AS _map3,
                       MAP { SET{1,2}: RECORD {x: 'set', y: 'type'}, SET{3,4}: RECORD {x: 'set', y: 'literal'} } AS _map4, 
                       MAP { MAP{'a':1}: 'map type', MAP{'b':2}: 'map literal' } AS _map5
                '''
+---------------+-------------------------------------------------------------+---------------------------+-----------------------------------------------+----------------------------------------------------+-----------------------------------------+
| _map          | _map1                                                       | _map2                     | _map3                                         | _map4                                              | _map5                                   |
+---------------+-------------------------------------------------------------+---------------------------+-----------------------------------------------+----------------------------------------------------+-----------------------------------------+
| {a:1,b:2,c:3} | {1:2022-12-31T00:00:00.000000,2:2022-12-31T12:34:56.000000} | {false:P3DT4H,true:P1Y2M} | {"[1,2]":[1.0,2.0,3.0],"[4,5]":[4.0,5.0,6.0]} | {"{2,1}":{x:set,y:type},"{4,3}":{x:set,y:literal}} | { {a:1}:"map type",{b:2}:"map literal"} |
+---------------+-------------------------------------------------------------+---------------------------+-----------------------------------------------+----------------------------------------------------+-----------------------------------------+

Operations between map literals

Map literals support union, for example:

(root@nebula)> RETURN MAP{'a': 1, 'b': 2} || MAP{'b': 3, 'c': 4} || MAP { } AS _map
+---------------+
| _map          |
+---------------+
| {a:1,b:2,c:4} |
+---------------+

For more information, see Supported operators.

Record literals

Record literals are combinations of zero or more key-value pairs enclosed in curly braces ({}) and declared with the keyword RECORD. The key-value pairs in record literals are separated by colons (:), and the pairs are separated by commas (,). For example:

(root@nebula)>  '''
                RETURN RECORD { _int:2023,
                               _boolean:false,
                               _string:"string",
                               _list: list[1,2,3],
                               _record:{_int:123},
                               _vector: VECTOR<3, FLOAT>([1.0, 2.0, 3.0]),
                               _instant: DATETIME '2023-01-01T00:00:00',
                               _duration: DURATION 'P1Y2M'
                               } AS _record 
                '''
+------------------------------------------------------------------------------------------------------------------------------------------------------+
| _record                                                                                                                                              |
+------------------------------------------------------------------------------------------------------------------------------------------------------+
| {_boolean:false,_duration:P1Y2M,_instant:2023-01-01T00:00:00.000000,_int:2023,_list:[1,2,3],_record:{_int:123},_string:string,_vector:[1.0,2.0,3.0]} |
+------------------------------------------------------------------------------------------------------------------------------------------------------+

More information