# Literals EdgeQL is *inextricably tied* to Gel'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. | | | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | [String](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-strings) | `str` | | [Boolean](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-boolean) | `bool` | | [Numbers](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-numbers) | `int16` `int32` `int64` `float32` `float64` `bigint` `decimal` | | [UUID](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-uuid) | `uuid` | | [Enums](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-enum) | `enum` | | [Dates and times](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-dates) | `datetime` `duration` `cal::local_datetime` `cal::local_date` `cal::local_time` `cal::relative_duration` | | [Durations](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-durations) | `duration` `cal::relative_duration` `cal::date_duration` | | [Ranges](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-ranges) | `range` | | [Bytes](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-bytes) | `bytes` | | [Arrays](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-array) | `array` | | [Tuples](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-tuple) | `tuple` or `tuple` | | [JSON](https://docs.geldata.com/reference/edgeql/literals.md#ref-eql-literal-json) | `json` | ## Strings The [`str`](https://docs.geldata.com/reference/stdlib/string.md#type::std::str) type is a variable-length string of Unicode characters. A string can be declared with either single or double quotes. ```edgeql-repl 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. ```edgeql-repl 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. ```edgeql-repl 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](https://docs.geldata.com/reference/stdlib/string.md#ref-std-string) or click an item below. | | | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Indexing and slicing | [`str[i]`](https://docs.geldata.com/reference/stdlib/string.md#operator::stridx) [`str[from:to]`](https://docs.geldata.com/reference/stdlib/string.md#operator::strslice) | | Concatenation | [`str ++ str`](https://docs.geldata.com/reference/stdlib/string.md#operator::strplus) | | Utilities | [`len()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::len) | | Transformation functions | [`str_split()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_split) [`str_lower()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_lower) [`str_upper()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_upper) [`str_title()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_title) [`str_pad_start()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_pad_start) [`str_pad_end()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_pad_end) [`str_trim()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_trim) [`str_trim_start()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_trim_start) [`str_trim_end()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_trim_end) [`str_repeat()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::str_repeat) | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Search | [`contains()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::contains) [`find()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::find) | | Pattern matching and regexes | [`str like pattern`](https://docs.geldata.com/reference/stdlib/string.md#operator::like) [`str ilike pattern`](https://docs.geldata.com/reference/stdlib/string.md#operator::ilike) [`re_match()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::re_match) [`re_match_all()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::re_match_all) [`re_replace()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::re_replace) [`re_test()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::re_test) | ## Booleans The [`bool`](https://docs.geldata.com/reference/stdlib/bool.md#type::std::bool) type represents a true/false value. ```edgeql-repl db> select true; {true} db> select false; {false} ``` Gel provides a set of operators that operate on boolean values. | | | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Logical operators | [`or`](https://docs.geldata.com/reference/stdlib/bool.md#operator::or) [`and`](https://docs.geldata.com/reference/stdlib/bool.md#operator::and) [`not`](https://docs.geldata.com/reference/stdlib/bool.md#operator::not) | | Aggregation | [`all()`](https://docs.geldata.com/reference/stdlib/set.md#function::std::all) [`any()`](https://docs.geldata.com/reference/stdlib/set.md#function::std::any) | ## Numbers There are several numerical types in Gel's type system. | | | | ------------------------------------------------------------------------------------ | ---------------------------- | | [`int16`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int16) | 16-bit integer | | [`int32`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int32) | 32-bit integer | | [`int64`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int64) | 64-bit integer | | [`float32`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::float32) | 32-bit floating point number | | [`float64`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::float64) | 64-bit floating point number | | [`bigint`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::bigint) | Arbitrary precision integer. | | [`decimal`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::decimal) | Arbitrary precision number. | 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`. | Syntax | Inferred type | | ------------------ | ------------------------------------------------------------------------------------ | | `select 3;` | [`int64`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int64) | | `select 3.14;` | [`float64`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::float64) | | `select 314e-2;` | [`float64`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::float64) | | `select 42n;` | [`bigint`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::bigint) | | `select 42.0n;` | [`decimal`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::decimal) | | `select 42e+100n;` | [`decimal`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::decimal) | To declare an `int16`, `int32`, or `float32`, you must provide an explicit type cast. For details on type casting, see [Casting](https://docs.geldata.com/reference/edgeql/types.md#ref-eql-types). | Syntax | Type | | -------------------------- | ------------------------------------------------------------------------------------ | | `select 1234;` | [`int16`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int16) | | `select 123456;` | [`int32`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::int32) | | `select 123.456;` | [`float32`](https://docs.geldata.com/reference/stdlib/numbers.md#type::std::float32) | 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. ```edgeql-repl 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. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Arithmetic | [`+`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::plus) [`-`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::minus) [`-`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::uminus) [`*`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::mult) [`/`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::div) [`//`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::floordiv) [`%`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::mod) [`^`](https://docs.geldata.com/reference/stdlib/numbers.md#operator::pow) | | Statistics | [`sum()`](https://docs.geldata.com/reference/stdlib/set.md#function::std::sum) [`min()`](https://docs.geldata.com/reference/stdlib/set.md#function::std::min) [`max()`](https://docs.geldata.com/reference/stdlib/set.md#function::std::max) [`math::mean()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::mean) [`math::stddev()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::stddev) [`math::stddev_pop()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::stddev_pop) [`math::var()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::var) [`math::var_pop()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::var_pop) | | Math | [`round()`](https://docs.geldata.com/reference/stdlib/numbers.md#function::std::round) [`math::abs()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::abs) [`math::ceil()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::ceil) [`math::floor()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::floor) [`math::ln()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::ln) [`math::lg()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::lg) [`math::log()`](https://docs.geldata.com/reference/stdlib/math.md#function::math::log) | | Random number | [`random()`](https://docs.geldata.com/reference/stdlib/numbers.md#function::std::random) | ## UUID The [`uuid`](https://docs.geldata.com/reference/stdlib/uuid.md#type::std::uuid) type is commonly used to represent object identifiers. UUID literal must be explicitly cast from a string value matching the UUID specification. ```edgeql-repl db> select 'a5ea6360-75bd-4c20-b69c-8f317b0d2857'; {a5ea6360-75bd-4c20-b69c-8f317b0d2857} ``` Generate a random UUID. ```edgeql-repl db> select uuid_generate_v1mc(); {b4d94e6c-3845-11ec-b0f4-93e867a589e7} ``` ## Enums Enum types must be [declared in your schema](https://docs.geldata.com/reference/datamodel/primitives.md#ref-datamodel-enums). ```sdl scalar type Color extending enum; ``` Once declared, an enum literal can be declared with dot notation, or by casting an appropriate string literal: ```edgeql-repl db> select Color.Red; {Red} db> select "Red"; {Red} ``` ## Dates and times Gel's typesystem contains several temporal types. | | | | -------------------------------------------------------------------------------------------------------- | ---------------------------- | | [`datetime`](https://docs.geldata.com/reference/stdlib/datetime.md#type::std::datetime) | Timezone-aware point in time | | [`cal::local_datetime`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::local_datetime) | Date and time w/o timezone | | [`cal::local_date`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::local_date) | Date type | | [`cal::local_time`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::local_time) | Time type | All temporal literals are declared by casting an appropriately formatted string. ```edgeql-repl db> select '1999-03-31T15:17:00Z'; {'1999-03-31T15:17:00Z'} db> select '1999-03-31T17:17:00+02'; {'1999-03-31T15:17:00Z'} db> select '1999-03-31T15:17:00'; {'1999-03-31T15:17:00'} db> select '1999-03-31'; {'1999-03-31'} db> select '15:17:00'; {'15:17:00'} ``` EdgeQL supports a set of functions and operators on datetime types. | | | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Arithmetic | [`dt + dt`](https://docs.geldata.com/reference/stdlib/datetime.md#operator::dtplus) [`dt - dt`](https://docs.geldata.com/reference/stdlib/datetime.md#operator::dtminus) | | String parsing | [`to_datetime()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::to_datetime) [`cal::to_local_datetime()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::to_local_datetime) [`cal::to_local_date()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::to_local_date) [`cal::to_local_time()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::to_local_time) | | Component extraction | [`datetime_get()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::datetime_get) [`cal::time_get()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::time_get) [`cal::date_get()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::date_get) | | Truncation | [`datetime_truncate()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::datetime_truncate) | | System timestamps | [`datetime_current()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::datetime_current) [`datetime_of_transaction()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::datetime_of_transaction) [`datetime_of_statement()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::datetime_of_statement) | ## Durations Gel's type system contains three duration types. | | | | -------------------------------------------------------------------------------------------------------------- | -------------------------------- | | [`duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::std::duration) | Exact duration | | [`cal::relative_duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::relative_duration) | Duration in relative units | | [`cal::date_duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::date_duration) | Duration in months and days only | ### Exact durations The [`duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::std::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`. ```edgeql-repl db> select '45.6 seconds'; {'0:00:45.6'} db> select '-15 microseconds'; {'-0:00:00.000015'} db> select '5 hours 4 minutes 3 seconds'; {'5:04:03'} db> select '8760 hours'; # about a year {'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. ### Relative durations By contrast, the [`cal::relative_duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::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. > Note: 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: ```edgeql-repl db> select '15 milliseconds'; {'PT.015S'} db> select '2 months 3 weeks 45 minutes'; {'P2M21DT45M'} db> select '-7 millennia'; {'P-7000Y'} ``` ### Date durations The [`cal::date_duration`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::date_duration) represents spans consisting of some number of *months* and *days*. This type is primarily intended to simplify logic involving [`cal::local_date`](https://docs.geldata.com/reference/stdlib/datetime.md#type::cal::local_date) values. ```edgeql-repl db> select '5 days'; {'P5D'} db> select '2022-06-25' + '5 days'; {'2022-06-30'} db> select '2022-06-30' - '2022-06-25'; {'P5D'} ``` EdgeQL supports a set of functions and operators on duration types. | | | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Arithmetic | [`dt + dt`](https://docs.geldata.com/reference/stdlib/datetime.md#operator::dtplus) [`dt - dt`](https://docs.geldata.com/reference/stdlib/datetime.md#operator::dtminus) | | Duration string parsing | [`to_duration()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::to_duration) [`cal::to_relative_duration()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::to_relative_duration) [`cal::to_date_duration()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::to_date_duration) | | Component extraction | [`duration_get()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::duration_get) | | Conversion | [`duration_truncate()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::std::duration_truncate) [`cal::duration_normalize_hours()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::duration_normalize_hours) [`cal::duration_normalize_days()`](https://docs.geldata.com/reference/stdlib/datetime.md#function::cal::duration_normalize_days) | ## 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. ```edgeql-repl 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. ```edgeql-repl 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. ```edgeql-repl db> select range(4, {}); {range(4, {})} db> select range({}, 4); {range({}, 4)} db> select range({}, {}); {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. ```edgeql-repl 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, {})); gel error: InvalidValueError: cannot unpack an unbounded range ``` ## Bytes The `bytes` type represents raw binary data. ```edgeql-repl 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. ```edgeql-repl 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: ```edgeql-repl 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. | | | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Indexing and slicing | [`array[i]`](https://docs.geldata.com/reference/stdlib/array.md#operator::arrayidx) [`array[from:to]`](https://docs.geldata.com/reference/stdlib/array.md#operator::arrayslice) [`array_get()`](https://docs.geldata.com/reference/stdlib/array.md#function::std::array_get) | | Concatenation | [`array ++ array`](https://docs.geldata.com/reference/stdlib/array.md#operator::arrayplus) | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Utilities | [`len()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::len) [`array_join()`](https://docs.geldata.com/reference/stdlib/array.md#function::std::array_join) | | Search | [`contains()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::contains) [`find()`](https://docs.geldata.com/reference/stdlib/generic.md#function::std::find) | | Conversion to/from sets | [`array_agg()`](https://docs.geldata.com/reference/stdlib/array.md#function::std::array_agg) [`array_unpack()`](https://docs.geldata.com/reference/stdlib/array.md#function::std::array_unpack) | See [Standard Library > Array](https://docs.geldata.com/reference/stdlib/array.md#ref-std-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. ```edgeql-repl 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. ```edgeql-repl db> 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. ```edgeql-repl 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')} ``` > Important: When you query an *unnamed* tuple using one of EdgeQL's [client libraries](https://docs.geldata.com/reference/using/clients.md#ref-clients-index), 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](https://docs.geldata.com/reference/stdlib/tuple.md#ref-std-tuple). ## JSON The [`json`](https://docs.geldata.com/reference/stdlib/json.md#type::std::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()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::to_json). Any type can be converted into JSON except [`bytes`](https://docs.geldata.com/reference/stdlib/bytes.md#type::std::bytes). ```edgeql-repl db> select 5; {'5'} db> select "a string"; {'"a string"'} db> select ["this", "is", "an", "array"]; {'["this", "is", "an", "array"]'} db> select ("unnamed tuple", 2); {'["unnamed tuple", 2]'} db> select (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`. ```edgeql-repl 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](https://docs.geldata.com/reference/stdlib/json.md#ref-std-json) or click an item below for detailed documentation. | | | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Indexing | [`json[i]`](https://docs.geldata.com/reference/stdlib/json.md#operator::jsonidx) [`json[from:to]`](https://docs.geldata.com/reference/stdlib/json.md#operator::jsonslice) [`json[name]`](https://docs.geldata.com/reference/stdlib/json.md#operator::jsonobjdest) [`json_get()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::json_get) | | Merging | [`json ++ json`](https://docs.geldata.com/reference/stdlib/json.md#operator::jsonplus) | | Comparison operators | [`=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::eq) [`!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::neq) [`?=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coaleq) [`?!=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::coalneq) [`<`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lt) [`>`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gt) [`<=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::lteq) [`>=`](https://docs.geldata.com/reference/stdlib/generic.md#operator::gteq) | | Conversion to/from strings | [`to_json()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::to_json) [`to_str()`](https://docs.geldata.com/reference/stdlib/string.md#function::std::to_str) | | Conversion to/from sets | [`json_array_unpack()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::json_array_unpack) [`json_object_unpack()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::json_object_unpack) | | Introspection | [`json_typeof()`](https://docs.geldata.com/reference/stdlib/json.md#function::std::json_typeof) |