Literals​

EdgeQL is inextricably tied to EdgeDB’s rigorous type system. Below is an overview of how to declare a literal value of each primitive type. Click a link in the left column to jump to the associated section.

Strings​

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

select 'i ❤️ edgedb';

{'i ❤️ edgedb'}

select "hello there!";

{'hello there!'}

select 'hello\nthere!';

{'hello
there!'}

select 'hello
there!';

{'hello
there!'}

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.

select r'hello\nthere'; # raw string

{r'hello\\nthere'}

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

{'one
two
three'}

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.

select 'hellothere'[5:10];

{'there'}

select 'hello' ++ 'there';

{'hellothere'}

select len('hellothere');

{10}

select str_trim('  hello there  ');

{'hello there'}

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.

select true;

{true}

select false;

{false}

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

Numbers​

There are several numerical types in EdgeDB’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.

select 5 > 2;

{true}

select 2 + 2;

{4}

select 2 ^ 10;

{1024}

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.

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

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

Generate a random UUID.

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:

select Color.Red;

{Red}

select <Color>"Red";

{Red}

Dates and times​

EdgeDB’s typesystem contains several temporal types.

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

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

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

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

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

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

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

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

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

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​

EdgeDB’s typesystem contains two duration types.

The duration type represents exact durations that can be represented by some fixed number of microseconds. It can be negative and it supports units of microseconds, milliseconds, seconds, minutes, and hours.

select <duration>'45.6 seconds';

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

select <duration>'-15 microseconds';

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

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

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

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

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

All temporal units beyond hour no longer correspond to a fixed duration of time; the length of a day/month/year/etc. changes based on daylight savings time, the month in question, leap years, etc.

By contrast, the cal::relative_duration type represents a “calendar” duration, like 1 month. Because months have different number of days, 1 month doesn’t correspond to a fixed number of milliseconds, but it’s often a useful quantity to represent recurring events, postponements, etc.

The cal::relative_duration type supports the same units as duration, plus days, weeks, months, years, decades, centuries, and millennia.

To declare relative duration literals:

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

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

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

{<cal::relative_duration>'P2M21DT45M'}

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

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

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

Bytes​

The bytes type represents raw binary data.

select b'bina\\x01ry';

{b'bina\\x01ry'}

Arrays​

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

select [1, 2, 3];

{[1, 2, 3]}

select ['hello', 'world'];

{['hello', 'world']}

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, tuples, and object types.

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.

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

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

Indexing tuples​

Tuple elements can be accessed with dot notation. Under the hood, there’s no difference between named and unnamed tuples. Named tuples support key-based and numerical indexing.

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

{1}

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

{'red'}

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

{('george')}

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

{('george')}

When you query an unnamed tuple using one of EdgeQL’s client libraries, its value is converted to a list/array. When you fetch a named tuple, it is converted to an object/dictionary/hashmap.

For a full reference on tuples, see Standard Library > Tuple.

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.

select <json>5;

{'5'}

select <json>"a string";

{'"a string"'}

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

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

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

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

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

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

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

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

JSON values support indexing operators. The resulting value is a json.

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

{2}

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 details documentation.