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

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

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

foreach関数は、[集計計算](/manual/config/items/itemtypes/calculated/aggregate) で使用され、使用されている **アイテム フィルター** によって選択された各アイテムに対して 1 つの集計値を返します。値の配列が返されます。

たとえば、*avg_foreach* 関数は値の配列を返します。各値は、指定された時間間隔における、選択された項目の *平均* 履歴値です。

[アイテム フィルター構文](#アイテムフィルター構文)は、foreach 関数で使用される構文の一部です。アイテム フィルターではワイルドカードの使用がサポートされているため、必要なアイテムを非常に柔軟に選択できます。

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

[comment]: # ({8c48f3cb-c9e1960d})
#### サポートされている関数

|関数|説明|
|--|--------|
|*avg_foreach*|各項目の平均値を返します|
|*bucket_rate_foreach*|[histogram\_quantile()](/manual/appendix/functions/aggregate#aggregate-functions1)関数での使用に適したペア (バケットの上限、レート値) を返します。ここでの"バケットの上限"は、[パラメーター](#additional_parameters)<parameter number>で定義されたアイテムキーのパラメーターの値です。|
|*count_foreach*|各アイテムの値の数を返します|
|*exists_foreach*|有効なアイテムごとに '1' を返します。|
|*last_foreach*|各アイテムの最新の値を返します|
|*max_foreach*|各アイテムの最大値を返します|
|*min_foreach*|各アイテムの最小値を返します|
|*sum_foreach*|各アイテムの値の合計を返します|

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

[comment]: # ({af871ae4-2cf639a9})
#### 関数構文

Foreach functions support two common parameters: `item filter` (see details below) and `time period`:
Foreach関数は、`item filter` (詳細は下記を参照) と `time period` という 2 つの共通パラメータをサポートしています。

    foreach_function(item filter,time period)

例:

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

MySQL サーバー グループ内の各 'mysql.qps' 項目の 5 分間の平均を返します。

一部の関数では追加の [パラメータ](#追加のパラメータ) がサポートされていることに注意してください。

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

[comment]: # ({6cd46ed7-737d2e38})
##### アイテムフィルター構文

アイテムフィルター:

    /host/key[parameters]?[conditions]

4 つの部分から構成されます:

*   host - ホスト名
*   key - アイテムキー(パラメータなし)
*   parameters - アイテムキーのパラメータ
*   conditions - ホストグループおよび/またはアイテムタグに基づく条件(式として)

スペースは条件式内でのみ許可されます。

**ワイルドカードの使用**

*   ワイルドカードは、ホスト名、アイテムキー、または個々のアイテムキーパラメータを置き換えるために使用できます。
*   ホストまたはアイテムキーのいずれかをワイルドカードなしで指定する必要があります。したがって、`/host/*` および `/*/key` は有効なフィルタですが、`/*/*` は無効です。
*   ワイルドカードは、ホスト名、アイテムキー、アイテムキーパラメータの *一部* には使用できません。
*   ワイルドカードは、1 つ以上のアイテムキーパラメータと一致しません。したがって、ワイルドカードはパラメータごとに分離して指定する必要があります (つまり、`key[abc,*,*]`)。

**条件式**

条件式は以下をサポートします:

*   引数:
    *   group - ホストグループ
    *   tag - iアイテムタグ
    *   `"<text>"` - string constant, with the `\` escape character to escape `"` and `\`
*   大文字と小文字を区別する文字列比較演算子: `=`、`<>`
*   論理演算子: `and`、`or`、`not`
*   括弧によるグループ化: `(` `)`

文字列定数の引用符は必須です。大文字と小文字を区別した完全な文字列比較のみがサポートされています。

:::notewarning
フィルターでタグを指定する場合 (つまり、`tag="tagname:value"`)、コロン ":" が区切り文字として使用されます。
それ以降のすべてがタグ値とみなされます。したがって、現在、":" を含むタグ名の指定はサポートされていません。
:::
  
**例**

次の例に示すように、アイテム キー、ホスト グループ、タグを参照する複雑なフィルターを使用することもできます:

|構文例|説明|
|--|--|
|`/host/key[abc,*]`|指定されたホストの指定されたアイテムキー、アイテムキーのパラメータと一致します。|
|`/*/key`|任意のホストの同じアイテムキーと一致します。|
|`/*/key?[group="ABC" and tag="tagname:value"]`|'tagname:value'タグを持つABCグループの任意のホストの指定されたアイテムキーと一致します。|
|`/*/key[a,*,c]?[(group="ABC" and tag="Tag1") or (group="DEF" and (tag="Tag2" or tag="Tag3:value"))]`|ABCまたはDEFグループのそれぞれ指定されたタグを持つ任意のホストの指定されたアイテムキーと一致させます。|

参照されるすべてのアイテムが存在しデータが収集されている必要があります。有効なホスト上の有効なアイテムのみが計算に含まれます。

::: noteimportant
参照されるアイテムのアイテムキーが変更された場合、フィルターを修正する必要があります。
:::

親ホストグループを指定すると、親グループと、そのアイテムを含むすべてのネストされたホスト グループが含まれます。

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

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

**2 番目の** パラメータを使用すると、集計の期間を指定できます。期間は時間としてのみ表現でき、値の量 (**\#** で始まる) はサポートされていません。

このパラメータでは、[サポートされている単位記号](/manual/appendix/suffixes)を使用できます。たとえば、'300s'(300 秒) の代わりに'5m'(5分)、'86400'(86400秒)の代わりに'1d'(1日)などです。

*last\_foreach* 関数で渡された場合、サーバーは時間を無視するため、省略できます。:

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

*exists\_foreach* 関数では期間はサポートされていません。

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

[comment]: # ({faa900ea-bf880e22})
##### 追加のパラメータ

3番目のオプションパラメータは*bucket\_rate\_foreach*関数でサポートされています:

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

where <parameter number> is the position of the "bucket" value in the item key. For example, if the "bucket" value in myItem\[aaa,0.2\] is '0.2', then its position is 2.
ここで、<parameter number> は、アイテム キー内の"バケット"値の位置です。たとえば、myItem\[aaa,0.2\] 内の"バケット"値が '0.2' の場合、その位置は2です。

<parameter number> のデフォルト値は 1'です。

foreach 関数の使用に関する詳細と例については、[集計計算](/manual/config/items/itemtypes/calculated/aggregate)を参照してください。

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

[comment]: # ({fc23e115-22af7980})
#### 空き状況に応じた動作

次の表は、ホスト/アイテムおよびヒストリデータの可用性が制限されている場合に各関数がどのように動作するかを示しています。

|関数|無効なホスト|データのある利用不可能なホスト|データのない利用不可能なホスト|無効な項目|取得不可のアイテム|データ取得エラー(SQL)|
|--|--|--|--|--|--|--|
|*avg_foreach*|無視|平均値|無視|無視|無視|無視|
|*bucket_rate_foreach*|無視|バケット率|無視|無視|無視|無視|
|*count_foreach*|無視|カウント数|0|無視|無視|無視|
|*exists_foreach*|無視|1|1|無視|1|n/a|
|*last_foreach*|無視|最新値|無視|無視|無視|無視|
|*max_foreach*|無視|最大値|無視|無視|無視|無視|
|*min_foreach*|無視|最小値|無視|無視|無視|無視|
|*sum_foreach*|無視|合計値|無視|無視|無視|無視|

アイテムが*無視*された場合、集計には何も追加されません。

[comment]: # ({/fc23e115-22af7980})