Required arguments

Optional arguments

| foreach mode=multivalue itemstr=<<NUMBER>> numbers 
    [ eval result = result + <<NUMBER>>]

| foreach mode=multivalue numbers 
    [ eval result = result + <<ITER>>]

| foreach mode=multivalue iterstr=<<NUMBER>> numbers 
    [ eval result = result + <<NUMBER>>]

Supported commands

The foreach command with mode=multifield supports searches with any streaming command.

The foreach command with all other modes (mode=auto_collections, mode=multivalue, or mode=json_array) only supports searches with the eval command.

Iterating over multiple matching fields containing nonalphanumeric characters

If the field names contain characters other than alphanumeric characters, such as dashes, underscores, or periods, enclose the <<FIELD>> template value in single quotation marks in the right side of the eval command portion of the search to avoid unpredictable results. For example, the following search uses the default foreach multifield mode and adds the values from all of the fields that match myfield_*.

| makeresults
| eval myfield_1 = 5, myfield_2 = 10
| foreach myfield_* 
       [eval <<FIELD>> = '<<FIELD>>' + <<MATCHSTR>>]

The search results look something like this:

The <<FIELD>> template value in the foreach subsearch is just a string replacement of the field named myfield_*. The eval expression does not recognize field names with nonalphanumeric characters unless the field names are surrounded by single quotation marks. For the eval expression to work, the <<FIELD>> template value must be surrounded by single quotation marks.

Support for multiple eval statements

If you need to include multiple eval statements with the foreach command, use the default multifield mode. Multiple eval statements are not supported in foreach searches that use multivalue mode or JSON array mode. As a result, your searches on multivalue fields or JSON arrays must contain only a single eval statement in the pipeline. However, your eval statement can include as many assignments as you want.

For example, the following multivalue search with multiple eval assignments completes successfully because there is only one eval statement, which means there aren't any piped commands following the eval command.

| makeresults
| eval mv=mvappend("5", "15"), total = 0, count = 0
| foreach mode=multivalue mv
     [eval total = total + <<ITEM>>, count = count + 1]

The search results look something like this.

Wildcards are not supported in multivalue fields or JSON arrays

Unlike multifield mode, the modes for multivalue fields and JSON arrays don't support wildcards in search expressions. Instead, these modes treat a wildcard as part of the field name. For example, the following search includes a field called mv*, which looks like a wildcarded field.

| makeresults 
| eval mv1=mvappend("1", "2"), mv2=mvappend("3", "4"), mv*=mvappend("100", "300"), total = 0
| foreach mode=multivalue mv* 
     [eval total = total + <<ITEM>>]

Elements of the same type in multivalue fields or JSON arrays

Elements in a subsearch and the eval expression must be of the same type as either strings or numbers. For example, the following search correctly adds up the three numbers in the JSON array because all of the elements are numbers.

| foreach json_array(1, 2, 3) 
     [eval total = total + <<ITEM>>]

However, the following search results in an error because adding a number to a string isn't allowed.

| foreach json_array(1, 2, "hello") 
     [eval total = total + <<ITEM>>]

1. Generate a total for each row in search results

Suppose you have events that contain the following data:

Use the foreach command with the default multifield mode to iterate over each field that starts with www and generate a total for each row in the search results.

...| eval total=0
| foreach www* 
     [eval total=total + <<FIELD>>]

The results look like this:

2. Add the values from all fields that start with similar names

The following search adds the values from all of the fields that start with similar names and match the wildcard field test*. It uses the foreach command with the default multifield mode

| makeresults
| eval total=0, test1=1, test2=2, test3=3 
| foreach test* 
     [eval total=total + <<FIELD>>]

The results of the search look something like this.

• This search creates one result using the makeresults command.
• The search then uses the eval command to create the fields total, test1, test2, and test3 with corresponding values.
• The foreach command is used to perform the subsearch for every field that starts with "test". Each time the subsearch is run, the previous total is added to the value of the test field to calculate the new total. The final total after all of the test fields are processed is 6.

The following table shows how the subsearch iterates over each test field. The table shows the beginning value of the total field each time the subsearch is run and the calculated total based on the value for the test field.

3. Iterate over fields using the eval and foreach commands

The eval command and foreach command can be used in similar ways. For example, this search uses the eval command:

| makeresults
| eval name="name" | eval price="price" | eval category="category"

It is equivalent to this search that uses the foreach command with the default multifield mode:

| makeresults 
| foreach name price category 
     [eval <<FIELD>> = "<<FIELD>>"]

The results of both searches look something like this:

4. Monitor license usage

Use the foreach command to monitor license usage.

First run the following search on the license manager to return the daily license usage per source type in bytes:

index=_internal source=*license_usage.log type!="*Summary" earliest=-30d
| timechart span=1d sum(b) AS daily_bytes by st

The search results for one user across several days looks something like this:

You can also use the foreach command with the default multifield mode to calculate the daily license usage in gigabytes for each field:

index=_internal source=*license_usage.log type!="*Summary" earliest=-30d
| timechart span=1d sum(b) AS daily_bytes by st
| foreach * [eval <<FIELD>>='<<FIELD>>'/1024/1024/1024]

This time the search results look something like this:

5. Use the MATCHSTR template value

In this example, the <<FIELD>> template value is a placeholder for test, and the <<MATCHSTR>>template value represents the wildcarded value that follows test in each field name in the eval expression. This example uses the default multifield mode.

| makeresults
| eval test1 = 5, test2 = 10
| foreach test* [eval <<FIELD>> = <<FIELD>> + <<MATCHSTR>>]

