Expressions are used to represent a value or a set of values in EdgeQL commands.
EdgeQL supports the following scalar literals:
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 a name (a simple identifier or a qualified schema name) that represents a set of values. It can be the name of an object type or an expression alias (defined in a statement WITH block or in the schema via an alias declaration).
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 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 <str>$name;
See this section for more information on parameters.
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, or 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.