Expressions Overview

Expressions are used to represent a value or a set of values in EdgeQL commands.

EdgeQL supports the following scalar literals:

Syntax

Type

SELECT true;

bool

SELECT false;

bool

SELECT 42;

int64

SELECT -1.1;

float64

SELECT 1e-3;

float64

SELECT -42n;

decimal

SELECT 100.1n;

decimal

SELECT 'hello';

str

SELECT r'hello';

str (raw string)

SELECT $$ CREATE .. $$;

str (raw string)

SELECT b'bina\x01ry';

bytes

Refer to lexical structure for more details about the syntax for standard scalar literals.

Additionally, many scalar values can be represented as a cast string literal:

SELECT <int16>'1' = <int16>1;
SELECT <float32>'1.23';
SELECT <duration>'1 day';
SELECT <decimal>'1.23' = 1.23n;

EdgeQL defines many functions and operators to work with various scalar types, see the functions and operators section for more details.

A set reference is an name (a simple identifier or a qualified schema name) that represents a set of values. It can be the name of an object type, the name of a view, or an alias defined in a statement.

For example, in the following query User is a set reference:

SELECT User;

See this section for more information about set references.

A path expression (or simply a path) represents a set of values that are reachable when traversing a given sequence of links or properties from some source set. For example, here is s a path that represents the names of all friends of all User objects in the database.

SELECT User.friends.name;

Path expression syntax and semantics are described in detail in a dedicated section.

A shape is a powerful syntactic construct that can be used to dynamically describe a portion of an object graph. For example, the below query returns a set of Issue objects and includes a number and an associated owner User object, which in turn includes the name and the email for that user:

db> 
... 
... 
... 
... 
... 
... 
... 
SELECT
    Issue {
        number,
        owner: {  # sub-shape, selects Issue.owner objects
           name,
           email
        }
    };

{
    'number': 1,
    'owner': {
        'name': 'Alice',
        'email': 'alice@example.com'
    }
}

See this section for more information on shape syntax and semantics.

A parameter reference is used to indicate a value that is supplied externally to an EdgeQL expression. Parameter references are used in parametrized statements. The form of a parameter reference is:

SELECT $name;

Most operators in EdgeQL are binary infix or unary prefix operators. Some operators have dedicated syntax, like the IF..ELSE operator.

Binary infix operator syntax:

expression operator expression

Unary prefix operator syntax:

operator expression

A complete reference of standard EdgeQL operators can be found in Functions and Operators.

Expressions can be enclosed in parentheses to indicate explicit evaluation precedence and to group subexpressions visually for better readability:

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

The syntax for a function call is as follows:

function-name "(" [argument [, argument ...]] ")"

Here function_name is a possibly qualified name of a function, and argument is an expression optionally prefixed with an argument name and the assignment operator (:=).

A complete reference of standard EdgeQL functions can be found in Functions and Operators.

A type cast expression converts the specified value to another value of the specified type:

"<" type ">" expression

The type must be a valid type expression denoting a non-abstract scalar or a container type.

For example, the following expression casts an integer value into a string:

db> 
SELECT <str>10;
{"10"}

See the type cast operator section for more information on type casting rules.

A set constructor is an expression that consists of a sequence of comma-separated expressions enclosed in curly braces:

"{" expr [, ...] "}"

A set constructor produces the result by appending its elements. It is perfectly equivalent to a sequence of UNION operators.

An empty set can also be created by omitting all elements. In situations where EdgeDB cannot infer the type of an empty set, it must be used together with a type cast:

db> 
SELECT {};
EdgeQLError: could not determine the type of empty set
db> 
SELECT <int64>{};
{}

A tuple is collection of values of possibly different types. For example:

db> 
SELECT (1.0, -2.0, 'red');
{(1.0, -2.0, 'red')}
db> 
SELECT (180, 82);
{(180, 82)}
db> 
SELECT (180, 82).0;
{180}

EdgeQL also supports named tuples:

db> 
SELECT (x := 1.0, y := -2.0, color := 'red');
{(x := 1.0, y := -2.0, color := 'red')}
db> 
SELECT (height := 180, weight := 82);
{(height := 180, weight := 82)}
db> 
SELECT (height := 180, weight := 82).height;
{180}
db> 
SELECT (height := 180, weight := 82).1;
{82}

Tuples can be nested in arrays, returned from functions, be a valid object property type.

See the tuple expression reference for more information on tuple constructors and accessing tuple elements.

An array is a 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)]}

See array expression reference for more information on array constructors.

Any SELECT or FOR statement, and, with some restrictions, INSERT, UPDATE or DELETE statements may be used as expressions. Parentheses are required around the statement to disambiguate:

SELECT 1 + (SELECT len(User.name));

See the statements section for more information.