search command usage
search command is an generating command when it is the first command in the search. The command generates events from the dataset specified in the search. However it is also possible to pipe incoming search results into the
search command. The <search-expression> is applied to the data in memory. For example, the following search puts data from the
main dataset into memory and then filters out events that do not contain the term
| from main | search 500
Searching for terms in your data
The search command can look for events that contain simple text terms, or character sequences, like this:
| search "UserNotFound"
_raw field is searched in all of the indexes that are visible to the current user in the current module for events that contain the text
Searching for phrases
search command, while quotation marks are not required to search for a term, if term that you are looking for contains spaces then quotation marks are required. If you omit the quotation marks, there is no guarantee the 'words' in the term you want to find are next to each other in the event. For example, these two search are not the same:
|| search User Not Found||This is the same as |
There is an implied AND condition between each word. Each word can appear anywhere in an event.
|| search "User Not Found"||This search finds the events that contain the phrase |
Searching for field values
search command also allows for more precise searches, such as looking for a value in a particular field. For example this search:
| search host=localhost
This search finds events that contain the string
localhost in the
host field. The field must always be on the left side of the comparison operator. Because of this strict ordering, no quoting is required to distinguish between field references and string literals.
To find all events in a particular field, use the wildcard character ( * ). For example:
| search status=*
This example returns only events that contain a
status field. You can also use the other comparison operators, such as:
Searching with wildcard characters
You can look for terms that contain a similar sequence of characters by using a wildcard character ( * ). Wildcard characters can be used both in text searches and in searching for field values. For example:
| search ccnumber="4232*1232" H*l*o
This search returns events that meet both of the conditions specified. Events must have the
ccnumber field with values that start with 4232 and end with 1232. The events must also have a word that starts with
H followed later by
l and ends with
o, such as the word
For information about best practices for using wildcards and when to avoid using wildcards, see Wildcards in the SPL2 Search Manual.
Indexed fields in search
When searching for a <field>=<value> or <field>="<value>", events that contain the value are searched for. For every matching event, a field extraction is run. Finally an in memory filter is applied for <field>=<value> to remove false positives.
However, if the field is known to be an indexed field you can take advantage of how index fields are stored in the index by looking for <field>::<value> instead of simply <value>. This is often much faster as it avoids reading and enriching events that contain the <value>, but do not contain the <value> in the <field>.
Searching with boolean operators
search command also allows for the construction of conjunctions and disjunctions which are both just more complex predicates.
Conjunctions can be explicitly specified using the AND operator, or can are implicitly inferred when two or more conditions are present, for example these two searches are identical:
| search host=localhost UserNotFound
| search host=localhost AND UserNotFound
Both examples match events that contain both
UserNotFound in the
_raw field and
localhost in the
Disjunctions must be explicitly specified using the OR operator:
| search host=localhost OR UserNotFound
Arbitrarily complicated combinations of conjunctions and disjunctions, or compound predicates, can be constructed by using the grouping operator, the parenthesis ( ). For example:
| search host=localhost ( UserNotFound OR sourcetype=webaccess )
Matches events that have
host equal to
localhost and either contain
UserNotFound or have
sourcetype equal to
It is possible to search for events that have a field that is not equal to a particular value using the != operator, like this:
| search src!="127.0.0.1"
However this only returns events that actually have a
src field. To also return events without a
src field use the NOT operator instead:
| search NOT src="127.0.0.1"
This will return all events where either the
src field is not found or where
src is not "127.0.0.1". You can also use the NOT operator with simple keyword searches like this:
search NOT error
This search return all events not containing "error".
search command supports implicit tiebreaking between AND and OR operators. To illustrate, these are both valid:
| search A AND B OR C
| search A B OR C
And are both processed as if written like this:
| search A AND (B OR C)
The rule is that OR bind its operands with higher precedence than AND, but this can be overridden using the explicit grouping operator. These searches product the same results:
| search (A AND B) OR C
| search (A B) OR C
search command supports the IN operator:
| search status IN (401, 403)
Which finds events where the value of the
status field is either
Running case-sensitive searches
By default string searches are case insensitive. Using the CASE directive, it is possible to do a case-sensitive match. For example:
| search host=CASE(LOCALHOST)
This search only matches events that contain localhost in uppercase in the
The TERM directive is useful for more efficiently finding terms, when you are searching for a term that:
- Contains minor breakers
- Is bound by major breakers, such as spaces or commas
- Does not contain major breakers
To illustrate, imagine looking for
127.0.0.1. This term contains minor breakers, the period character ( . ). If we know that
127.0.0.1 is bound on either side by major breakers like a comma ( , ) or space (" "), it is more efficient to search using
TERM(127.0.0.1) than simply
For example, suppose the
_raw field looks like this:
Because 127.0.0.1 is bound on either side by a major breaker, a comma ( , ), using TERM(127.0.0.1) will match. However if the
_raw field looked like this:
This event would not be found because the full term after splitting on major breakers is
Major differences between search and other commands
There are major differences between predicates in the
search command and predicates in the
from commands and elsewhere in the language, including:
|Search command||Where command|
|A subset of the
|Has a rudimentary expression language||A powerful expression language with full access to an exhaustive list of scalar functions, arithmetic operators, parameters, navigation properties and literal constructs like array literals, verbatim strings, regex literals.|
|Comparison operators are always interpreted as <field><operator><value>||The left operands and right operands are interpreted based on syntax rules for each kind of operand. For example it is possible to perform <field><operator><field>.|
|The AND operator is implied||The AND operator must be explicitly specified.|
|Grouping precedence rules are implied.||The grouping operator () must be explicitly used.|
|Can search for a specific sequence of characters anywhere in an event.||Must be more explicit to find characters. For example use |
Indexes in scope
In SPL2 when using the
search command, indexes are either those explicitly mentioned in the
search predicate, or a default index. For example:
|search index=main ERROR||This search is explicitly scoped to the |
|search ERROR||This search picks up the indexes that are implicitly in scope.
Which means all of the indexes visible to the current user in the module that the search is run in.
Using time modifiers
Specify absolute time ranges
For exact time ranges, the syntax for the time modifiers is
%m/%d/%Y:%H:%M:%S. For example, the following search specifies a time range from 12 A.M. July 13, 2021 to 12 A.M. July 16, 2021.
If you specify only the
earliest time , the
latest time is set to the current time
Now by default. If you specify the
latest time, you must also specify the
For more information on using time modifiers see Time modifiers in the SPL2 Search Manual.
Differences between SPL and SPL2
Different requirements for fields that must be quoted
If a field name must be quoted, SPL2 uses single quotation marks. For example, if a field name contains a space, the field name must be single quoted. SPL uses double quotation marks.
|SPL||search "my field"=10|
|SPL2||search 'my field'=10|
Different requirements for quoting values
search command is designed to be backward compatible with SPL. String values do not need to be double quoted in SPL2 when you use the
search command. When using any other SPL2 command, string values must be double quoted.
search command syntax details
search command examples
This documentation applies to the following versions of Splunk® Cloud Services: current