Use CASE() and TERM() to match phrases
If you want to search for a specific term or phrase in your Splunk index, use the CASE() or TERM() directives to do an exact match of the entire term.
- CASE
- Syntax: CASE(<term>)
- Description: Search for case-sensitive matches for terms and field values.
- TERM
- Syntax: TERM(<term>)
- Description: Match whatever is inside the parentheses as a single term in the index, even if it contains characters that are usually recognized as minor breakers, such as periods or underscores.
The CASE()
and TERM()
directives are similar to the PREFIX()
directive used with the tstats
command because they match strings in your raw data. For more information about the PREFIX()
directive, see tstats in the Search Reference.
When to use CASE
By default, searches are case-insensitive. For example, if you search for Error
, any case of that term is returned, such as Error
, error
, and ERROR
. You can use the CASE directive to perform case-sensitive matches for terms and field values. For example, if you search for CASE(error)
, your search returns results containing only the specified case of the term, which is error
.
You can use the CASE directive to search for terms using wildcards. For example, searching for CASE(%ASA-1*)
returns events matching values such as %ASA-1-134568
and %ASA-1-12345
.
Example
The following search only matches events that contain localhost in uppercase in the host
field.
host=CASE(LOCALHOST)
When to use TERM
The TERM directive is useful for more efficiently searching for a term that:
- Contains minor breakers, such as periods or underscores.
- Is bound by major breakers, such as spaces or commas.
- Does not contain major breakers.
When data is indexed, characters such as periods and underscores are recognized as minor breakers between terms. Use the TERM directive to ignore the minor breakers and match whatever is inside the parentheses as a single term. For example, the IP address 127.0.0.1
contains the period ( . ) minor breaker. If you search for the IP address 127.0.0.1, Splunk software searches for 127 AND 0 AND 1
and returns events that contain those numbers anywhere in the event. If you specify TERM(127.0.0.1)
, the search treats the IP address as a single term, instead of individual numbers, and returns all events that contain the IP address 127.0.0.1.
The TERM directive only works for terms that are bounded by major or minor breakers, but the term you are searching for cannot contain major breakers. For example, you cannot use TERM to search for Maria Dubois
because there is a space between the names. This is discussed in the examples later in this topic.
When you use the TERM directive, the Splunk software expects to see the term you specify as a token in the lexicon in the .tsidx file. For more information about how Splunk software breaks events up into searchable segments, see About segmentation in Getting Data In.
You can use the TERM directive to search for terms using wildcards. For example, searching for TERM(%ASA-1*)
returns events matching values such as %ASA-1-134568
and %ASA-1-12345
.
See Use the TERM directive to match terms that contain minor breakers.
Using TERM() with major and minor breakers
Searches that contain the TERM() directive might return unexpected results if the following conditions are met:
- The term in the TERM directive contains minor breakers, such as a period ( . ); and
- The raw data for the term is bound by major breakers that end in a number or letter; and
- The search contains other expressions such as
host=*
,sourcetype=*
ormyfield=*
, OR contains other expressions that include minor breakers, such as"myfield1.myfield2", "myfield1:myfield2"
.
For example, say your raw data is foo%20www.something.com%20abc 127.1.1
, which includes the major breaker %20
. The following searches don't return results:
index=main TERM(www.something.com) host=*
index=main TERM(www.something.com) "127.1.1"
However, the following search does return results:
index=main TERM(www.something.com)
For a full list of minor breakers and multicharacter major breakers, see the segmenters.conf file in the Splunk Enterprise Admin Manual.
Examples
Searching for TERM(127.0.0.1)
works for raw data that looks like this:
127.0.0.1 - admin
Both 127.0.0.1
and admin
are bounded by major breakers, in this case spaces.
However, searching for TERM(127.0.0.1)
fails for data that looks like this:
ip=127.0.0.1 - user=admin
This is because the equal symbol ( = ) is a minor breaker, not a major breaker. Additionally, the IP address portion of the event is indexed as: ip
, 127
, 0
, 1
, and ip=127.0.0.1
. You are looking for 127.0.0.1
, which is not an indexed term.
If your data looks like this:
ip 127.0.0.1 - user admin
Searching for TERM(user admin)
fails to return results. The space is a major breaker and the phrase "user admin" is not indexed as a single term. In this situation, use quotation marks to search for a string that contains a space, for example "user admin"
.
See also
- Related information
- Event segmentation and searching
Event segmentation and searching | Boolean expressions |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!