search command usage

The 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 500.

| 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"

The _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 UserNotFound.

Searching for phrases

With the 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	Description
\| search User Not Found	This is the same as `search User AND Not AND Found.` 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 `User Not Found`.

Searching for field values

The 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: !=, <, <=, >, and >=.

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 Hello.

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

The search command also allows for the construction of conjunctions and disjunctions which are both just more complex predicates.

AND Operator

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 host field.

OR Operator

Disjunctions must be explicitly specified using the OR operator:

| search host=localhost OR UserNotFound

Grouping Operator

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 webaccess.

NOT Operator

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".

Implicit Grouping

The 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

IN Operator

The search command supports the IN operator:

| search status IN (401, 403)

Which finds events where the value of the status field is either 401 or 403.

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 host field.

TERM directive

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 127.0.0.1. For example, suppose the _raw field looks like this:

_time=1549931073,127.0.0.1,test,foo,bar

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:

_time=1549931073,host=127.0.0.1,test,foo,bar

This event would not be found because the full term after splitting on major breakers is host=127.0.0.1 not 127.0.0.1.

Major differences between search and other commands

There are major differences between predicates in the search command and predicates in the where and from commands and elsewhere in the language, including:

Search command	Where command
A subset of the `where` command functionality	Full functionality
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 `...where _raw=sequence` or `where searchmatch(<search-predicate>)`

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	Description
search index=main ERROR	This search is explicitly scoped to the `main` index.
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.

earliest=7/13/2021:00:00:00 latest=7/16/2021:00:00:00

Time modifiers

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 earliest time.

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.

Version	Example
SPL	search "my field"=10
SPL2	search 'my field'=10

Different requirements for quoting values

The 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.

Version	Example
SPL	search host!="localhost"
SPL2	search host!=localhost

Related answers from Splunk Community