Splunk® Enterprise

Search Reference

Acrobat logo Download manual as PDF


Splunk Enterprise version 8.0 is no longer supported as of October 22, 2021. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk® Enterprise. For documentation on the most recent version, go to the latest release.
Acrobat logo Download topic as PDF

foreach

Description

Use this command to run a streaming subsearch that uses a template to iterate over each field in a wildcarded field list.

Syntax

The required syntax is in bold.

foreach
<wc-field>...
[fieldstr=<string>]
[matchstr=<string>]
[matchseg1=<string>]
[matchseg2=<string>]
[matchseg3=<string>]
<subsearch>

Required arguments

wc-field
Syntax: <field> ...
Description: A list of field names. You can use wild card characters in the field names.
subsearch
Syntax: [ subsearch ]
Description: A subsearch that includes a template for replacing the values of the fields specified.

Optional arguments

fieldstr
Syntax: fieldstr=<string>
Description: Replaces the <<FIELD>> token with the whole field name.
matchstr
Syntax: matchstr=<string>
Description: Replaces <<MATCHSTR>> with part of the field name that matches wildcard(s) in the specifier.
matchseg1
Syntax: matchseg1=<string>
Description: Replaces <<MATCHSEG1>> with part of the field name that matches the first wildcard.
matchseg2
Syntax: matchseg2=<string>
Description: Replaces <<MATCHSEG2>> with part of the field name that matches the second wildcard.
matchseg3
Syntax: matchseg3=<string>
Description: Replaces <<MATCHSEG3>> with part of the field name that matches the third wildcard.

Usage

If the field names contain characters other than alphanumeric characters, such as dashes, underscores, or periods, you need to enclose the <<FIELD>> token in single quotation marks in the eval command portion of the search.

For example, the following search adds the values from all of the fields that start with similar names.

... | eval total=0 | eval test_1=1 | eval test_2=2 | eval test_3=3 | foreach test* [eval total=total + '<<FIELD>>']

The <<FIELD>> token in the foreach subsearch is just a string replacement of the field names test*. The eval expression does not recognize field names with non-alphanumeric characters unless the field names are surrounded by single quotation marks. For the eval expression to work, the <<FIELD>> token needs to be surrounded by single quotation marks.

Examples

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

The following search adds the values from all of the fields that start with similar names. You can run this search on your own Splunk instance.

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

  • This search creates 1 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.

Subsearch iteration Test field Total field start value Test field value Calculation of "total" field
1 test1 0 1 0+1=1
2 test2 1 2 1+2=3
3 test3 3 3 3+3=6

2. Monitor license usage

Use the foreach command to monitor license usage.

First run the following search on the license master to return the daily license usage per sourcetype in bytes:

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

Use the foreach command 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]

3. Use the <<MATCHSTR>>

Add each field that matches foo* to the corresponding bar* and write the result to a new_* field. For example, new_X = fooX + barX.

... | foreach foo* [eval new_<<MATCHSTR>> = <<FIELD>> + bar<<MATCHSTR>>]

4.

Equivalent to ... | eval foo="foo" | eval bar="bar" | eval baz="baz"

... | foreach foo bar baz [eval <<FIELD>> = "<<FIELD>>"]

5.

For the field, fooXbarY, this is equivalent to: ... | eval fooXbarY = "Y"

... | foreach foo*bar* fieldstr="#field#" matchseg2="#matchseg2#" [eval #field# = "#matchseg2#"]

See also

eval, map

Last modified on 30 March, 2022
PREVIOUS
folderize
  NEXT
format

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.10, 7.0.1, 7.2.4, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10, 8.1.0, 7.2.5


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters