[comment]: # ({6537e63f-6537e63f})
# 1. Функции foreach

[comment]: # ({/6537e63f-6537e63f})

[comment]: # ({5f3bebe2-7d50e3a2})
### Обзор

Функции foreach используются в [агрегатных вычислениях](/manual/config/items/itemtypes/calculated/aggregate) для возврата одного агрегированного значения для каждого элемента данных, который выбран с помощью используемого **фильтра элементов данных**.
Возвращается массив значений.

::: noteimportant
Функции foreach поддерживаются только в [вычисляемых элементах данных](/manual/config/items/itemtypes/calculated) как часть формул агрегатных вычислений.
Их нельзя вызывать в обычных ключах элементов данных или выражениях триггеров вне этого контекста.
:::

Например, функция `avg_foreach` вернет массив значений, где каждое значение — это *среднее* значение истории выбранного элемента данных за указанный временной интервал.

[Фильтр элементов данных](#item-filter-syntax) является частью синтаксиса, используемого функциями foreach.
В фильтре элементов данных поддерживается использование подстановочных знаков, поэтому необходимые элементы можно выбирать весьма гибко.

[comment]: # ({/5f3bebe2-7d50e3a2})

[comment]: # ({1e055e7c-c9e1960d})
### Поддерживаемые функции

|Функция|Описание|
|--|--------|
|*avg_foreach*|Возвращает среднее значение для каждого элемента данных.|
|*bucket_rate_foreach*|Возвращает пары (верхняя граница разряда, значение доли), подходящие для использования в функции [histogram\_quantile()](/manual/appendix/functions/aggregate#histogram-quantile), где значение «верхняя граница разряда» — это значение параметра ключа элемента данных, определённого [параметром](#дополнительные-параметры) <номер параметра>.|
|*count_foreach*|Возвращает количество значений для каждого элемента данных.|
|*exists_foreach*|Возвращает «1» для каждого активированного элемента данных.|
|*last_foreach*|Возвращает последнее значение для каждого элемента данных.|
|*max_foreach*|Возвращает наибольшее значение для каждого элемента данных.|
|*min_foreach*|Возвращает наименьшее значение для каждого элемента данных.|
|*sum_foreach*|Возвращает сумму значений для каждого элемента данных.|

[comment]: # ({/1e055e7c-c9e1960d})

[comment]: # ({a8e9955e-2cf639a9})
### Синтаксис функции

Функции foreach поддерживают два общих параметра: `item filter` (подробности см. ниже) и `time period`:

```default
foreach_function(item filter,time period)
```

Например:

`avg_foreach(/*/mysql.qps?[group="MySQL Servers"],5m)`

вернет среднее значение за пять минут для каждого элемента данных `mysql.qps` в группе узлов сети MySQL.

Обратите внимание, что некоторые функции поддерживают дополнительные [параметры](#additional-parameters).

[comment]: # ({/a8e9955e-2cf639a9})

[comment]: # ({f8b1fa52-737d2e38})
#### Синтаксис фильтра элементов данных

Фильтр элементов данных:

```default
/host/key[parameters]?[conditions]
```

состоит из четырех частей, где:<br>
`host` - имя узла сети;<br>
`key` - ключ элемента данных (без параметров);<br>
`parameters` - параметры ключа элемента данных;<br>
`conditions` - условия на основе группы узлов сети и/или тега элемента данных (в виде выражения).<br>

Пробелы допускаются только внутри выражения условий.

**Использование подстановочного знака**

-   Подстановочный знак можно использовать для замены имени узла сети, ключа элемента данных или отдельного параметра ключа элемента данных.
-   Либо узел сети, либо ключ элемента данных должны быть указаны без подстановочного знака.
Поэтому `/host/*` и `/*/key` являются допустимыми фильтрами, а `/*/*` - недопустимым.
-   Подстановочный знак нельзя использовать для *части* имени узла сети, ключа элемента данных, параметра ключа элемента данных.
-   Подстановочный знак не сопоставляется более чем с одним параметром ключа элемента данных.
Поэтому для каждого параметра подстановочный знак должен указываться отдельно (то есть `key[abc,*,*]`).

**Выражение условий**

Выражение условий поддерживает:

-   Операнды:<br>
**group** - группа узлов сети;<br>
**tag** - тег элемента данных;<br>
`"<text>"` - строковая константа, с использованием escape-символа `\` для экранирования `"` и `\`.
-   Операторы сравнения строк с учетом регистра: `=`, `<>`
-   Логические операторы: `and`, `or`, `not`
-   Группировку с помощью круглых скобок: `(` `)`

Кавычки для строковых констант обязательны.
Поддерживается только полное строковое сравнение с учетом регистра.

:::notewarning
При указании тегов в фильтре (то есть `tag="tagname:value"`) двоеточие ":" используется в качестве разделителя.
Все, что следует после него, считается значением тега.
Поэтому в настоящее время не поддерживается указание имени тега, содержащего ":".
:::

**Примеры**

Сложный фильтр может использоваться для ссылки на ключ элемента данных, группу узлов сети и теги, как показано в примерах:

|Syntax example|Description|
|--|--|
|`/host/key[abc,*]`|Соответствует похожим элементам данных на этом узле сети.|
|`/*/key`|Соответствует одному и тому же элементу данных любого узла сети.|
|`/*/key?[group="ABC" and tag="tagname:value"]`|Соответствует одному и тому же элементу данных любого узла сети из группы ABC, имеющему теги 'tagname:value'.|
|`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Соответствует похожим элементам данных любого узла сети из группы ABC или DEF с соответствующими тегами.|

Все указанные элементы данных должны существовать и собирать данные.
В вычисления включаются только включенные элементы данных на включенных узлах сети.
Элементы данных в неподдерживаемом состоянии не включаются.

::: noteimportant
Если ключ элемента данных указанного элемента данных изменен, фильтр необходимо обновить вручную.
:::

Указание родительской группы узлов сети включает родительскую группу и все вложенные группы узлов сети с их элементами данных.

[comment]: # ({/f8b1fa52-737d2e38})

[comment]: # ({2ab7aef7-0a9b9b28})
#### Период времени

**Второй** параметр позволяет указать период времени для агрегации.
Период времени может быть задан только как время; количество значений (с префиксом **\#**) не поддерживается.

Для удобства в этом параметре можно использовать [поддерживаемые символы единиц измерения](/manual/appendix/suffixes), например, `5m` (пять минут) вместо `300s` (300 секунд) или `1d` (один день) вместо `86400` (86400 секунд).

Для функции `last_foreach` период времени является необязательным параметром (поддерживается начиная с Zabbix 7.0) и может быть опущен:

```default
last_foreach(/*/key?[group="host group"])
```

Период времени не поддерживается функцией `exists_foreach`.

[comment]: # ({/2ab7aef7-0a9b9b28})

[comment]: # ({a4d91525-bf880e22})
#### Дополнительные параметры

**bucket\_rate\_foreach**

Функция `bucket_rate_foreach` поддерживает третий необязательный параметр:

```default
bucket_rate_foreach(item filter,time period,<parameter number>)
```

где `<parameter number>` — это позиция значения "bucket" в ключе элемента данных.
Например, если значение "bucket" в `myItem[aaa,0.2]` равно `0.2`, то его позиция — 2.

Значение по умолчанию для <parameter number> — `1`.

**count\_foreach**

Функция `count_foreach` поддерживает третий и четвертый необязательные параметры:

```default
count_foreach(item filter,time period,<operator>,<pattern>)
```

Где:

-   **operator** — условный оператор для значений элементов данных (должен быть в двойных кавычках).
Поддерживаемые `operators`:<br>*eq* - равно<br>*ne* - не равно<br>*gt* - больше<br>*ge* - больше или равно<br>*lt* - меньше<br>*le* - меньше или равно<br>*like* - совпадает, если содержит шаблон (с учетом регистра)<br>*bitand* - побитовое И<br>*regexp* - совпадение с регулярным выражением, заданным в `pattern`, с учетом регистра<br>*iregexp* - совпадение с регулярным выражением, заданным в `pattern`, без учета регистра.<br>
-   **pattern** — требуемый шаблон (строковые аргументы должны быть в двойных кавычках); поддерживается, если в третьем параметре указан *operator*.

Примечания:

-   Необязательные параметры *operator* или *pattern* нельзя оставлять пустыми после запятой, их можно только полностью опустить.
-   При использовании *bitand* в качестве третьего параметра четвертый параметр `pattern` можно указать как два числа, разделенные '/': **number_to_compare_with/mask**. `count_foreach()` вычисляет "побитовое И" для значения и *mask* и сравнивает результат с *number_to_compare_with*.
Если результат "побитового И" равен *number_to_compare_with*, значение учитывается.<br>Если *number_to_compare_with* и *mask* равны, достаточно указать только *mask* (без '/').
-   При использовании *regexp* или *iregexp* в качестве третьего параметра четвертый параметр `pattern` может быть обычным или [глобальным](/manual/regular_expressions#global-regular-expressions) регулярным выражением (начинающимся с '@').
В случае глобальных регулярных выражений чувствительность к регистру наследуется из настроек глобального регулярного выражения.
Для сопоставления regexp значения с плавающей точкой всегда будут представлены с 4 знаками после '.'.
Также обратите внимание, что для больших чисел разница в десятичном (хранимом в базе данных) и двоичном (используемом сервером Zabbix) представлении может повлиять на 4-й десятичный знак.

См. [агрегатные вычисления](/manual/config/items/itemtypes/calculated/aggregate) для получения дополнительных сведений и примеров использования функций foreach.

[comment]: # ({/a4d91525-bf880e22})

[comment]: # ({fc23e115-328844f6})
#### Поведение, зависящее от доступности

Следующая таблица иллюстрирует, как каждая функция ведёт себя в случае ограниченной доступности узла сети / элемента данных и данных истории.

|Функция|Узел сети деактивирован|Узел сети с данными недоступен|Узел сети без данных недоступен|Элемент данных деактивирован|Элемент данных не поддерживается|Ошибка извлечения данных (SQL)|
|--|--|--|--|--|--|--|
|*avg_foreach*|игнорировать|вернуть среднее|игнорировать|игнорировать|игнорировать|игнорировать|
|*bucket_rate_foreach*|игнорировать|вернуть bucket rate|игнорировать|игнорировать|игнорировать|игнорировать|
|*count_foreach*|игнорировать|вернуть количество|0|игнорировать|игнорировать|игнорировать|
|*exists_foreach*|игнорировать|1|1|игнорировать|1|n/a|
|*last_foreach*|игнорировать|вернуть последнее|игнорировать|игнорировать|игнорировать|игнорировать|
|*max_foreach*|игнорировать|вернуть максимум|игнорировать|игнорировать|игнорировать|игнорировать|
|*min_foreach*|игнорировать|вернуть минимум|игнорировать|игнорировать|игнорировать|игнорировать|
|*sum_foreach*|игнорировать|вернуть сумму|игнорировать|игнорировать|игнорировать|игнорировать|

Если для элемента данных указано *игнорировать*, к агрегированию ничего не добавляется.

[comment]: # ({/fc23e115-328844f6})