Functions

Example

Declare a custom function that concatenates the length of a string to the end of the that string:

function foo(s: str) -> str
    using (
        SELECT s ++ <str>len(a)
    );

Syntax

Define a new function corresponding to the more explicit DDL commands.

function name ([ argspec ] [, ... ]) -> returnspec
using ( edgeql );

function name ([ argspec ] [, ... ]) -> returnspec
using language functionbody ;

function name ([ argspec ] [, ... ]) -> returnspec
"{"
    [ annotation-declarations ]
    [ volatility := {'Immutable' | 'Stable' | 'Volatile'} ]
    [ using ( expr ) ; ]
    [ using language functionbody ; ]
    [ ... ]
"}" ;

where argspec is:

[ argkind ] argname: [ typequal ] argtype [ = default ]

argkind is:

[ { variadic | named only } ]

typequal is:

[ { set of | optional } ]

and returnspec is:

[ typequal ] rettype

Description

This declaration defines a new constraint with the following options:

name

The name (optionally module-qualified) of the function to create.

argkind

The kind of an argument: variadic or named only.

If not specified, the argument is called positional.

The variadic modifier indicates that the function takes an arbitrary number of arguments of the specified type. The passed arguments will be passed as as array of the argument type. Positional arguments cannot follow a variadic argument. variadic parameters cannot have a default value.

The named only modifier indicates that the argument can only be passed using that specific name. Positional arguments cannot follow a named only argument.

argname

The name of an argument. If named only modifier is used this argument must be passed using this name only.

typequal

The type qualifier: set of or optional.

The set of qualifier indicates that the function is taking the argument as a whole set, as opposed to being called on the input product element-by-element.

The optional qualifier indicates that the function will be called if the argument is an empty set. The default behavior is to return an empty set if the argument is not marked as optional.

argtype

The data type of the function’s arguments (optionally module-qualified).

default

An expression to be used as default value if the parameter is not specified. The expression has to be of a type compatible with the type of the argument.

rettype

The return data type (optionally module-qualified).

The set of modifier indicates that the function will return a non-singleton set.

The optional qualifier indicates that the function may return an empty set.

The valid SDL sub-declarations are listed below:

volatility := {'Immutable' | 'Stable' | 'Volatile'}

Function volatility determines how aggressively the compiler can optimize its invocations.

If not explicitly specified the function volatility is set to Immutable by default.

• A Volatile function can modify the database and can return different results on successive calls with the same arguments.

• A Stable function cannot modify the database and is guaranteed to return the same results given the same arguments within a single statement.

• An Immutable function cannot modify the database and is guaranteed to return the same results given the same arguments forever.

using ( expr )

Specified the body of the function. expr is an arbitrary EdgeQL expression.

using language functionbody

A verbose version of the using clause that allows to specify the language of the function body.

• language is the name of the language that the function is implemented in. Currently can only be edgeql.

• functionbody is a string constant defining the function. It is often helpful to use dollar quoting to write the function definition string.

annotation-declarations

Set function annotation to a given value.

The function name must be distinct from that of any existing function with the same argument types in the same module. Functions of different argument types can share a name, in which case the functions are called overloaded functions.