[comment]: # attributes: notoc

[comment]: # (terms: avg, bucket_percentile, count, histogram_quantile, item_count, kurtosis, mad, max, min, skewness, stddevpop, stddevsamp, sum, sumofsquares, varpop, varsamp )

[comment]: # (tags: count )

[comment]: # ({cbe17b03-ee60e21e})
# 1 Aggregate functions

Except where stated otherwise, all functions listed here are supported in:

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

Aggregate functions can work with either:

-   history of items, for example, `min(/host/key,1h)`
-   [foreach functions](/manual/config/triggers/expression/aggregate/foreach) as
    the only parameter, for example, `min(last_foreach(/*/key))` (only in calculated item formulas; to use in triggers reference the calculated item by its key)

The functions are listed without additional information. Click on the function to see the full details.

|Function|Description|
|--|--------|
|[avg](#avg)|The average value of an item within the defined evaluation period.|
|[bucket_percentile](#bucket-percentile)|Calculates the percentile from the buckets of a histogram.|
|[count](#count)|The count of values in an array returned by a foreach function.|
|[histogram_quantile](#histogram-quantile)|Calculates the φ-quantile from the buckets of a histogram.|
|[item_count](#item-count)|The count of existing items in configuration that match the filter criteria.|
|[kurtosis](#kurtosis)|The "tailedness" of the probability distribution in collected values within the defined evaluation period.|
|[mad](#mad)|The median absolute deviation in collected values within the defined evaluation period.|
|[max](#max)|The highest value of an item within the defined evaluation period.|
|[min](#min)|The lowest value of an item within the defined evaluation period.|
|[skewness](#skewness)|The asymmetry of the probability distribution in collected values within the defined evaluation period.|
|[stddevpop](#stddevpop)|The population standard deviation in collected values within the defined evaluation period.|
|[stddevsamp](#stddevsamp)|The sample standard deviation in collected values within the defined evaluation period.|
|[sum](#sum)|The sum of collected values within the defined evaluation period.|
|[sumofsquares](#sumofsquares)|The sum of squares in collected values within the defined evaluation period.|
|[varpop](#varpop)|The population variance of collected values within the defined evaluation period.|
|[varsamp](#varsamp)|The sample variance of collected values within the defined evaluation period.|

[comment]: # ({/cbe17b03-ee60e21e})

[comment]: # ({a83c5ed7-4d343eb8})
#### Common parameters

-   `/host/key` is a common mandatory first parameter for the functions
    referencing the host item history
-   `(sec|#num)<:time shift>` is a common second parameter for the
    functions referencing the host item history, where:
    -   **sec** - maximum [evaluation
        period](/manual/config/triggers/expression#time-period) in seconds
        (time [suffixes](/manual/appendix/suffixes) can be used), or
    -   **\#num** - maximum [evaluation
        range](/manual/config/triggers/expression#time-period) in latest
        collected values (if preceded by a hash mark)
    -   **time shift** (optional) allows to move the evaluation point
        back in time. See [more
        details](/manual/config/triggers/expression#time-shift) on
        specifying time shift.

[comment]: # ({/a83c5ed7-4d343eb8})

[comment]: # ({c645f0e4-fe53c04c})
### Function details

Some general notes on function parameters:

-   Function parameters are separated by a comma
-   Optional function parameters (or parameter parts) are indicated by
    `<` `>`
-   Function-specific parameters are described with each function
-   `/host/key` and `(sec|#num)<:time shift>` parameters must never be
    quoted

[comment]: # ({/c645f0e4-fe53c04c})

[comment]: # ({2844b0b7-f5993b4c})

##### avg(/host/key,(sec|#num)<:time shift>) {#avg}

The average value of an item within the defined evaluation period.<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach functions](/manual/config/triggers/expression/aggregate/foreach): *avg_foreach*, *count_foreach*, *exists_foreach*, *last_foreach*, *max_foreach*, *min_foreach*, *sum_foreach*.

Parameters: see [common parameters](#common-parameters).

Time shift is useful when there is a need to compare the current average value with the average value some time ago.

Examples:

```default
avg(/host/key,1h) #calculate the average value for the last hour until now
avg(/host/key,#5) #calculate the average value of the five latest values
avg(/host/key,1h:now-1d) #calculate the average value for an hour from 25 hours ago to 24 hours ago from now
avg(last_foreach(/*/system.cpu.load[,avg1]?[group="MySQL Servers"])) #calculate the average processor load for all MySQL servers
avg(/host/proc.num,5m)>300 #trigger if the average number of processes in the last 5 minutes has been above 300
```

[comment]: # ({/2844b0b7-f5993b4c})

[comment]: # ({ae55eda6-af24d13f})

##### bucket_percentile(item filter,time period,percentage) {#bucket-percentile}

Calculates the percentile from the buckets of a histogram.<br>

Parameters: 

-   **item filter** - see [item filter](/manual/config/triggers/expression/aggregate/foreach#item-filter-syntax);<br>
-   **time period** - see [time period](/manual/config/triggers/expression/aggregate/foreach#time-period);<br>
-   **percentage** - percentage (0-100).

Comments:

-   Supported only in calculated items;
-   This function is an alias for `histogram_quantile(percentage/100, bucket_rate_foreach(item filter, time period, 1))`.

Examples:

```default
bucket_percentile(/*/http_request_duration_seconds_bucket[*],5m,95) #calculate the 95th percentile response time over 5 minutes
bucket_percentile(/*/apiserver_request_duration_seconds_bucket[*],10m,99) #calculate the 99th percentile API latency
```

[comment]: # ({/ae55eda6-af24d13f})

[comment]: # ({4520f3ef-3c498650})

##### count(func_foreach(item filter,<time period>),<operator>,<pattern>) {#count}

The count of values in an array returned by a foreach function.<br>
Supported [foreach functions](/manual/config/triggers/expression/aggregate/foreach): *avg_foreach*, *count_foreach*, *exists_foreach*, *last_foreach*, *max_foreach*, *min_foreach*, *sum_foreach*.

Parameters: 

-   **func_foreach** - foreach function for which the number of returned values should be counted. See [foreach functions](/manual/config/triggers/expression/aggregate/foreach) for details. Note that count_foreach and bucket_rate_foreach support [additional parameters](/manual/config/triggers/expression/aggregate/foreach#additional-parameters).
-   **item filter** - see [item filter](/manual/config/triggers/expression/aggregate/foreach#item-filter-syntax);<br>
-   **time period** - see [time period](/manual/config/triggers/expression/aggregate/foreach#time-period);<br>
-   **operator** (must be double-quoted). Supported `operators`:<br>*eq* - equal<br>*ne* - not equal<br>*gt* - greater<br>*ge* - greater or equal<br>*lt* - less<br>*le* - less or equal<br>*like* - matches if contains pattern (case-sensitive)<br>*bitand* - bitwise AND<br>*regexp* - case-sensitive match of the regular expression given in `pattern`<br>*iregexp* - case-insensitive match of the regular expression given in `pattern`<br>
-   **pattern** - the required pattern (string arguments must be double-quoted); supported if *operator* is specified in the third parameter.

Comments: 

-   Using **count()** with a history-related foreach function (max_foreach, avg_foreach, etc.) may lead to performance implications, whereas using **exists_foreach()**, which works only with configuration data, will not have such effect.
-   Optional parameters *operator* or *pattern* can't be left empty after a comma, only fully omitted.
-   With *bitand* as the third parameter, the fourth `pattern` parameter can be specified as two numbers, separated by '/': **number_to_compare_with/mask**. count() calculates "bitwise AND" from the value and the *mask* and compares the result to *number_to_compare_with*. If the result of "bitwise AND" is equal to *number_to_compare_with*, the value is counted.<br>If *number_to_compare_with* and *mask* are equal, only the *mask* need be specified (without '/').
-   With *regexp* or *iregexp* as the third parameter, the fourth `pattern` parameter can be an ordinary or [global](/manual/regular_expressions#global-regular-expressions) (starting with '@') regular expression. In case of global regular expressions case sensitivity is inherited from global regular expression settings. For the purpose of regexp matching, float values will always be represented with 4 decimal digits after '.'. Also note that for large numbers difference in decimal (stored in database) and binary (used by Zabbix server) representation may affect the 4th decimal digit.

Examples:

```default
count(max_foreach(/*/net.if.in[*],1h)) #calculate the number of net.if.in items that received data in the last hour until now
count(last_foreach(/*/vfs.fs.size[*,pused]),"gt",95) #calculate the number of file systems with over 95% of disk space used
```

[comment]: # ({/4520f3ef-3c498650})

[comment]: # ({3ba37963-f3ad7158})

##### histogram_quantile(quantile,bucket1,value1,bucket2,value2,...) {#histogram-quantile}

Calculates the φ-quantile from the buckets of a histogram.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *bucket_rate_foreach*.

Parameters: 

-   **quantile** - 0 ≤ φ ≤ 1;<br>
-   **bucketN, valueN** - manually entered pairs (>=2) of parameters or the response of [bucket_rate_foreach](/manual/config/triggers/expression/aggregate/foreach).

Comments:

-   Supported only in calculated items;
-   Functionally corresponds to '[histogram\_quantile](https://prometheus.io/docs/prometheus/latest/querying/functions/#histogram-quantile)' of PromQL;
-   Returns -1 if values of the last 'Infinity' bucket (*"+inf"*) are equal to 0.

Examples:

```default
histogram_quantile(0.75,1.0,last(/host/rate_bucket[1.0]),"+Inf",last(/host/rate_bucket[Inf]))
histogram_quantile(0.5,bucket_rate_foreach(//item_key,30s))
```

[comment]: # ({/3ba37963-f3ad7158})

[comment]: # ({b14d0146-c8e3133a})

##### item_count(item filter) {#item-count}

The count of existing items in configuration that match the filter criteria.<br>
Supported value type: *Integer*.

Parameter: 

-   **item filter** - criteria for item selection, allows referencing by host group, host, item key, and tags. Wildcards are supported. See [item filter](/manual/config/triggers/expression/aggregate/foreach#item-filter-syntax) for more details.<br>

Comments:

-   Supported only in calculated items;
-   Works as an alias for the *count(exists_foreach(item_filter))* function.

Examples:

```default
item_count(/*/agent.ping?[group="Host group 1"]) #calculate the number of hosts with the agent.ping item in "Host group 1"
```

[comment]: # ({/b14d0146-c8e3133a})

[comment]: # ({356d9069-88a54099})

##### kurtosis(/host/key,(sec|#num)<:time shift>) {#kurtosis}

The "tailedness" of the probability distribution in collected values within the defined evaluation period. See also: [Kurtosis](https://en.wikipedia.org/wiki/Kurtosis).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
kurtosis(/host/system.cpu.util[,user],5m)>5 #trigger on sharp spikes of CPU utilization over 5 minutes
```

[comment]: # ({/356d9069-88a54099})

[comment]: # ({98a81503-bfb43a27})

##### mad(/host/key,(sec|#num)<:time shift>) {#mad}

The median absolute deviation in collected values within the defined evaluation period. See also: [Median absolute deviation](https://en.wikipedia.org/wiki/Median_absolute_deviation).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
last(/host/system.cpu.util[,user])>avg(/host/system.cpu.util[,user],1h)+3*mad(/host/system.cpu.util[,user],1h) #trigger if the last CPU utilization value is statistically significant
```

[comment]: # ({/98a81503-bfb43a27})

[comment]: # ({e93a3513-5882010b})

##### max(/host/key,(sec|#num)<:time shift>) {#max}

The highest value of an item within the defined evaluation period.<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach functions](/manual/config/triggers/expression/aggregate/foreach): *avg_foreach*, *count_foreach*, *exists_foreach*, *last_foreach*, *max_foreach*, *min_foreach*, *sum_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
max(/host/key,1h) - min(/host/key,1h) #calculate the difference between the maximum and minimum values within the last hour until now (the delta of values)
max(last_foreach(/*/vfs.fs.size[*,pused]?[group="Linux servers"])) #return the highest disk usage across all Linux servers
```

[comment]: # ({/e93a3513-5882010b})

[comment]: # ({cfe7b652-ffd1e499})

##### min(/host/key,(sec|#num)<:time shift>) {#min}

The lowest value of an item within the defined evaluation period.<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach functions](/manual/config/triggers/expression/aggregate/foreach): *avg_foreach*, *count_foreach*, *exists_foreach*, *last_foreach*, *max_foreach*, *min_foreach*, *sum_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
max(/host/key,1h) - min(/host/key,1h) #calculate the difference between the maximum and minimum values within the last hour until now (the delta of values)
min(last_foreach(/*/vfs.file.contents["/sys/class/net/enp0s3/operstate"]?[group="Linux servers"])) #return the minimum operational state for any interface across all Linux servers
```

[comment]: # ({/cfe7b652-ffd1e499})

[comment]: # ({f9d7543b-6b6fb273})

##### skewness(/host/key,(sec|#num)<:time shift>) {#skewness}

The asymmetry of the probability distribution in collected values within the defined evaluation period. See also: [Skewness](https://en.wikipedia.org/wiki/Skewness).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
skewness(/host/vm.memory.size[used],5m)<-20 #trigger on sudden negative drops indicating crashes/restarts
```

[comment]: # ({/f9d7543b-6b6fb273})

[comment]: # ({7e32d94e-11c2ea25})

##### stddevpop(/host/key,(sec|#num)<:time shift>) {#stddevpop}

The population standard deviation in collected values within the defined evaluation period. See also: [Standard deviation](https://en.wikipedia.org/wiki/Standard_deviation).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
stddevpop(/host/system.cpu.util[,user],10m)>7 #trigger if CPU usage fluctuates heavily (population standard deviation is above 7 over 10 minutes)
```

[comment]: # ({/7e32d94e-11c2ea25})

[comment]: # ({23ca7fe4-1db77c44})

##### stddevsamp(/host/key,(sec|#num)<:time shift>) {#stddevsamp}

The sample standard deviation in collected values within the defined evaluation period. See also: [Standard deviation](https://en.wikipedia.org/wiki/Standard_deviation).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

At least two data values are required for this function to work.

Examples:

```default
stddevsamp(/host/system.cpu.util[,user],10m)>7 #trigger if CPU usage fluctuates heavily (sample standard deviation is above 7 over 10 minutes)
```

[comment]: # ({/23ca7fe4-1db77c44})

[comment]: # ({89b5406f-0ecf79eb})

##### sum(/host/key,(sec|#num)<:time shift>) {#sum}

The sum of collected values within the defined evaluation period.<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach functions](/manual/config/triggers/expression/aggregate/foreach): *avg_foreach*, *count_foreach*, *exists_foreach*, *last_foreach*, *max_foreach*, *min_foreach*, *sum_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
sum(last_foreach(/*/net.if.in[*]?[group="Linux servers"])) #calculate the total incoming network traffic for all Linux servers
sum(last_foreach(/*/vfs.fs.size[/,total]?[group="MySQL Servers"])) #calculate the total disk space for all MySQL servers
sum(last_foreach(/*/net.dns[*,*,*])) #calculate the total number of successful DNS checks
```

[comment]: # ({/89b5406f-0ecf79eb})

[comment]: # ({907627c8-6f6556f2})

##### sumofsquares(/host/key,(sec|#num)<:time shift>) {#sumofsquares}

The sum of squares in collected values within the defined evaluation period.<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
sumofsquares(/host/calculated.net.if.rate,1m) #the sum of squares for the network traffic rate (incoming vs outgoing)
sumofsquares(last_foreach(/*/net.if.in[*]?[group="Linux servers"])) #the sum of squares for latest incoming network traffic values across all Linux servers
```

[comment]: # ({/907627c8-6f6556f2})

[comment]: # ({04d271f7-d299bd33})

##### varpop(/host/key,(sec|#num)<:time shift>) {#varpop}

The population variance of collected values within the defined evaluation period. See also: [Variance](https://en.wikipedia.org/wiki/Variance).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

Examples:

```default
varpop(/host/system.cpu.util[,user],10m)>50 #trigger if CPU usage fluctuates heavily (variance is above 50 over 10 minutes)
```

[comment]: # ({/04d271f7-d299bd33})

[comment]: # ({9c60c2c9-b1bc041c})

##### varsamp(/host/key,(sec|#num)<:time shift>) {#varsamp}

The sample variance of collected values within the defined evaluation period. See also: [Variance](https://en.wikipedia.org/wiki/Variance).<br>
Supported value types: *Float*, *Integer*.<br>
Supported [foreach function](/manual/config/triggers/expression/aggregate/foreach): *last_foreach*.

Parameters: see [common parameters](#common-parameters).

At least two data values are required for this function to work.

Examples:

```default
varsamp(/host/system.cpu.util[,user],10m)>50 #trigger if CPU usage fluctuates heavily (sample variance is above 50 over 10 minutes)
```

[comment]: # ({/9c60c2c9-b1bc041c})

[comment]: # ({ba58f5e4-541616fc})

See [all supported functions](/manual/config/triggers/expression#functions).

[comment]: # ({/ba58f5e4-541616fc})