[comment]: # ({731aa9c5-510ac9cc})
# 3 Trigger expression

[comment]: # ({/731aa9c5-510ac9cc})

[comment]: # ({3a919b3c-473bcd5e})
#### Overview

This page describes the trigger expression syntax and evaluation details.

The syntax of a simple expression is:

**`function`**(`/host/item`,`time_period`)<**`operator`**><**`constant`**>

In this expression, the first operand (to the left of the operator) is a [function](#functions) with its [parameters](#function-parameters) in parentheses (typically the data item and time period). 

The function is used to analyze received data during the set time period, resulting in a calculated value.

This value is then compared to the second operand, using the [operator](#operators). In this example the second operand is a constant, but it can also be another function. 

For example:

```
min(/Zabbix server/net.if.in[eth0,bytes],5m)>100K
```

This trigger fires if the number of received bytes on `eth0` during the last five minutes was always over 100 kilobytes. In this case the expression is true and a problem is created.

Trigger expressions are extremely flexible. In more complex expressions, a number of functions, operators and constants can be combined.

See also:

-   [Trigger examples](/manual/config/triggers/trigger_examples)
-   [Problem detection with triggers](/manual/config/triggers) (general introduction)

[comment]: # ({/3a919b3c-473bcd5e})

[comment]: # ({856cad55-d4e5ef03})
#### Functions

Functions allow to analyze collected values, for example, calculate the average or find a specific string.

Click the respective function group to see more details.

|Function group|<|Functions|
|-|----------|----------------------------------------|
|[Aggregate functions](/manual/config/triggers/expression/aggregate/)|<|avg, bucket\_percentile, count, histogram\_quantile, item\_count, kurtosis, mad, max, min, skewness, stddevpop, stddevsamp, sum, sumofsquares, varpop, varsamp|
| |[Foreach functions](/manual/config/triggers/expression/aggregate/foreach)|avg\_foreach, bucket\_rate\_foreach, count\_foreach, exists\_foreach, last\_foreach, max\_foreach, min\_foreach, sum\_foreach|
|[Bitwise functions](/manual/config/triggers/expression/bitwise)|<|bitand, bitlshift, bitnot, bitor, bitrshift, bitxor|
|[Date and time functions](/manual/config/triggers/expression/time)|<|date, dayofmonth, dayofweek, now, time|
|[History functions](/manual/config/triggers/expression/history)|<|change, changecount, count, countunique, find, first, firstclock, fuzzytime, last, lastclock, logeventid, logseverity, logsource, logtimestamp, monodec, monoinc, nodata, percentile, rate|
|[Trend functions](/manual/config/triggers/expression/trends)|<|baselinedev, baselinewma, trendavg, trendcount, trendmax, trendmin, trendstl, trendsum|
|[Mathematical functions](/manual/config/triggers/expression/math)|<|abs, acos, asin, atan, atan2, avg, cbrt, ceil, cos, cosh, cot, degrees, e, exp, expm1, floor, log, log10, max, min, mod, pi, power, radians, rand, round, signum, sin, sinh, sqrt, sum, tan, truncate|
|[Operator functions](/manual/config/triggers/expression/operator)|<|between, in|
|[Predictive functions](/manual/config/triggers/expression/predictive)|<|forecast, timeleft|
|[String functions](/manual/config/triggers/expression/string)|<|ascii, bitlength, bytelength, char, concat, insert, jsonpath, left, length, ltrim, mid, repeat, replace, right, rtrim, trim, xmlxpath|

Except where stated otherwise, these functions are supported in:

-   [Trigger expressions](/manual/config/triggers/expression)
-   [Calculated items](/manual/config/items/itemtypes/calculated)
-   [Expression macros](/manual/config/macros/expression_macros)

Foreach functions are supported only for [aggregate calculations](/manual/config/items/itemtypes/calculated/aggregate).

Typically functions return numeric values for comparison.
When returning strings, comparison is possible with the **=** and **<>** operators (see [Detect non-matching software on different hosts](/manual/config/triggers/trigger_examples#detect-non-matching-software-on-different-hosts) example).

[comment]: # ({/856cad55-d4e5ef03})

[comment]: # ({f1c0b59d-b255de16})
#### Function parameters

Function parameters allow to specify:

-   item key (as `/host/key`) for functions referencing a host item history
-   time period (and other function-specific parameters)
-   [other expressions](#other-expressions)

[comment]: # ({/f1c0b59d-b255de16})

[comment]: # ({c59d025d-7ea76dfe})

##### Item key

The referenced item must be in a supported state (except for **nodata()** function, which is calculated for unsupported items as well).

Omission of the host name in the first parameter (i.e. as in `function(//key,parameter,...)`) is only supported in certain contexts:

-   In the formula of calculated items
-   In expression macros, which can be used in:
    -   The [*Event name*](/manual/config/triggers/trigger#configuration) field
    -   Graph name
    -   The label of "Host" and "Trigger" [map elements](/manual/config/visualization/maps/map#adding-elements)

In these contexts, you may also use the [`{HOST.HOST}`](/manual/appendix/macros/supported_by_location#hosthost) macro.
`{HOST.HOST<1-9>}` could be used in the case of the *Event name* field and the "Trigger" map element to refer to a specific item in the trigger expression.
When the host name is omitted or replaced by `{HOST.HOST}` in these contexts, the reference points to the first item in the trigger expression or to the first item in the graph.
Outside of these supported contexts, omitting the host name in trigger expressions will result in an error.
See [Compare long-term CPU loads](/manual/config/triggers/trigger_examples#compare-long-term-cpu-loads) example for an illustration of double-slash usage in Event name macros.

[comment]: # ({/c59d025d-7ea76dfe})

[comment]: # ({85352379-cf9e09bb})
##### Time period

Function-specific parameters are placed after the item key and are separated from the item key by a comma.

Most of numeric functions accept **time period** as a parameter.
It allows to specify the interval we are interested in. 
It can be specified as time period (30s, 10m, 1h) or as a value range (\#5 - for five latest values).

You may use seconds or [time suffixes](/manual/appendix/suffixes) to indicate the time period.
Preceded by a hash mark, the parameter has a different meaning:

|Expression|Description|
|----------|-----------|
|**sum**(/host/key,**10m)**|Sum of values in the last 10 minutes.|
|**sum**(/host/key,**\#10)**|Sum of the last ten values.|

Parameters with a hash mark have a different meaning with the function **last** - they denote the Nth previous value, so given the values 30, 70, 20, 60, 50 (from the most recent to the least recent):

-   `last(/host/key,#2)` would return '70'
-   `last(/host/key,#5)` would return '50'

The time period is measured up to "now" - where "now" is the latest recalculation time of the trigger (see [Calculation frequency](/manual/config/triggers#calculation-frequency)); "now" is not the "now" time of the server.

The time period specifies either:

-   All values between "now - time period" and "now" (or, with time shift applied, between "now - time shift - time period" and "now - time shift").
-   The specified number of values from the past, up to "now".

If no data exists for the specified evaluation period, the trigger or calculated item using this function becomes unsupported.

Note that:

-   If only a single function (referencing data history) is used in the
    trigger, "now" is always the latest received value. For example, if
    the last value was received an hour ago, the time period will
    be regarded as up to the latest value an hour ago.
-   A new trigger is calculated as soon as the first value is received
    (history functions); it will be calculated within 30 seconds for
    [date and time](/manual/config/triggers/expression/time) and [nodata()](/manual/config/triggers/expression/history#nodata) functions. Thus the trigger will be calculated even
    though perhaps the set time period (for example, one hour) has
    not yet passed since the trigger was created. The trigger will also
    be calculated after the first value, even though the time
    range was set, for example, to ten latest values.

[comment]: # ({/85352379-cf9e09bb})

[comment]: # ({da3613bd-6699e631})
##### Time shift

An optional time shift is supported with time or value count as the function parameter.
This parameter allows to reference data from a period of time in the past.

Time shift starts with `now` - specifying the current time, and is followed by `+N<time unit>` or `-N<time unit>` - to add or subtract N time units.

For example, `avg(/host/key,1h:now-1d)` will return the average value for an hour one day ago.

::: noteimportant
Time shift specified in months (M) and years (y) is only supported for [trend functions](/manual/config/triggers/expression/trends). Other functions support seconds (s), minutes (m), hours (h), days (d), and weeks (w).
:::

**Time shift with absolute time periods**

Absolute time periods are supported in the time shift parameter, for example, midnight to midnight for a day, Monday-Sunday for a week, first day-last day of
the month for a month.

Time shift for absolute time periods starts with `now` - specifying the current time, and is followed by any number of time operations: `/<time unit>` - defines the beginning and end of the time unit, for example, midnight to midnight for a day, `+N<time unit>` or `-N<time unit>` - to add or subtract N time units.

Please note that the value of time shift can be greater or equal to 0, while the time period minimum value is 1.

|Parameter|Description|
|--|--------|
|1d:now/d|Yesterday|
|1d:now/d+1d|Today|
|2d:now/d+1d|Last 2 days|
|1w:now/w|Last week|
|1w:now/w+1w|This week|

[comment]: # ({/da3613bd-6699e631})

[comment]: # ({7fc33108-c5d3ec54})
##### Other expressions

Function parameters may contain other expressions, as in the following syntax:

```default
min(min(/host/key,1h),min(/host2/key2,1h)*10)
```

Note that other expressions may not be used, if the function references item history.
For example, the following syntax is **not** allowed:

~~`min(/host/key,#5*10)`~~

While other trigger expressions as function parameters are limited to non-history functions in triggers, this limitation does not apply in [calculated items](/manual/config/items/itemtypes/calculated).

[comment]: # ({/7fc33108-c5d3ec54})

[comment]: # ({2ef1f03c-10bc91a2})
#### Operators

The following operators are supported for triggers **(in descending priority of execution)**:

|Priority|Operator|Definition|**Notes for [unknown values](/manual/config/triggers/expression#unknown-expression-state)**|Force cast operand to float ^**1**^|
|-|-|----|----------------|--|
|**1**|**-**|Unary minus|**-**Unknown → Unknown|Yes|
|**2**|**not**|Logical NOT|**not** Unknown → Unknown|Yes|
|**3**|**\***|Multiplication|0 **\*** Unknown → Unknown<br>(yes, Unknown, not 0 - to not lose<br>Unknown in arithmetic operations)<br>1.2 **\*** Unknown → Unknown|Yes|
|<|**/**|Division|Unknown **/** 0 → error<br>Unknown **/** 1.2 → Unknown<br>0.0 **/** Unknown → Unknown|Yes|
|**4**|**+**|Arithmetical plus|1.2 **+** Unknown → Unknown|Yes|
|<|**-**|Arithmetical minus|1.2 **-** Unknown → Unknown|Yes|
|**5**|**\<**|Less than. The operator is defined as:<br><br>A<B ⇔ (A<B-0.000001)|1.2 **<** Unknown → Unknown|Yes|
|<|**<=**|Less than or equal to. The operator is defined as:<br><br>A<=B ⇔ (A≤B+0.000001)|Unknown **<=** Unknown → Unknown|Yes|
|<|**>**|More than. The operator is defined as:<br><br>A>B ⇔ (A>B+0.000001)| |Yes|
|<|**>=**|More than or equal to. The operator is defined as:<br><br>A>=B ⇔ (A≥B-0.000001)| |Yes|
|**6**|**=**|Is equal. The operator is defined as:<br><br>A=B ⇔ (A≥B-0.000001) and (A≤B+0.000001)| |No ^**1**^|
|<|**<>**|Not equal. The operator is defined as:<br><br>A<>B ⇔ (A<B-0.000001) or (A>B+0.000001)| |No ^**1**^|
|**7**|**and**|Logical AND|0 **and** Unknown → 0<br>1 **and** Unknown → Unknown<br>Unknown **and** Unknown → Unknown|Yes|
|**8**|**or**|Logical OR|1 **or** Unknown → 1<br>0 **or** Unknown → Unknown<br>Unknown **or** Unknown → Unknown|Yes|

^**1**^ String operand is still cast to numeric if:

-   another operand is numeric
-   operator other than **=** or **<>** is used on an operand

(If the cast fails - numeric operand is cast to a string operand and both operands get compared as strings.)

**not**, **and** and **or** operators are case-sensitive and must be in lowercase.
They also must be surrounded by spaces or parentheses.

All operators, except unary **-** and **not**, have left-to-right associativity.
Unary **-** and **not** are non-associative (meaning **-(-1)** and **not (not 1)** should be used instead of **--1** and **not not 1**).

Evaluation result:

-   **<**, **<=**, **>**, **>=**, **=**, **<>** operators shall yield '1' in the trigger expression if the specified relation is true and '0' if it is false.
If at least one operand is Unknown the result is Unknown;
-   **and** for known operands shall yield '1' if both of its operands compare unequal to '0'; otherwise, it yields '0'; for unknown operands **and** yields '0' only if one operand compares equal to '0'; otherwise, it yields 'Unknown';
-   **or** for known operands shall yield '1' if either of its operands compare unequal to '0'; otherwise, it yields '0'; for unknown operands **or** yields '1' only if one operand compares unequal to '0'; otherwise, it yields 'Unknown';
-   The result of the logical negation operator **not** for a known operand is '0' if the value of its operand compares unequal to '0'; '1' if the value of its operand compares equal to '0'.
For unknown operand **not** yields 'Unknown'.

[comment]: # ({/2ef1f03c-10bc91a2})

[comment]: # ({a5181770-cad1df72})

#### Unknown expression state

It is possible that an unknown operand appears in a trigger expression when:

-   unsupported item is used
-   function evaluation, for a supported item, results in error

In this case the trigger expression generally evaluates to `Unknown` (as it cannot be evaluated)

It is possible to [get notified](/manual/config/events/sources#internal-events) on unknown triggers.

**Exceptions**

Despite an unknown operand, trigger expressions can be evaluated to known result (Problem/OK) in some cases:

-   The [`nodata()`](/manual/config/triggers/trigger/expression/history#nodata) function is evaluated regardless of whether the referenced item is supported or not.
-   Expressions with AND/OR can be evaluated to known result in two cases:
    -   **Case 1**: "`1 or some_function(unsupported_item1) or some_function(unsupported_item2) or ...`" evaluates to known result ('1' or "Problem"),
    -   **Case 2**: "`0 and some_function(unsupported_item1) and some_function(unsupported_item2) and ...`" evaluates to known result ('0' or "OK").
-   If the function evaluation for a supported item results in error, the function value becomes `Unknown` and it takes part as unknown operand in further expression evaluation.

Unknown operands may "disappear" only in logical expressions as described above.
In arithmetic expressions unknown operands always lead to `Unknown` (except division by 0).

::: noteimportant
Unknown expression state does not change the trigger state (Problem/OK).
So, if trigger state was "Problem" (see Case 1), it stays in the problem state even if the known part is resolved ('1' becomes '0'), because the expression is now evaluated to `Unknown` and that does not change the trigger state.
:::

If a trigger expression with several unsupported items evaluates to `Unknown`, the error message in the frontend refers to the last unsupported item evaluated.

[comment]: # ({/a5181770-cad1df72})

[comment]: # ({0e2466bf-195c3f4f})
#### Value caching

Values required for trigger evaluation are cached by Zabbix server.
Because of this trigger evaluation causes a higher database load for some time after the server restarts.

The value cache is not cleared when item history values are removed (either manually or by housekeeper), so the server will use the cached values until they are older than the time periods defined in trigger functions or server is restarted.

::: noteclassic
If there is no recent data in the cache and there is no defined querying period in the function, Zabbix will by default go as far back in the past as one week to query the database for historical values.
:::

[comment]: # ({/0e2466bf-195c3f4f})