search command: Overview and syntax
The SPL2 search
command is similar to the SPL search
command with 1 major exception - You must specify the word search
at the beginning of your search. For example:
SPL search | SPL2 search |
---|---|
|
|
The SPL2 search
command, when used at the beginning of a search, retrieves events from one or more index datasets. When used in the middle of a search, the command filters search results that are already in memory.
You can retrieve events from your datasets using keywords, quoted phrases, wildcards, and field-value expressions. When the search
command is not the first command in the pipeline, it is used to filter the results of the previous command.
Use these links to quickly navigate to the main sections in this topic:
How the SPL2 search command works
You specify a search expression, such as a keyword or a field-value pair, when you use the SPL2 search
> command.
Keyword searches are searches for literal values, terms or phrases, that appear in your events.
Use the search
command to perform keyword searches against events in your indexes, similar to searching the internet using a web browser. For example, you can search for a literal value such as buttercupgames
or itemId
.
Keyword searches are not case sensitive. The following search returns any event that contains the term itemId
, including all variations of the capitalization of that term, such as itemID
, ITEMID
, and itemid
.
| search itemId
To search for a phrase, enclose the phrase in double quotations. For example, this search returns only those events where the term Windows
is immediately followed by a space and the number 10
:
| search "Windows 10"
You also use double quotations for terms that contain punctuation, for example:
| search "SC-MG-G10"
Search using field-value pairs
When you are looking for a specific value in a field, identify the field in your search using a field-value pair.
The field name is case sensitive, the field value is not case sensitive.
For example, to search the categoryId
field for the value sports
, use this search:
| search categoryId=sports
Searching for multiple keywords
When you specify multiple terms to search for, there is an implied AND operator between each term. In the following example, the search looks only for events where the term www2
exists and the categoryId
field contains sports
:
| search www2 categoryId=sports
This is the same as if you explicitly included the AND operator in your search, such as:
| search www2 AND categoryId=sports
Search expressions
The search
command, along with the from
command, is one of the most powerful commands in SPL2.
There are a wide variety of search expressions that you can specify with the search
command. To learn more about how you can use the search
command, see the Syntax section in this topic and the search command: Usage topic for examples of common search expressions.
For a complete description of the types of expressions that you can use in SPL2, see Types of expressions in the SPL2 Search Manual.
Syntax
The required syntax is in bold.
- search <search-expression>
Required arguments
- search-expression
- Syntax: <literal-expression> | <comparison-expression> | <time-expression> | <index-expression>
- Description: The <search-expression> can be a word or phrase, a field-value comparison, a list of values, or a group of search expressions. You can use logical expressions by using IN, AND, OR, or NOT comparisons in your <search-expression>.
You can use Boolean operators to specify more than one <search-expression>. The supported operators are AND, OR, and NOT. Examples of how you can use these operators are:
- <search-expression> AND <search-expression>
- <search-expression> OR <search-expression>
- NOT <search-expression>
Literal expression
- literal-expression
- Syntax: <literal-value> | "<literal-phrase>")
- Description: You can search for string values, number values, or phrases in your data. For example you can specify a word such as
error
, a number such as404
, or a phrase such as"time limit"
. If the string, number, or phrase contains any characters like periods ( . ) or spaces, you must enclose the word or phrase in double quotation marks.
Comparison expression
- comparison-expression
- Syntax: (<field><comparison-operator> [<value>| TERM | CASE]) | <field> IN (<value-list>)
- Description: You can specify a field name and a comparison operator, such as equal to ( = ) or greater than ( > ), followed by the literal number or string value of a field. You can also specify field name and the IN keyword followed by a list of values enclosed in parentheses. For example, you can specify
categoryID="accessories"
orbytes>3900
orstatus IN (400,403,404)
.
- You can use comparison operators when searching for field/value pairs. Comparison expressions with the equal ( = ) or not equal ( != ) operator compare string values. For example, "1" does not match "1.0". Comparisons with greater than or less than operators, including
<=
and>=
numerically compare two numbers and lexicographically compare other values. Valid comparison operators are:=
,!=
,<
,<=
,>
, and>=
. See search command usage.
- You can use the CASE() or TERM() directives to perform an exact match for a term.
- field
- Syntax: <string>
- Description: The name of a field.
- value
- Syntax: <literal-value>
- Description: In comparison-expressions, the literal number or string value of a field.
- value-list
- Syntax: (<literal-value>, <literal-value>, ...)
- Description: Used with the IN operator to specify two or more values. For example use
error IN (400, 402, 404, 500)
instead oferror=400 OR error=402 OR error=404 OR error=500
. You can also use a wildcard character ( * ) to specify similar values, such aserror IN(40*, 500)
.
- CASE
- Syntax: CASE(<term>)
- Description: By default searches are case-insensitive. If you search for
Error
, any case of that term is returned such asError
,error
, andERROR
. Use the CASE directive to perform case-sensitive matches for terms and field values.CASE(error)
will return only that specific case of the term.
- TERM
- Syntax: TERM(<term>)
- Description: When data is indexed, characters such as periods and underscores are recognized as minor segmenters between terms. Use the TERM directive to ignore the minor segmenters and match whatever is inside the parentheses as a single term. The <term> must have been bound by major segmenters, such as spaces or commas, before it was indexed. For example, the IP address
127.0.0.1
contains the period ( . ) minor segmenter. If you search for the IP address using| search 127.0.0.1
the search is converted into| search 127 AND 0 AND 1
which returns events that contain those numbers anywhere in the event. If you search using| search TERM(127.0.0.1)
the search treats the IP address as a single term, instead of individual numbers.
Time expression
- time-expression
- Syntax: [<timeformat>] (<time-modifier>)...
- Description: Describes the format of the start and end time of the search. Use the <timeformat> to set the time format. The <timeformat> is optional, and if not specified the default format is
%m/%d/%Y:%H:%M:%S
. Use the <time-modifier> to specify start and end times using absolute or relative times.
- An absolute time range uses specific dates and times, for example, from 12 A.M. July 1, 2019 to 12 A.M. July 13, 2019.
- A relative time range is dependent on when the search is run. For example, a relative time range of -60m means 60 minutes ago. If the current time is 3 P.M., the search returns events from the last 60 minutes, or 2 P.M. to 3 P.M. today.
Use the earliest and latest modifiers to specify custom and relative time ranges. You can specify an exact time such as earliest="10/5/2016:20:00:00"
, or a relative time such as earliest=-h
or latest=@w6
.
Time modifier | Description | Examples |
---|---|---|
starttime=<string> | Events must be later or equal to this time.
Times must match the <timeformat>. |
starttime="%d-%b-%Y %H:%M:%S"
|
endtime=<string> | All events must be earlier or equal to this time.
Times must match the <timeformat>. |
endtime="%d-%b-%Y %H:%M:%S
|
earliest=<time_modifier> | Events must be later or equal to this time.
You can specify an absolute or relative time, including a snap-to time. |
earliest=4/27/2019:00:00:00
|
latest=<time_modifier> | All events must be earlier or equal to this time.
You can specify an absolute or relative time, including a snap-to time. |
latest=7/16/2019:00:00:00
|
Index expression
- index-expression
- Syntax: "<string>" | <term> | <search-modifier>
- Description: Use to describe the events you want to retrieve from the index using literal strings and search modifiers.
- string
- Syntax: "<string>"
- Description: Specify keywords or quoted phrases to match. When searching for strings and quoted strings, anything that is not a search modifier, the
_raw
field is searched for the matching events or results.
- search-modifier
- Syntax: <sourcetype-specifier> | <host-specifier> | <hosttag-specifier> | <source-specifier> | <savedsplunk-specifier> | <eventtype-specifier> | <eventtypetag-specifier> | <splunk_server-specifier>
- Description: Search for events from specified fields or field tags. For example, search for one or a combination of hosts, sources, source types, saved searches, and event types. Also, search for the field tag, with the format: tag::<field>=<string>.
- sourcetype-specifier
- Syntax: sourcetype=<string>
- Description: Search for events from the specified sourcetype field.
- host-specifier
- Syntax: host=<string>
- Description: Search for events from the specified host field.
- hosttag-specifier
- Syntax: hosttag=<string>
- Description: Search for events that have hosts that are tagged by the string.
- eventtype-specifier
- Syntax: eventtype=<string>
- Description: Search for events that match the specified event type.
- eventtypetag-specifier
- Syntax: eventtypetag=<string>
- Description: Search for events that would match all eventtypes tagged by the string.
- savedsplunk-specifier
- Syntax: savedsearch=<string> | savedsplunk=<string>
- Description: Search for events that would be found by the specified saved search.
- source-specifier
- Syntax: source=<string>
- Description: Search for events from the specified source field.
- splunk_server-specifier
- Syntax: splunk_server=<string>
- Description: Search for events from a specific server. Use "local" to refer to the search head.
See also
- search command
- search command: Usage
- search command: Examples
route command: Overview | search command: Usage |
This documentation applies to the following versions of Splunk® Cloud Services: current
Feedback submitted, thanks!