[comment]: # ({6537e63f-6537e63f})
# 1 Foreach funkcijas

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

[comment]: # ({5f3bebe2-7d50e3a2})
### Pārskats

Foreach funkcijas tiek izmantotas [agregētajos aprēķinos](/manual/config/items/itemtypes/calculated/aggregate), lai atgrieztu vienu agregēto vērtību katram vienumam, kas ir atlasīts, izmantojot **vienumu filtru**.
Tiek atgriezts vērtību masīvs.

::: noteimportant
Foreach funkcijas tiek atbalstītas tikai [aprēķinātajos vienumos](/manual/config/items/itemtypes/calculated) kā daļa no agregētā aprēķina formulām.
Tās nevar izsaukt parastās vienumu atslēgās vai trigeru izteiksmēs ārpus šī konteksta.
:::

Piemēram, funkcija `avg_foreach` atgriezīs vērtību masīvu, kur katra vērtība ir atlasītā vienuma vēstures vērtību *vidējā* vērtība norādītajā laika intervālā.

[Vienumu filtrs](#item-filter-syntax) ir daļa no sintakses, ko izmanto foreach funkcijas.
Vienumu filtrā tiek atbalstīti aizstājējzīmes, tādēļ nepieciešamos vienumus var atlasīt ļoti elastīgi.

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

[comment]: # ({1e055e7c-c9e1960d})
### Atbalstītās funkcijas

|Function|Description|
|--|--------|
|*avg_foreach*|Atgriež katra vienuma vidējo vērtību.|
|*bucket_rate_foreach*|Atgriež pārus (bucket augšējā robeža, ātruma vērtība), kas ir piemēroti lietošanai [histogram\_quantile()](/manual/appendix/functions/aggregate#histogram-quantile) funkcijā, kur "bucket augšējā robeža" ir vienuma atslēgas parametra vērtība, kas definēta ar <parameter number> [parametru](#additional-parameters).|
|*count_foreach*|Atgriež vērtību skaitu katram vienumam.|
|*exists_foreach*|Atgriež '1' katram iespējotajam vienumam.|
|*last_foreach*|Atgriež pēdējo vērtību katram vienumam.|
|*max_foreach*|Atgriež maksimālo vērtību katram vienumam.|
|*min_foreach*|Atgriež minimālo vērtību katram vienumam.|
|*sum_foreach*|Atgriež vērtību summu katram vienumam.|

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

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

Foreach funkcijas atbalsta divus kopīgus parametrus: `vienuma filtrs` (skatiet detalizētu informāciju tālāk) un `laika periods`:

    foreach_function(item filter,time period)

Piemēram: 

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

atgriezīs katra vienuma 'mysql.qps' piecu minūšu vidējo vērtību MySQL serveru grupā.

Ņemiet vērā, ka dažas funkcijas atbalsta papildu [parametrus](#additional-parameters).

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

[comment]: # ({f8b1fa52-737d2e38})
#### Vienumu filtra sintakse

Vienumu filtrs:

    /host/key[parameters]?[conditions]

sastāv no četrām daļām, kur:

*   host - hosta nosaukums
*   key - vienuma atslēga (bez parametriem)
*   parameters - vienuma atslēgas parametri
*   conditions - uz hostu grupu un/vai vienuma tagu balstīti nosacījumi (izteiksmes veidā)

Atstarpes ir atļautas tikai nosacījumu izteiksmē.

**Aizstājējzīmju lietošana**

*   Aizstājējzīmi var izmantot, lai aizstātu hosta nosaukumu, vienuma atslēgu vai atsevišķu vienuma atslēgas parametru.
*   Vai nu hostam, vai vienuma atslēgai jābūt norādītai bez aizstājējzīmes. Tātad `/host/*` un `/*/key` ir derīgi filtri, bet `/*/*` ir nederīgs.
*   Aizstājējzīmi nevar izmantot hosta nosaukuma, vienuma atslēgas vai vienuma atslēgas parametra *daļai*.
*   Aizstājējzīme neatbilst vairāk nekā vienam vienuma atslēgas parametram. Tāpēc aizstājējzīme jānorāda katram parametram atsevišķi (t.i., `key[abc,*,*]`).

**Nosacījumu izteiksme**

Nosacījumu izteiksme atbalsta:

*   operandus:
    *   group - hostu grupa
    *   tag - vienuma tags
    *   `"<text>"` - virknes konstante ar `\` atsoļa rakstzīmi, lai atsoļotu `"` un `\`
*   reģistrjutīgus virkņu salīdzināšanas operatorus: `=`, `<>`
*   loģiskos operatorus: `and`, `or`, `not`
*   grupēšanu ar iekavām: `(` `)`

Virkņu konstanšu pēdiņas ir obligātas. Tiek atbalstīta tikai pilnas virknes salīdzināšana ar reģistrjutību.

:::notewarning
Norādot tagus filtrā (t.i. `tag="tagname:value"`), kols ":" tiek izmantots kā atdalītājs. 
Viss pēc tā tiek uzskatīts par taga vērtību. Tādēļ pašlaik netiek atbalstīta tāda taga nosaukuma norādīšana, kas satur ":".
:::

**Piemēri**

Var izmantot sarežģītu filtru, atsaucoties uz vienuma atslēgu, hostu grupu un tagiem, kā parādīts piemēros:

|Sintakses piemērs|Apraksts|
|--|--|
|`/host/key[abc,*]`|Atbilst līdzīgiem vienumiem šajā hostā.|
|`/*/key`|Atbilst vienam un tam pašam vienumam jebkurā hostā.|
|`/*/key?[group="ABC" and tag="tagname:value"]`|Atbilst vienam un tam pašam vienumam jebkurā hostā no ABC grupas ar tagiem 'tagname:value'.|
|`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|Atbilst līdzīgiem vienumiem jebkurā hostā no ABC vai DEF grupas ar attiecīgajiem tagiem.|

Visiem norādītajiem vienumiem jāeksistē un jāvāc dati.
Aprēķinos tiek iekļauti tikai iespējoti vienumi iespējotos hostos.
Vienumi neatbalstītā stāvoklī netiek iekļauti.

::: noteimportant
Ja atsauktā vienuma atslēga tiek mainīta, filtrs ir jāatjaunina manuāli.
:::

Norādot vecākgrupas hostu grupu, tiek iekļauta vecākgrupa un visas ligzdotās hostu grupas ar to vienumiem.

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

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

**Otrais** parametrs ļauj norādīt laika periodu agregācijai.
Laika periodu var izteikt tikai kā laiku; vērtību skaits (ar prefiksu **\#**) netiek atbalstīts.

Ērtības labad šajā parametrā var izmantot [atbalstītos vienību simbolus](/manual/appendix/suffixes),
piemēram, '5m' (piecas minūtes) '300s' (300 sekundes) vietā vai '1d' (viena diena) '86400' (86400 sekundes) vietā.

Funkcijai *last\_foreach* laika periods ir neobligāts parametrs (atbalstīts kopš Zabbix 7.0), kuru var izlaist:

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

Laika periods netiek atbalstīts ar funkciju *exists\_foreach*.

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

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

**bucket\_rate\_foreach**

Funkcija *bucket\_rate\_foreach* atbalsta trešo neobligāto parametru:

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

kur <parameter number> ir "bucket" vērtības pozīcija vienuma atslēgā.
Piemēram, ja "bucket" vērtība myItem\[aaa,0.2\] ir '0.2', tad tās pozīcija ir 2.

Noklusējuma vērtība <parameter number> ir '1'.

**count\_foreach**

Funkcija *count\_foreach* atbalsta trešo un ceturto neobligāto parametru:

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

Kur:

-   **operator** ir nosacījuma operators vienuma vērtībām (jābūt dubultpēdiņās). Atbalstītie `operators`:<br>*eq* - vienāds<br>*ne* - nav vienāds<br>*gt* - lielāks<br>*ge* - lielāks vai vienāds<br>*lt* - mazāks<br>*le* - mazāks vai vienāds<br>*like* - atbilst, ja satur šablonu (reģistrjutīgs)<br>*bitand* - bitu AND<br>*regexp* - reģistrjutīga atbilstība regulārajai izteiksmei, kas norādīta `pattern`<br>*iregexp* - reģistrnejutīga atbilstība regulārajai izteiksmei, kas norādīta `pattern`<br>
-   **pattern** ir obligātais šablons (virknes argumentiem jābūt dubultpēdiņās); tiek atbalstīts, ja *operator* ir norādīts trešajā parametrā.

Komentāri:

-   Neobligātos parametrus *operator* vai *pattern* nevar atstāt tukšus aiz komata, tos var tikai pilnībā izlaist.
-   Ja kā trešais parametrs ir *bitand*, ceturto `pattern` parametru var norādīt kā divus skaitļus, kas atdalīti ar '/': **number_to_compare_with/mask**. count\_foreach() aprēķina "bitwise AND" no vērtības un *mask* un salīdzina rezultātu ar *number_to_compare_with*. Ja "bitwise AND" rezultāts ir vienāds ar *number_to_compare_with*, vērtība tiek ieskaitīta.<br>Ja *number_to_compare_with* un *mask* ir vienādi, var norādīt tikai *mask* (bez '/').
-   Ja kā trešais parametrs ir *regexp* vai *iregexp*, ceturtais `pattern` parametrs var būt parasta vai [globāla](/manual/regular_expressions#global-regular-expressions) (sākas ar '@') regulārā izteiksme. Globālo regulāro izteiksmju gadījumā reģistrjutība tiek pārmantota no globālās regulārās izteiksmes iestatījumiem. Regexp atbilstības vajadzībām peldošā komata vērtības vienmēr tiks attēlotas ar 4 zīmēm aiz '.'. Ņemiet vērā arī to, ka lieliem skaitļiem atšķirība starp decimālo (glabājas datubāzē) un bināro (izmanto Zabbix serveris) attēlojumu var ietekmēt 4. zīmi aiz komata.

Plašāku informāciju un piemērus par foreach funkciju izmantošanu skatiet sadaļā [aggregate calculations](/manual/config/items/itemtypes/calculated/aggregate).

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

[comment]: # ({fc23e115-328844f6})
#### Darbība atkarībā no pieejamības

Tālāk esošā tabula parāda, kā katra funkcija darbojas ierobežotas hosta/vienuma un vēstures datu pieejamības gadījumos.

|Function|Disabled host|Unavailable host with data|Unavailable host without data|Disabled item|Unsupported item|Data retrieval error (SQL)|
|--|--|--|--|--|--|--|
|*avg_foreach*|ignorēt|atgriezt vidējo|ignorēt|ignorēt|ignorēt|ignorēt|
|*bucket_rate_foreach*|ignorēt|atgriezt bucket rate|ignorēt|ignorēt|ignorēt|ignorēt|
|*count_foreach*|ignorēt|atgriezt skaitu|0|ignorēt|ignorēt|ignorēt|
|*exists_foreach*|ignorēt|1|1|ignorēt|1|n/a|
|*last_foreach*|ignorēt|atgriezt pēdējo vērtību|ignorēt|ignorēt|ignorēt|ignorēt|
|*max_foreach*|ignorēt|atgriezt maksimumu|ignorēt|ignorēt|ignorēt|ignorēt|
|*min_foreach*|ignorēt|atgriezt minimumu|ignorēt|ignorēt|ignorēt|ignorēt|
|*sum_foreach*|ignorēt|atgriezt summu|ignorēt|ignorēt|ignorēt|ignorēt|

Ja vienums tiek *ignorēts*, agregācijai nekas netiek pievienots.

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