
Use the search command
You can't run a Splunk search without using the search command. At the beginning of a search pipeline it is implied. You don't need to invoke it, but you are using it.
Use keywords, phrases, fields, boolean expressions, and comparison expressions to specify exactly which events you want to retrieve from a Splunk index(es). By default, when you search with keywords and phrases, Splunk retrieves events by matching against the raw event field, _raw
, in your data. When you start adding search modifiers, such as fields like _time
and tag
, you're also matching against pieces of information that have been extracted from the _raw
field.
Keywords, phrases, and wildcards
When searching for strings, which includes keywords and quoted phrases (or anything that's not a search modifier), Splunk searches the _raw
field for the matching events or results. Some examples of keywords and phrases are:
web
error
web error
"web error"
Note that the search for the quoted phrase "web error" is not that same as the search before it. When you search for web error
, Splunk returns events that contain both "web" and "error". When you search for "web error", Splunk only returns events that contain the phrase "web error".
The Splunk search language supports regular expressions, the simplest of which is the asterisk (*) wildcard. Use * to match an unrestricted number of characters in a string. Searching for *
by itself means "match all" and retrieves all events up to the maximum limit. Searching for *
as part of a string matches based on that string. For example:
my*
matches myhost1, myhost.ny.mydomain.com, myeventtype, etc.*host
matches myhost, yourhost, etc.*host*
matches host1, myhost3, yourhost27.yourdomain.com, etc
The more specific your search terms are to the events you want to retrieve, the better chance you have at matching them. For example, searching for "access denied" is always better than searching for "denied". If 90% of your events have the word ‘error’ but only 5% have the word ‘sshd’ (and the events you want to find require both of these words), include ‘sshd’ in the search to make it more efficient.
Boolean expressions
Splunk supports the Boolean operators: AND
, OR
, and NOT
; the operators have to be capitalized. The AND operator is always implied between terms, that is: web error
is the same as web AND error
.
Splunk evaluates Boolean expressions in the following order:
1. Expressions within parentheses.
2. OR
clauses.
3. AND
or NOT
clauses.
Without parenthesis,
A=1 AND B=2 OR C=3
will be processed as
A=1 AND ( B=2 OR C=3 )
You can use parentheses to group Boolean expressions.
web client error NOT (403 OR 404)
(A=1 AND B=2 ) OR C=3
Note: Inclusion is generally better than exclusion. Searching for "access denied" will yield faster results than NOT "access granted".
Field expressions
When you add data, Splunk extracts pairs of information and saves them as fields. Some fields are common to all events, but others are not. Adding fields to you search term gives you a better chance of matching specific events.
If you're searching web access logs for specific HTTP status errors, instead of searching for "web error 404", you can use fields to search for:
status=404
Read more about how to "Use fields to retrieve events."
Use wildcards to match multiple field values
You can also use the asterisk wildcard to match multiple field values. For example, the following search would return events with an HTTP status of 400, 401, 402, etc.
status=40*
Use comparison operators to match field values
You can use comparison operators to match a specific value or a range of field values.
Operator | Example | Result |
---|---|---|
= | field=foo | Multivalued field values that exactly match "foo". |
!= | field!=foo | Multivalued field values that don't exactly match "foo". |
< | field<x | Numerical field values that are less than x. |
> | field>x | Numerical field values that are greater than x. |
<= | field<=x | Numerical field values that are less than and equal to x. |
>= | field>=x | Numerical field values that are greater than and equal to x. |
For example, to find events that have a delay field that is greater than 10:
delay > 10
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 force Splunk to do an exact match of the entire term.
- CASE forces Splunk to search for case-sensitive matches for terms and field values.
- TERM forces Splunk to match whatever is inside the parentheses as a single term in the index, even if it contains characters that are usually recognized as minor segmenters, such as periods or underscores.
When you search for a term that contains minor segmenters, Splunk defaults to treating it as a phrase: It searches for the conjunction of the subterms (the terms between minor breaks) and post-filters the results. For example, when you search for the IP address 127.0.0.1, Splunk searches for: 127 AND 0 AND 1
This search is not very efficient if the conjunction of these subterms is common, even if the whole term itself is not common.
If you search for TERM(127.0.0.1), Splunk treats the IP address as a single term to match in your raw data.
TERM is more useful for cases where the term contains minor segmenters and is bounded by major segmenters, such as spaces or commas. In fact, TERM does not work for terms that are not bounded by major breakers. This is illustrated in the examples below.
For more information about how Splunk breaks events up into searchable segments, read "About segmentation" in the Getting Data In Manual.
Examples
TERM(127.0.0.1) works for raw data that looks like:
127.0.0.1 - admin
However, it fails for data that looks like:
ip=127.0.0.1 - user=admin
This is because "=" is a minor breaker and the IP address portion of the event is indexed as: ip, 127, 0, 1, ip=127.0.0.1
If your data looks like this:
ip 127.0.0.1 - user admin
TERM(user admin) fails to return results. The space is a major breaker and Splunk would not index the phrase "user admin" as a single term.
PREVIOUS About retrieving events |
NEXT Use fields to retrieve events |
This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14
Feedback submitted, thanks!