Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/literals/ Documentation version: v5.3.2 # 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/numeric-type/). ### 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/literals/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/expressions/cast/). ```` (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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/c-string-type/#length_limits). ### 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/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 | +------------+-----------------+------------------+----------------------------+-----------------------------+ ```` - To view the default date and time format in the current session, see [SHOW CURRENT_SESSION TIME FORMATS](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-current-session-time-formats/). - To view the timezone information in the current session, see [SHOW CURRENT_SESSION](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/show-current-session/). - To modify the date and time format in the current session, see [SESSION SET](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/sessions/set/). ### 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/#operators_or_functions_for_temporal_type_values). ## Vector literals The declaration of vector literals is as follows: ```` VECTOR([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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/vector-type/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/set-type/#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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/map-type/#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 - For rules on converting between different types of literals, see [Data type conversions](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/expressions/cast/). - For rules on comparing different types of literals, see [Comparison predicates](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/predicates/comparison/).