Expressions

Example expressions are 1 + 2, row / 5, @if row < 10 @then 0 @else row @endif. Expressions are called formulas in spreadsheets. They are a way of performing some calculation, generally as part of a larger transformation. For example, Calculate processes the expression once per row and shows the value, Filter processes the expression once per row and keeps only certain rows.

Expressions very often use the values of columns in them. Unlike spreadsheets, columns are referred to by name (rather than cell references like B6). Columns can be referred to either as a single value on the current row, or as a list of all the values in the column.

Columns

Most expressions use a column. This might be to use a column value to filter out some rows (e.g. Sales > 0, or to subtract the value in one column from the value in another (e.g. After - Before.

To use the value of a column on the current row in a Filter or Calculate, just type the name of the column, e.g. Price. If you need to use the whole column as a list, use the table name and column name like this: table\\Sales#Price. The entire column can be useful if you need access to specific entries using the element(..) or element or(..) functions, but an Aggregate transformation which helps to calculate column totals, averages, etc, may be more appropriate.

Numeric calculations

The standard add (+), subtract (-), multiply (*), divide (/) and raise-to-power (^) operators can be used to perform calculations. If the order of operations is unclear, the operators must be bracketed, e.g. 1 + 2 * 3 is not allowed, it must either be written (1 + 2) * 3 or 1 + (2 * 3).

A useful feature to avoid mistakes is the idea of units of measure. Numbers can be given units, and they will be tracked through calculations, converted between, and checked. For example, 15{m} means 15 metres, and 15{m} / 60{s} will give 0.25{m/s}. If you try to compare mismatching units such as (15{m} / 60{s}) < 10{mile/hour} then you will get an error, which helps avoid mistakes with different quantities. More information on this is available in the units guide.

Text manipulation

Text values can be joined together using the ; operator. For example, "a" ; "bc" ; "d" gives "abcd". Lists of text can be joined together with join text(..) or if a separator (e.g. a comma) is needed between each item then join text with(..).

Text is stored as Unicode, meaning that it can deal with non-English characters, emoji and the rest of the Unicode standard.

Comparison

You can use the less-than (<), less-than-or-equal-to (<=), greater-than (>) and greater-than-or-equal-to(>=) operators to compare values. You can also chain together several operators of the same direction, for example 1 <= row <= 10 checks if row is between 1 and 10 (inclusive).

If you need the lowest or highest item in a list, you can use the minimum(..) and maximum(..), which work on any types (numbers, text, dates, etc).

Equality

You can use the equals (=) and not equals (<>) operators to compare values for being the same. You can only compare items which have the same type.

It is also possible to compare a value against a pattern such as 5 ± 0.01 (meaning within 0.01 of 5) or "The" ; _ (meaning any text beginning with "The"). See the section on patterns for more details.

Patterns

A pattern is a way to flexibly compare against a value. For example, you may want to check if two columns have almost the same numeric value, Actual = Forecast will be false if say Actual was 2.356 and Forecast was 2.353. Instead you can use Actual = Forecast ± 0.01 which checks if they are within 0.01 of each other.

Another example where patterns are very useful is in text matching. Often you want to match the beginning, something in the middle, or the end, but not the entire text. Animal = _ ; "cat" will check if the Animal text ends with "cat". Underscore means match anything, as you want to match anything followed by cat. If you want to use the value of part of the pattern afterwards then you can put a name with the underscore, for example @if Animal = _type ; "cat" @then "Cat type: " ; type @else "Not a cat" @endif applied to "Wildcat" will give back "Cat type: Wild".

If Then Else

It is very common to need to choose between two alternatives based on some condition. For example, @if Amount >= 0 @then "Incoming" @else "Outgoing" @endif chooses which text to display based on the value in the amount column.

The format is always @if condition @then value_if_true @else value_if_false @endif. The condition part usually involves a comparison or an equality check, the latter of which may feature a pattern.

If you need to compare one value against many possibilities, you may find a match expression better than multiple if-then-else expressions.

Match Expressions

Sometimes you may want to compare a value against multiple possible alternatives. For example, @match Level @case "High" @then 2 @case "Medium" @then 1 @case "Low" @then 0 @endmatch matches Level against High/Medium/Low and gives back the number 2/1/0 respectively.

It is also possible to attach extra conditions to each case using @given, for example @match Amount @case n @given n < 0 @then "Negative" @case 0 @then "Zero" @case n @given n > 0 @then "Positive" @endmatch works out whether the number is negative, zero or positive.

Cases inside a match are checked in order, so often the last item can be @case _ meaning match anything, given that that the earlier matches failed. If no cases match then an error will occur.