foreach
Description
The foreach command executes subqueries with a pattern to iterate over the following elements:
- Each field matching a wildcard.
- Each element of a multivalue field.
Syntax
foreach mode=(multifield | multivalue)
<wildcard-field-list> | <field>
<subsearch>
Required Arguments
| Parameter | Syntax | Description |
|---|---|---|
<wildcard-field-list> | [<wildcard>] [<wildcard>]* | A wildcard or a list of wildcards separated by spaces. This parameter is only available in multifield mode. |
<field> | <field> | The field to be used for iterating over elements. This parameter is only available in multivalue mode. |
<subsearch> | [ subsearch ] | An SPL query where only the where and eval commands are allowed. It must be enclosed in square brackets. The query can contain templates, depending on the mode of the foreach command. |
Templates for Subqueries
| Template | Replaces | Description |
|---|---|---|
<<FIELD>> | The field name. | multifield |
<<MATCHSTR>> | The part of the field name that matches the wildcard. | multifield |
<<MATCHSEG1>> | The part of the field name that matches the first wildcard. | multifield |
<<MATCHSEG2>> | The part of the field name that matches the second wildcard. | multifield |
<<MATCHSEG3>> | The part of the field name that matches the third wildcard. | multifield |
<<ITEM>> | The element of a multivalue field. | multivalue |
Optional Arguments
| Parameter | Syntax | Default | Description |
|---|---|---|---|
<mode> | mode=<mode-name> | multifield | Mode for foreach. Multifield iterates over one or more specified field names that match a wildcard. Multivalue iterates over the values of a multivalue field. |
Example Queries
Example 1
In this example, subqueries are executed for each field matching the wildcard message*. Each subquery creates a new field new_<<MATCHSTR>>, where <<MATCHSTR>> is replaced with the part matching the wildcard (e.g., for message1, the field new_1 is created), and assigns it the value of the field for which the subquery was called.
source tweets6
| foreach mode=multifield message* [eval new_<<MATCHSTR>> = <<FIELD>>]
Example 2
In this example, the field sum is calculated as the sum of the values of all fields matching the wildcard test*.
| makeresults
| eval test1 = 100, test2 = 200, test3 = 300, sum = 0
| foreach test* [eval sum = <<FIELD>> + sum]
Example 3
In this example, the field sum is calculated as the sum of the values of all elements of the multivalue field test.
| makeresults
| eval test = mvappend(100, 200, 300), sum = 0, total = 0
| foreach mode=multivalue test [eval sum = sum + <<ITEM>>, total = total + 1]
Example 4
In this example, the records are filtered to only include those where all fields matching the wildcard value* have a value greater than 1000.
source foreach_data
| foreach value* [where <<FIELD>> > 1000]
Example 5
In this example, the field max is calculated as the maximum value among the elements of the multivalue field test.
| makeresults
| eval test = mvappend(100, 200, 300, 150), max = 0
| foreach mode=multivalue test [eval max = if(max < <<ITEM>>, <<ITEM>>, max)]
Example 6
In this example, a new field is created for each query, where the field's name is composed of two segments that match the parts of the field name matching the wildcard. For instance, for the field t3t3t6, a new field new_336 is created with the value 36.
| makeresults
| eval t1t1t1 = 100, t2t2t2 = 200, t3t3t6 = 300
| foreach t*t*t* [eval new_<<MATCHSTR>> = <<MATCHSEG1>><<MATCHSEG3>>]