IQL Syntax

Let’s take a look at the syntax of IQL queries and filters. We are going to start from the top, and gradually break down what each expression means until we reach the "atoms" that make up IQL.

To manually display predictive text in the IQL editor, tap Ctrl+Space on your keybord.

Queries

The entry point of an IQL query is:

Query ::= <ResultColumn> FROM <Table> WHERE <Filter> GROUP BY <Expr> ORDER BY <Expr>

Each keyword is used to indicate how to interpret the next expression. The keywords WHERE, GROUP BY and ORDER BY (and their corresponding expressions) are all optional, but must appear in the order above.

Table above is simply the of the table. It consists of either an identifier (a text string consisting of the letters A-Z and digits 0-9), or any text string within double quotation marks ".

Similar identifiers are used in many places within IQL. They are interpreted as table names, field names, list items, rule names, or functions depending on their surrounding context.

Filters

A Filter can be used as a part of a query, or as an entrypoint itself, and is defined by the following rule:

Filter ::= <Comparison> | <Filter> AND <Filter> | <Filter> OR <Filter>

A filter is a boolean expression, that is, an expression that evaluates to true or false. It is either a comparison, a conjunction (AND) or a disjunction (OR). Each comparison must be further broken down:

Comparison ::= <Expr> <BooleanOperator> <Expr>
             | <Column> <LikeOperator> <Literal>
             | <Expr> IS NOT? NULL
             | <Expr> IN ( Query )
             | <Expr> IN ( ValueList )

Here BooleanOperator is simply one of the operators =, !=, <, >, >=, <=, while LikeOperator are the keywords LIKE, STARTSWITH, ENDSWITH, and CONTAINS. To read more about these operators, see the reference.

Filters can be grouped using parentheses.

Statements

IQL statements is a further generalization of IQL. While filters and queries are declarative, statements are procedures that may cause side effects. Statements are the entrypoint for Run IQL rules, Behavior in forms, and Run on x actions in forms.

Statements ::= <empty> | <Statement> <Statements>

Statement ::= SET <AssignOperations>
            | LET <Parameter> = <Expr>
            | AWAIT <Parameter> = <Expr>
            | IF <Expr> THEN <Statements> END
            | IF <Expr> THEN <Statements> ELSE <Statements> END
            | FOR <LoopQuery> DO <Statements> END
            | INSERT <Table> VALUES <AssignOperations>
            | CALL <Function>
            | TRIGGER <Rule>

AssignOperations ::= <AssignOperation> | <AssignOperation> , <AssignOperations>

AssignOperation ::= <Field> = <Expr> | <PseudoField> = <Expr>
TRIGGER, FOR and INSERT statements are only valid in Run IQL rules. CALL and AWAIT are only valid in Run on x configurations.

Expressions

Expr above is a generic expression. It can be a field name path, a pseudo field, a literal value, a parameter, a function, or any mathematical expression.

Expr ::= <FieldPath>
       | <Literal>
       | <Expr> <MathOperator> <Expr>
       | <Expr> || <Expr>
       | <FunctionCall>
       | ( <Query> )

FieldPath ::= <PseudoField>
            | <Field>
            | <Field> . <FieldPath>

Here MathOperator is the arithmetic operators +, -, * and /. Double pipe || signifies text concatenation. Expressions can also be grouped using parentheses.

'my text', @param, (Salary + 1000) / 2, recordname || '_2' and substring(Department.Name, 1, 5) are all examples of expressions.

Literals

A literal is a constant value hard-coded into the IQL. E.g., the expression Salary + 10 has one literal, the number 10.

Literal Type Examples

Text

'marketing' 'an example text value' '10'

Number

5 -1 6.25

Date (or datetime)

2024-11-05 2010-02-22T18:15:00

Boolean (checkbox)

true false
Date literals are expressed in ISO 8601 format without a timezone designator. The time part is optional and defaults to midnight if omitted.

Parameters

A parameter is a special type of literal which can change value during runtime. A parameter is indicated by an identifier that starts with a @.

Parameter names are not case-sensitive, but using consistent naming usually aids readibility.

Functions

There are a number of functions available to perform calculations or other transformations of the data. A function call is dictated by the grammar rules:

Function ::= <IDENTIFIER> ( <ArgList>? )
ArgList ::= <Expr> | <Expr> , <ArgList>

In other words, today(), length(Text) and substring(Text, 1, 3) are all function calls.

Aggregate functions are syntactically just functions, but they are only valid to be used in the "ResultColumn" part of a query.

Reserved words

The following words have special meanings in IQL. Although written in uppercase here, they are not case-sensitive.

Keywords

FROM WHERE GROUP ORDER BY DESC IF THEN ELSE END SET LET CALL TRIGGER FOR DO INSERT VALUES AWAIT

Operators

AND OR IS NOT IN LIKE STARTSWITH ENDSWITH CONTAINS

System defined fields

CDATE UDATE CTIME UTIME CUSER UUSER CUSERNAME UUSERNAME CREALNAME UREALNAME RECORDID RECORDNAME RECORDGROUP RECORDURI

Special values

NULL TRUE FALSE

Other

USER NONE FORM

Comments

IQL has two styles of comments. Two minus signs -- is used to comment the remainder of the line. Anything within /* and */ is also considered a comment.