Literals​

.md

Copy page

Strings​

The str type is a variable-length string of Unicode characters. A string can be declared with either single or double quotes.

db> 

select 'I ❤️ EdgeQL';

{'I ❤️ EdgeQL'}

db> 

select "hello there!";

{'hello there!'}

db> 

select 'hello\nthere!';

{'hello
there!'}

db> 
... 

select 'hello
there!';

{'hello
there!'}

db> 
... 

select r'hello
there!'; # multiline

{'hello
there!'}

There is a special syntax for declaring "raw strings". Raw strings treat the backslash \ as a literal character instead of an escape character.

db> 

select r'hello\nthere'; # raw string

{r'hello\\nthere'}

db> 
... 
... 

select $$one
two
three$$; # multiline raw string

{'one
two
three'}

db> 
... 

select $label$You can add an interstitial label
if you need to use "$$" in your string.$label$;

{
  'You can add an interstital label
  if you need to use "$$" in your string.',
}

EdgeQL contains a set of built-in functions and operators for searching, comparing, and manipulating strings.

db> 

select 'hellothere'[5:10];

{'there'}

db> 

select 'hello' ++ 'there';

{'hellothere'}

db> 

select len('hellothere');

{10}

db> 

select str_trim('  hello there  ');

{'hello there'}

db> 

select str_split('hello there', ' ');

{['hello', 'there']}

For a complete reference on strings, see Standard Library > String or click an item below.

Booleans​

The bool type represents a true/false value.

db> 

select true;

{true}

db> 

select false;

{false}

Gel provides a set of operators that operate on boolean values.

Numbers​

There are several numerical types in Gel's type system.

Number literals that do not contain a decimal are interpreted as int64. Numbers containing decimals are interpreted as float64. The n suffix designates a number with arbitrary precision: either bigint or decimal.

To declare an int16, int32, or float32, you must provide an explicit type cast. For details on type casting, see Casting.

EdgeQL includes a full set of arithmetic and comparison operators. Parentheses can be used to indicate the order-of-operations or visually group subexpressions; this is true across all EdgeQL queries.

db> 

select 5 > 2;

{true}

db> 

select 2 + 2;

{4}

db> 

select 2 ^ 10;

{1024}

db> 

select (1 + 1) * 2 / (3 + 8);

{0.36363636363636365}

EdgeQL provides a comprehensive set of built-in functions and operators on numerical data.

UUID​

The uuid type is commonly used to represent object identifiers. UUID literal must be explicitly cast from a string value matching the UUID specification.

db> 

select <uuid>'a5ea6360-75bd-4c20-b69c-8f317b0d2857';

{a5ea6360-75bd-4c20-b69c-8f317b0d2857}

Generate a random UUID.

db> 

select uuid_generate_v1mc();

{b4d94e6c-3845-11ec-b0f4-93e867a589e7}

Enums​

Enum types must be declared in your schema.

scalar type Color extending enum<Red, Green, Blue>;

Once declared, an enum literal can be declared with dot notation, or by casting an appropriate string literal:

db> 

select Color.Red;

{Red}

db> 

select <Color>"Red";

{Red}

Dates and times​

Gel's typesystem contains several temporal types.

All temporal literals are declared by casting an appropriately formatted string.

db> 

select <datetime>'1999-03-31T15:17:00Z';

{<datetime>'1999-03-31T15:17:00Z'}

db> 

select <datetime>'1999-03-31T17:17:00+02';

{<datetime>'1999-03-31T15:17:00Z'}

db> 

select <cal::local_datetime>'1999-03-31T15:17:00';

{<cal::local_datetime>'1999-03-31T15:17:00'}

db> 

select <cal::local_date>'1999-03-31';

{<cal::local_date>'1999-03-31'}

db> 

select <cal::local_time>'15:17:00';

{<cal::local_time>'15:17:00'}

EdgeQL supports a set of functions and operators on datetime types.

Durations​

Gel's type system contains three duration types.

db> 

select <duration>'45.6 seconds';

{<duration>'0:00:45.6'}

db> 

select <duration>'-15 microseconds';

{<duration>'-0:00:00.000015'}

db> 

select <duration>'5 hours 4 minutes 3 seconds';

{<duration>'5:04:03'}

db> 

select <duration>'8760 hours'; # about a year

{<duration>'8760:00:00'}

db> 

select <cal::relative_duration>'15 milliseconds';

{<cal::relative_duration>'PT.015S'}

db> 

select <cal::relative_duration>'2 months 3 weeks 45 minutes';

{<cal::relative_duration>'P2M21DT45M'}

db> 

select <cal::relative_duration>'-7 millennia';

{<cal::relative_duration>'P-7000Y'}

db> 

select <cal::date_duration>'5 days';

{<cal::date_duration>'P5D'}

db> 

select <cal::local_date>'2022-06-25' + <cal::date_duration>'5 days';

{<cal::local_date>'2022-06-30'}

db> 

select <cal::local_date>'2022-06-30' - <cal::local_date>'2022-06-25';

{<cal::date_duration>'P5D'}

Ranges​

Ranges represent a range of orderable scalar values. A range comprises a lower bound, upper bound, and two boolean flags indicating whether each bound is inclusive.

Create a range literal with the range constructor function.

db> 

select range(1, 10);

{range(1, 10, inc_lower := true, inc_upper := false)}

db> 

select range(2.2, 3.3);

{range(2.2, 3.3, inc_lower := true, inc_upper := false)}

Ranges can be empty, when the upper and lower bounds are equal.

db> 

select range(1, 1);

{range({}, empty := true)}

Ranges can be unbounded. An empty set is used to indicate the lack of a particular upper or lower bound.

db> 

select range(4, <int64>{});

{range(4, {})}

db> 

select range(<int64>{}, 4);

{range({}, 4)}

db> 

select range(<int64>{}, <int64>{});

{range({}, {})}

To compute the set of concrete values defined by a range literal, use range_unpack. An empty range will unpack to the empty set. Unbounded ranges cannot be unpacked.

db> 

select range_unpack(range(0, 10));

{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}

db> 

select range_unpack(range(1, 1));

{}

db> 

select range_unpack(range(0, <int64>{}));

gel error: InvalidValueError: cannot unpack an unbounded range

Bytes​

The bytes type represents raw binary data.

db> 

select b'bina\\x01ry';

{b'bina\\x01ry'}

There is a special syntax for declaring "raw byte strings". Raw byte strings treat the backslash \ as a literal character instead of an escape character.

db> 

select rb'hello\nthere';

{b'hello\\nthere'}

db> 

select br'\';

{b'\\'}

Arrays​

An array is an ordered collection of values of the same type. For example:

db> 

select [1, 2, 3];

{[1, 2, 3]}

db> 

select ['hello', 'world'];

{['hello', 'world']}

db> 

select [(1, 2), (100, 200)];

{[(1, 2), (100, 200)]}

EdgeQL provides a set of functions and operators on arrays.

See Standard Library > Array for a complete reference on array data types.

Tuples​

A tuple is fixed-length, ordered collection of values, each of which may have a different type. The elements of a tuple can be of any type, including scalars, arrays, other tuples, and object types.

db> 

select ('Apple', 7, true);

{('Apple', 7, true)}

Optionally, you can assign a key to each element of a tuple. These are known as named tuples. You must assign keys to all or none of the elements; you can't mix-and-match.

db> 

select (fruit := 'Apple', quantity := 3.14, fresh := true);

{(fruit := 'Apple', quantity := 3.14, fresh := true)}

db> 

select (1, 3.14, 'red').0;

{1}

db> 

select (1, 3.14, 'red').2;

{'red'}

db> 

select (name := 'george', age := 12).name;

{('george')}

db> 

select (name := 'george', age := 12).0;

{('george')}

JSON​

The json scalar type is a stringified representation of structured data. JSON literals are declared by explicitly casting other values or passing a properly formatted JSON string into to_json(). Any type can be converted into JSON except bytes.

db> 

select <json>5;

{'5'}

db> 

select <json>"a string";

{'"a string"'}

db> 

select <json>["this", "is", "an", "array"];

{'["this", "is", "an", "array"]'}

db> 

select <json>("unnamed tuple", 2);

{'["unnamed tuple", 2]'}

db> 

select <json>(name := "named tuple", count := 2);

{'{
  "name": "named tuple",
  "count": 2
}'}

db> 

select to_json('{"a": 2, "b": 5}');

{'{"a": 2, "b": 5}'}

JSON values support indexing operators. The resulting value is also of type json.

db> 

select to_json('{"a": 2, "b": 5}')['a'];

{2}

db> 

select to_json('["a", "b", "c"]')[2];

{'"c"'}

EdgeQL supports a set of functions and operators on json values. Refer to the Standard Library > JSON or click an item below for detailed documentation.