[comment]: # ({6537e63f-6537e63f})
# 1 Funkcje foreach

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

[comment]: # ({5f3bebe2-7d50e3a2})
### Przegląd

Funkcje foreach są używane w [obliczeniach agregujących](/manual/config/items/itemtypes/calculated/aggregate) do zwracania jednej wartości agregowanej dla każdej pozycji wybranej przez użyty **filtr pozycji**.
Zwracana jest tablica wartości.

::: noteimportant
Funkcje foreach są obsługiwane tylko w [pozycjach obliczanych](/manual/config/items/itemtypes/calculated) jako część formuł obliczeń agregujących.
Nie można ich wywoływać w zwykłych kluczach pozycji ani w wyzwalaczach poza tym kontekstem.
:::

Na przykład funkcja `avg_foreach` zwróci tablicę wartości, gdzie każda wartość jest *średnią* wartością historyczną wybranej pozycji w określonym przedziale czasu.

[Filtr pozycji](#item-filter-syntax) jest częścią składni używanej przez funkcje foreach.
W filtrze pozycji obsługiwane są symbole wieloznaczne, dzięki czemu wymagane pozycje można wybierać bardzo elastycznie.

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

[comment]: # ({1e055e7c-c9e1960d})
### Obsługiwane funkcje

|Function|Description|
|--|--------|
|*avg_foreach*|Zwraca średnią wartość dla każdej pozycji.|
|*bucket_rate_foreach*|Zwraca pary (górna granica kubełka, wartość szybkości) odpowiednie do użycia w funkcji [histogram\_quantile()](/manual/appendix/functions/aggregate#histogram-quantile), gdzie "górna granica kubełka" jest wartością parametru klucza pozycji zdefiniowaną przez [parametr](#additional-parameters) <parameter number>.|
|*count_foreach*|Zwraca liczbę wartości dla każdej pozycji.|
|*exists_foreach*|Zwraca '1' dla każdej włączonej pozycji.|
|*last_foreach*|Zwraca ostatnią wartość dla każdej pozycji.|
|*max_foreach*|Zwraca maksymalną wartość dla każdej pozycji.|
|*min_foreach*|Zwraca minimalną wartość dla każdej pozycji.|
|*sum_foreach*|Zwraca sumę wartości dla każdej pozycji.|

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

[comment]: # ({a8e9955e-2cf639a9})
### Składnia funkcji

Funkcje foreach obsługują dwa wspólne parametry: `filtr pozycji` (szczegóły poniżej) oraz `okres czasu`:

    foreach_function(item filter,time period)

Na przykład: 

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

zwróci pięciominutową średnią dla każdej pozycji „mysql.qps” w grupie serwerów MySQL.

Należy pamiętać, że niektóre funkcje obsługują dodatkowe [parametry](#additional-parameters).

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

[comment]: # ({f8b1fa52-737d2e38})
#### Składnia filtra pozycji

Filtr pozycji:

    /host/key[parameters]?[conditions]

składa się z czterech części, gdzie:

*   host - nazwa hosta
*   key - klucz pozycji (bez parametrów)
*   parameters - parametry klucza pozycji
*   conditions - warunki oparte na grupie hostów i/lub tagach pozycji (w postaci wyrażenia)

Spacje są dozwolone wyłącznie wewnątrz wyrażenia warunków.

**Użycie symbolu wieloznacznego**

*   Symbol wieloznaczny może być użyty do zastąpienia nazwy hosta, klucza pozycji lub pojedynczego parametru klucza pozycji.
*   Albo host, albo klucz pozycji musi być określony bez symbolu wieloznacznego. Dlatego `/host/*` i `/*/key` są poprawnymi filtrami, ale `/*/*` jest nieprawidłowy.
*   Symbol wieloznaczny nie może być użyty dla *części* nazwy hosta, klucza pozycji ani parametru klucza pozycji.
*   Symbol wieloznaczny nie dopasowuje więcej niż jednego parametru klucza pozycji. Dlatego symbol wieloznaczny musi być określony osobno dla każdego parametru (tj. `key[abc,*,*]`).

**Wyrażenie warunków**

Wyrażenie warunków obsługuje:

*   operandy:
    *   group - grupa hostów
    *   tag - tag pozycji
    *   `"<text>"` - stała tekstowa, ze znakiem ucieczki `\` do poprzedzania `"` i `\`
*   operatory porównania ciągów znaków z rozróżnianiem wielkości liter: `=`, `<>`
*   operatory logiczne: `and`, `or`, `not`
*   grupowanie za pomocą nawiasów: `(` `)`

Ujęcie stałych tekstowych w cudzysłów jest obowiązkowe. Obsługiwane jest tylko pełne porównanie ciągów znaków z rozróżnianiem wielkości liter.

:::notewarning
Podczas określania tagów w filtrze (tj. `tag="tagname:value"`), dwukropek ":" jest używany jako separator. 
Wszystko po nim jest traktowane jako wartość tagu. Dlatego obecnie nie jest obsługiwane określanie nazwy tagu zawierającej ":".
:::

**Przykłady**

Można użyć złożonego filtra odwołującego się do klucza pozycji, grupy hostów i tagów, co ilustrują poniższe przykłady:

|Przykład składni|Opis|
|--|--|
|`/host/key[abc,*]`|Dopasowuje podobne pozycje na tym hoście.|
|`/*/key`|Dopasowuje tę samą pozycję dowolnego hosta.|
|`/*/key?[group="ABC" and tag="tagname:value"]`|Dopasowuje tę samą pozycję dowolnego hosta z grupy ABC mającego tagi 'tagname:value'.|
|`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Dopasowuje podobne pozycje dowolnego hosta z grupy ABC lub DEF z odpowiednimi tagami.|

Wszystkie pozycje, do których istnieją odwołania, muszą istnieć i zbierać dane.
W obliczeniach uwzględniane są tylko włączone pozycje na włączonych hostach.
Pozycje w stanie nieobsługiwanym nie są uwzględniane.

::: noteimportant
Jeśli klucz pozycji, do której istnieje odwołanie, zostanie zmieniony, filtr musi zostać zaktualizowany ręcznie.
:::

Określenie nadrzędnej grupy hostów obejmuje grupę nadrzędną oraz wszystkie zagnieżdżone grupy hostów wraz z ich pozycjami.

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

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

Drugi parametr pozwala określić okres czasu dla agregacji.
Okres czasu może być wyrażony wyłącznie jako czas; liczba wartości (poprzedzona prefiksem **\#**) nie jest obsługiwana.

Dla wygody w tym parametrze można używać [obsługiwanych symboli jednostek](/manual/appendix/suffixes),
na przykład „5m” (pięć minut) zamiast „300s” (300 sekund) lub „1d” (jeden dzień) zamiast „86400” (86400 sekund).

W przypadku funkcji *last\_foreach* okres czasu jest parametrem opcjonalnym (obsługiwanym od Zabbix 7.0), który można pominąć:

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

Okres czasu nie jest obsługiwany przez funkcję *exists\_foreach*.

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

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

**bucket\_rate\_foreach**

Trzeci opcjonalny parametr jest obsługiwany przez funkcję *bucket\_rate\_foreach*:

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

gdzie <parameter number> to pozycja wartości „bucket” w kluczu pozycji.
Na przykład, jeśli wartość „bucket” w myItem\[aaa,0.2\] to „0.2”, to jej pozycja wynosi 2.

Domyślna wartość <parameter number> to „1”.

**count\_foreach**

Trzeci i czwarty opcjonalny parametr są obsługiwane przez funkcję *count\_foreach*:

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

Gdzie:

-   **operator** to operator warunkowy dla wartości pozycji (musi być ujęty w podwójny cudzysłów). Obsługiwane `operators`:<br>*eq* - równe<br>*ne* - nierówne<br>*gt* - większe<br>*ge* - większe lub równe<br>*lt* - mniejsze<br>*le* - mniejsze lub równe<br>*like* - pasuje, jeśli zawiera wzorzec (z uwzględnieniem wielkości liter)<br>*bitand* - bitowe AND<br>*regexp* - dopasowanie z uwzględnieniem wielkości liter do wyrażenia regularnego podanego w `pattern`<br>*iregexp* - dopasowanie bez uwzględniania wielkości liter do wyrażenia regularnego podanego w `pattern`<br>
-   **pattern** to wymagany wzorzec (argumenty tekstowe muszą być ujęte w podwójny cudzysłów); obsługiwany, jeśli *operator* jest określony w trzecim parametrze.

Uwagi:

-   Opcjonalne parametry *operator* lub *pattern* nie mogą być pozostawione puste po przecinku, mogą być tylko całkowicie pominięte.
-   Gdy *bitand* jest użyty jako trzeci parametr, czwarty parametr `pattern` może być określony jako dwie liczby rozdzielone znakiem '/': **number_to_compare_with/mask**. count\_foreach() oblicza „bitowe AND” z wartości i *mask* oraz porównuje wynik z *number_to_compare_with*. Jeśli wynik „bitowego AND” jest równy *number_to_compare_with*, wartość jest zliczana.<br>Jeśli *number_to_compare_with* i *mask* są równe, wystarczy podać tylko *mask* (bez '/').
-   Gdy *regexp* lub *iregexp* jest użyty jako trzeci parametr, czwarty parametr `pattern` może być zwykłym lub [globalnym](/manual/regular_expressions#global-regular-expressions) (zaczynającym się od '@') wyrażeniem regularnym. W przypadku globalnych wyrażeń regularnych rozróżnianie wielkości liter jest dziedziczone z ustawień globalnych wyrażeń regularnych. Na potrzeby dopasowania regexp wartości zmiennoprzecinkowe będą zawsze przedstawiane z 4 cyframi dziesiętnymi po '.'. Należy również pamiętać, że w przypadku dużych liczb różnica między reprezentacją dziesiętną (przechowywaną w bazie danych) a binarną (używaną przez serwer Zabbix) może wpływać na 4. cyfrę dziesiętną.

Więcej szczegółów i przykładów użycia funkcji foreach można znaleźć w sekcji [obliczenia agregowane](/manual/config/items/itemtypes/calculated/aggregate).

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

[comment]: # ({fc23e115-328844f6})
#### Zachowanie zależne od dostępności

Poniższa tabela ilustruje, jak każda funkcja zachowuje się w przypadkach ograniczonej dostępności hosta/pozycji oraz danych historycznych.

|Function|Disabled host|Unavailable host with data|Unavailable host without data|Disabled item|Unsupported item|Data retrieval error (SQL)|
|--|--|--|--|--|--|--|
|*avg_foreach*|ignoruj|zwróć średnią|ignoruj|ignoruj|ignoruj|ignoruj|
|*bucket_rate_foreach*|ignoruj|zwróć bucket rate|ignoruj|ignoruj|ignoruj|ignoruj|
|*count_foreach*|ignoruj|zwróć liczbę|0|ignoruj|ignoruj|ignoruj|
|*exists_foreach*|ignoruj|1|1|ignoruj|1|n/d|
|*last_foreach*|ignoruj|zwróć ostatnią wartość|ignoruj|ignoruj|ignoruj|ignoruj|
|*max_foreach*|ignoruj|zwróć maksimum|ignoruj|ignoruj|ignoruj|ignoruj|
|*min_foreach*|ignoruj|zwróć minimum|ignoruj|ignoruj|ignoruj|ignoruj|
|*sum_foreach*|ignoruj|zwróć sumę|ignoruj|ignoruj|ignoruj|ignoruj|

Jeśli pozycja jest *ignorowana*, nic nie jest dodawane do agregacji.

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