Skip to content

Writing expressions

Geometric shapes fitting together in cool tones

An expression is a short formula that calculates a value: the amount including VAT of a line, a label depending on the total, an instalment due in thirty days. They are used in reports, in calculated columns and in conditions, and here is the reference for the language at three levels of detail.

Where do I start if I only want to calculate a column?

With the quick guide to the expression language. It is the practical reference: a table of ‘I want this, I type this’, the most used functions and the typical errors with the message each one gives.

That covers almost everything for day-to-day use. A field from the row is written in square brackets, [Importe]; numbers use a decimal point; comparing is == and not =; and it doesn’t matter how you use capitals in field and function names.

What happens with empty fields?

They behave as in the database: any operation with an empty value gives an empty value. It is the most common reason for a calculated column coming out blank without an error, and the fix is to give the field a default value before operating with it.

The quick guide has a whole section on this, with the ways of asking whether a field is empty and the functions that ignore empty values instead of propagating them.

Can I write in the style I know?

Yes. There is no selector or mode to switch on: the grammar accepts both the C# forms and the Python forms at the same time, even mixed in the same expression. Write && or and, c ? a : b or a if c else b, null or None, and the result is exactly the same.

The minimal syntax and usage manual sums it up on one page, with the table of equivalences between the two styles and the whole syntax in ten lines. It sits halfway between the quick guide and the specification.

Where is the exact definition of the language?

In the expression engine grammar: the tokens, the formal grammar, the types and their conversions, the semantics of empty values and the list of allowed functions. It is the specification, not a tutorial: you look it up when the question is whether something is valid or not.

Why are some expressions short and others a script?

Because there are two levels and they aren’t for the same thing. The expression level is a single formula with no statements or assignments, and that limitation is deliberate: since it can’t repeat or assign, it always finishes. It is what is used in reports and in calculated columns.

The second level is scripts, with variables and blocks, and it is meant for automations and plugins. The three documents cover it at the end: the quick guide introduces it, the manual says what it is for and what it isn’t for, and the grammar defines it.

What happens when an expression is wrong?

It isn’t run halfway: the program warns you first. The errors are written to be read without knowing how to program, and several suggest the fix —a mistyped field suggests the similar name, and using = to compare reminds you that it is written ==—.

There is one message that isn’t a syntax error and is worth recognising: if the expression uses data that your profile can’t see, the program says so and doesn’t calculate. Permissions apply here too.