Control search execution using directives

You can use the following search execution directives to control aspects of a search before a search executes and optimize search performance.

• REQUIRED_TAGS()
• REQUIRED_EVENTTYPES()
• READ_SUMMARY()

These directives should be used only by advanced Splunk users who need to exercise fine control over their searches. In most cases, do not use REQUIRED_TAGS(), REQUIRED_EVENTTYPES() or READ_SUMMARY() unless directed to do so by Splunk Support.

You may have already heard of TERM() and CASE() directives, which are qualifiers that are applied to search terms in searches. Because TERM() and CASE() don't control how searches are executed or relate to search execution directives, they are not discussed in this section. See Use CASE() and TERM() to match phrases.

REQUIRED_TAGS()

The REQUIRED_TAGS() directive turns off the automatic tagging that Splunk performs as part of the background operations for the search command. Use this directive to tell Splunk software not to run all tags when performing its automatic tagging operations because you're only interested in certain tags that you have defined. The REQUIRED_TAGS() directive is typically used to improve search performance.

The intersect="t" argument that Splunk software adds to the REQUIRED_TAGS directive in some data-model-based searches is for internal use only.

REQUIRED_EVENTTYPES()

The REQUIRED_EVENTTYPES() directive turns off the automatic eventtypes that Splunk generates as part of the background operations for the search command. Use this directive to restrict the set of event types that are used in your search. The REQUIRED_EVENTTYPES() directive is useful for debugging and, in some cases, it can help improve search performance.

READ_SUMMARY()

The READ_SUMMARY() directive tells Splunk software to look only at the specified summary, which allows the search processor to leverage existing data model acceleration summary data when it performs event searches. Use the READ_SUMMARY() directive to tell Splunk software to display summary data for this search from the specified summary only and ignore the rest of the summaries. The READ_SUMMARY() directive is typically used to improve search performance.

This directive is intended primarily for internal use by Splunk software. Do not use READ_SUMMARY() unless directed to do so by Splunk Support.

Examples

These examples use the sample data from the Search Tutorial but should work with any format of Apache web access log. To try these examples on your own Splunk instance, you must download the sample data and follow the instructions to get the tutorial data into Splunk. Use the time range All time when you run the search.

1. Create custom tags using REQUIRED_TAGS()

In this example, say you create two tags like these:

Tag name	field value pair
tag1	host=www1
tag2	host=www2

Then, run the following search using the time range All time:

source="tutorialdata.zip:*" | tags

The results include the tag field, which associates tag1 and tag1 with events that contain the www1 and www2 hosts.

To suppress tag1 and tag2 in the results, run the following search using the time range All time:

source="tutorialdata.zip:*" DIRECTIVES(REQUIRED_TAGS(tags=""))

The results do not include the tag field.

To limit your search to just tag1, run the following search:

source="tutorialdata.zip:*" DIRECTIVES(REQUIRED_TAGS(tags="tag1"))

The results include the tag field, which lists the tag1 tag that is used in the events that contain the www1 host.

2. Restrict event types in searches using REQUIRED_EVENTTYPES()

In this example, say you define the following eventtypes in the eventtypes.conf file:

[eventtype1] search = host=www1

[eventtype2] search = host=www2

Then, run this search:

source="tutorialdata.zip:*" DIRECTIVES(REQUIRED_EVENTTYPES(eventtypes="eventtype1"))

Because the search includes REQUIRED_EVENTTYPES(eventtypes="eventtype1"), it is restricted to eventtype1. As a result, only eventtype1 is returned in the eventtype field.