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

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

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

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

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

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

[comment]: # ({/84d63c3e-7d50e3a2})

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

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

[comment]: # ({/8c48f3cb-c9e1960d})

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

Функции foreach поддерживают два общих параметра: `фильтр_элементов_данных` (подробнее смотрите ниже) и `период_времени`:

    функция_foreach(фильтр_элементов_данных,период_времени)

Например: 

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

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

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

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

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

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

    /узел_сети/ключ[параметры]?[условия]

состоит из четырёх частей, где:

*   узел_сети — имя узла сети
*   ключ — ключ элемента данных (без параметров)
*   параметры — параметры ключа элемента данных
*   условия — условия на основе группы узлов сети и/или тега элемента данных (как выражение)

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

**Использование подстановочных символов**

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

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

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

*   операнды:
    *   group — группа узлов сети
    *   tag — тег элемента данных
    *   `"<текст>"` — строковая константа, с использованием символа обратной косой черты `\` для экранирования символов `"` и `\`
*   операторы чувствительного к регистру сравнения строк: `=`, `<>`
*   логические операторы: `and`, `or`, `not`
*   группировка при помощи круглых скобок: `(` `)`

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

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

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

|Пример синтаксиса|Описание|
|--|--|
|`/узел_сети/ключ[abc,*]`|Соответствует подобным элементам данных на конкретном узле сети.|
|`/*/ключ`|Соответствует одинаковому элементу данных на любом узле сети.|
|`/*/ключ?[group="ABC" and tag="имя_тега:значение"]`|Соответствует тому же элементу данных любого узла сети из группы ABC, имеющему тег «имя_тега:значение».|
|`/*/ключ[a,*,c]?[(group="ABC" and tag="Тег1") or (group="DEF" and (tag="Тег2" or tag="Тег3:значение"))]`|Соответствует подобным элементам данных любого узла сети из групп ABC или DEF с соответствующими тегами.|

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

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

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

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

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

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

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

Период времени игнорируется сервером, если передан для функции *last\_foreach*, и может быть опущен:

    last_foreach(/*/ключ?[group="группа узлов сети"])

Период времени не поддерживается для функции *exists\_foreach*.

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

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

Третий необязательный параметр поддерживается функцией *bucket\_rate\_foreach*:

    bucket_rate_foreach(фильтр_элементов_данных,период_времени,<номер_параметра>)

где <номер_параметра> — это положение значения «разряд» в ключе элемента данных. Например, если в myItem\[aaa,0.2\] значением «разряд» является
«0.2», то его положение — это 2.

Значением по умолчанию для <номера параметра> является «1».

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

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

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

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

|Функция|Узел сети деактивирован|Узел сети с данными недоступен|Узел сети без данных недоступен|Элемент данных деактивирован|Элемент данных не поддерживается|Ошибка извлечения данных (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-22af7980})