The results look something like this:

The value of each field is added to the value that replaces the wildcard in the field name. For example, for the test1 field, 5 + 1 = 6.

6. Use the MATCHSEG1 and MATCHSEG2 template values

This example uses the default multifield mode. The matchseg1 and matchseg2 options are used to add each field value to the two values represented by the wildcard in the corresponding <<MATCHSEG1>> and <<MATCHSEG2>> template values.

| makeresults
| eval test1ab2=5, test2ab3=10
| foreach test*ab* fieldstr=MYFIELD matchseg1=SEG1 matchseg2=SEG2 
     [eval MYFIELD = MYFIELD + SEG1 + SEG2]

Let's take a closer look at the syntax for the test1ab2=5 eval expression:

The results of the search look something like this:

The value of the test1ab2 field in the search results is 8 because 5 + 1 + 2 = 8.

7. Add values in a multivalue field using the auto_collections mode

In this example using the auto_collections mode, <<ITEM>> is a placeholder for each number in the multivalue field, which is added to the total.

| makeresults 
| eval mvfield=mvappend("1", "2", "3"), total=0 
| foreach mode=auto_collections
     [eval total = total + <<ITEM>>] 
| table mvfield, total

The results of the search look something like this.

The previous search produces similar results as the following eval search, which also displays the total, but without listing each of the values that make up the total.

| makeresults
| eval total = 0
| eval total = total + 1 
| eval total = total + 2 
| eval total = total + 3

The search results look like this:

8. Calculate grade averages using multivalue fields

To find the average of a set of student grades using the multivalue mode, you could run this search:

| makeresults 
| eval teacher="James", student_grades=mvappend("50", "100", "30"), sum = 0, count = 0
| foreach mode=multivalue student_grades
    [eval sum = sum + <<ITEM>>, count = count + 1]
| eval average = sum / count

The search results look something like this:

9. Add values in a JSON array

If you want to do something simple like add up each element in a JSON array, you could run a search like this:

| makeresults 
| eval jsonfield=json_array(1, 2, 3), total=0 
| foreach mode=json_array jsonfield 
     [eval total = total + <<ITEM>>] 
| table jsonfield, total

The search results look like this:

10. Categorize employees by manager using multivalue fields

You can create lists of employee names and organize them by manager using the eval command or the foreach command. This is an example of a search on employees and their manager using the eval command:

| makeresults 
| eval manager="Rutherford", employees=mvappend("Alex", "Claudia", "David")
| fields - _time

The results of the eval search look something like this.

To create multivalue fields of employee names and organize them by manager, you can run a similar search using multivalue fields with the foreach command:

| makeresults 
| eval manager="Rutherford", employees=mvappend("Alex", "Claudia", "David"), employees_array=json_array()
| foreach mode=multivalue employees 
     [eval employees_array=json_append(employees_array, "", <<ITEM>>)]
| fields - _time

The search results this time look like this:

11. Add values to a JSON array

Now let's take the names of the employees in a multivalue field and append them to a JSON array. In this search, the employees_array is empty.

| makeresults 
| eval manager="Rutherford", employees=mvappend("Alex", "Claudia", "David"), employees_array=json_array()
| fields - _time

The search results look like this:

To copy all the values from the multivalue field into json_array(), use foreach to iterate over the employees values and append each of the employee names to the array, like this search:

| makeresults 
| eval manager="Rutherford", employees=mvappend("Alex", "Claudia", "David"), employees_array=json_array()
| foreach mode=multivalue employees 
     [eval employees_array=json_append(employees_array, "", <<ITEM>>)]
| fields - _time

Now the search results look like this:

The foreach command just copied over each of the employees' names to the JSON array.

12. Extracting values from a JSON array

What if you want to extract values for given key names from a JSON array and do something with them? For example, the following search extracts a list of employee IDs from a JSON array of employees and puts them in a new field called ID_array that you can use for other operations.

| makeresults 
| eval manager="Rutherford", employees=mvappend("Alex", "Claudia", "David"), ID_array=json_array(), IDs=json_object("Alex", 4125, "Claudia", 2538, "David", 3957)
| foreach mode=multivalue employees 
     [eval ID_array=json_append(ID_array, "", json_extract(IDs, <<ITEM>>))]
| fields - _time

The results of this search look something like this:

13. Multiplying elements in a JSON array

You can use the foreach command to multiply numbers and append to a JSON array in searches like this:

| makeresults 
| eval price=json_array(1,2,3,4), double_price=json_array()
| foreach mode=json_array price 
    [eval double_price = json_append(double_price, "",  <<ITEM>> * 2)]

The results look something like this:

This search doubles each value in the array in price and then adds the values to a new array called double_price.

14. Calculating weights

To find the weights of values in a JSON array called grades, you could run a search like this:

| makeresults 
| eval grades=json_array(1,2,3,4), weight=json_array()
| eval sum = 0
| foreach mode=json_array grades 
    [eval sum = sum + <<ITEM>>]
| foreach mode=json_array grades
    [eval weight = json_append(weight, "", <<ITEM>> / sum)]

The search results look something like this:

15. Iterate over multivalue fields and concatenate the values

The following example iterates over multivalue fields and concatenates the values, so that each letter is added to the index value in the search results.

|makeresults
|fields - _time
|eval word=split("ABCDE",""), nums=split("01234","")
|foreach word mode=multivalue [eval word_and_num=mvappend(word_and_num, <<ITEM>>.mvindex(nums, <<ITER>>))]

The search results look like this: