Expressions¶

One expression language serves every place that reads values from features:

• Select By Attributes, Definition Query, display filters, label classes, attribute constraints and reports use an expression as a condition (a WHERE clause): a feature matches when the expression is true.
• Calculate Field and calculation attribute rules use an expression as a value, stored in the field after conversion to the field's type.
• Symbols by expression take a value per feature: a marker's size, the fill and outline colours, the outline width and a marker's angle.
• Labels by expression take a label class's text, size, colour and angle per feature.
• Unique Values can class features by an expression's value instead of a field's.

pop_est > 100000000 AND continent = 'Asia'
name LIKE 'S%' OR iso_a3 IN ('FRA', 'DEU', 'ITA')
"name" || ' (' || to_string(round(pop_est / 1e6)) || ' M)'
CASE WHEN pop_est > 1e8 THEN 'large' WHEN pop_est > 1e7 THEN 'medium' ELSE 'small' END
scale_linear(pop_est, 0, 1e9, 2, 12)
area('ac') BETWEEN 1 AND 5 AND zoning = 'R-1'

Grammar¶

Keywords and function names are not case sensitive. Rules are listed from the loosest binding to the tightest; [ x ] is optional, { x } repeats zero or more times, | separates choices.

expression = or ;
or         = and { "OR" and } ;
and        = not { "AND" not } ;
not        = "NOT" not | comparison ;
comparison = concat [ compare_op concat
                    | "IS" [ "NOT" ] "NULL"
                    | [ "NOT" ] ( "LIKE" | "ILIKE" ) concat
                    | [ "NOT" ] "IN" "(" expression { "," expression } ")"
                    | [ "NOT" ] "BETWEEN" concat "AND" concat ] ;
compare_op = "=" | "==" | "<>" | "!=" | "<" | "<=" | ">" | ">=" ;
concat     = sum { "||" sum } ;
sum        = product { ( "+" | "-" ) product } ;
product    = unary { ( "*" | "/" | "%" ) unary } ;
unary      = ( "-" | "+" ) unary | power ;
power      = primary [ "^" unary ] ;
primary    = number | text | "TRUE" | "FALSE" | "NULL"
           | field | variable | call | case | "(" expression ")" ;
call       = name "(" [ expression { "," expression } ] ")" ;
case       = "CASE" [ expression ]
             "WHEN" expression "THEN" expression
             { "WHEN" expression "THEN" expression }
             [ "ELSE" expression ] "END" ;

number     = digits [ "." digits ] [ exponent ] | "." digits [ exponent ] ;
exponent   = ( "e" | "E" ) [ "+" | "-" ] digits ;
text       = "'" { character | "''" } "'" ;
field      = name | '"' { character | '""' } '"' | "!" { character } "!" ;
variable   = "@" name | "$" name ;
name       = ( letter | digit | "_" ) { letter | digit | "_" } ;   (* not starting with a digit *)

So a OR b AND c is a OR (b AND c), NOT a = b is NOT (a = b), 1 + 2 * 3 is 7, -2 ^ 2 is −4 and 2 ^ 3 ^ 2 is 512 (^ groups from the right). A comparison takes one operator: write a < b AND b < c, not a < b < c.

Values¶

An unknown field, variable or function is an error that names it.

Operators¶

Rules shared by all of them:

• Comparing numbers and text. A number and text that reads as a number compare as numbers ('12' = 12 is true). Two texts compare as text, ignoring letter case, even when both read as numbers (name = 'paris' matches Paris; '10' < '9'; LIKE ignores case too).
• Arithmetic reads text as a number when it is one ('12' + 1 is 13). + joins text that isn't (name + ' km'); -, *, / on such text give null.
• Nulls. Arithmetic with a null gives null. A comparison with a null is unknown: it matches neither pop > 100 nor NOT pop > 100; IS NULL tests for it. AND is false when either side is false and OR true when either side is true, whatever the other side is.
• Errors give null: a division by zero, the square root of a negative number, a result too large to represent.
• IN compares with each value as = does; a NULL in the list matches nothing, so x NOT IN (1, NULL) is true for 2.
• As a condition, a value that isn't true or false counts as true when it is a non-zero number or non-empty text.

Functions¶

Areas and lengths are measured on the WGS 84 ellipsoid, as Calculate Geometry in the attribute table measures them, whatever the layer's coordinate system (with the same two exceptions, a ring with a full-turn edge and one winding around a pole). On a feature with no geometry, or coordinates that aren't longitudes and latitudes, they are null. Measuring another kind of layer ($area on lines), or a unit that isn't one of those, is an error.

Limits¶

A number too large to represent (1e999) is an error. An expression is at most 10,000 characters and nests at most 64 levels: each parenthesis, function call, NOT, sign before something other than a number, ^ and CASE counts (a CASE two). One chain of AND, OR, ||, +/- or *///%, and the arms of one CASE, take at most 256 terms; a function at most 32 arguments; an IN list as many as fit. Text an expression makes is cut at 64 KiB, and a LIKE pattern longer than 10,000 characters matches nothing. A LIKE that would take more than about 16 million steps to match (a very long text against a pattern of many %s) is unknown.

Calculate Field¶

A number goes into a number field as it is: a decimal field keeps every digit of 1 / 3 (a whole number past 2^53 becomes the nearest decimal, as a decimal field holds it). A whole-number field holds whole numbers, so a decimal result, or text written as one, loses its fraction toward zero (2.7 is 2, -2.7 is -2), and one past the 64-bit integer range, or not a number (NaN), is left empty. Calculate Field, and a calculation attribute rule on each edit it applies to, says how many results lost their fraction, how many were past the range and how many weren't numbers. Text that doesn't read as a number at all (n/a) is left empty too, for now without a notice. A number into a text field is written as RustGIS shows it, to six decimal places.

Calculate Field also takes the forms its earlier calculator took: a field name with spaces written bare (Pop Est * 2) still works when the text isn't a valid expression, and on a layer with a field named true, false or null such forms keep reading it as the field (in other expressions, quote it: "null"). Text that starts and ends with a quote but holds more quotes now reads as an expression: 'it''s' is it's and 'a' || 'b' is ab, where both were taken as the text between the outer quotes.