Search Reference

 


search

NOTE - Splunk version 4.x reached its End of Life on October 1, 2013. Please see the migration information.

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

search

Use the search command to retrieve events from your indexes, using keywords, quoted phrases, wildcards, and key/value expressions; The command is implicit when it's the first search command (used at the beginning of a pipeline). When it's not the first search command, it's used to filter results.

After you retrieve events, you can apply commands to them to transform, filter, and report on them. Use the vertical bar "|" , or pipe character, to apply a command to the retrieved events.

Synopsis

Retrieve events from indexes or filter the results of a previous search command in the pipeline.

Syntax

search <logical-expression>

Arguments

<logical-expression>
Syntax: <time-opts> | <search-modifier> | [NOT] <logical-expression> | <index-expression> | <comparison-expression> | <logical-expression> [OR] <logical-expression>
Description: Includes all keywords or key/value pairs used to describe the events to retrieve from the index. These filters can be defined using Boolean expressions, comparison operators, time modifiers, search modifiers, or combinations of expressions.

Logical expression

<comparison-expression>
Syntax: <field><cmp><value>
Description: Compare a field to a literal value or values of another field.
<index-expression>
Syntax: "<string>" | <term> | <search-modifier>
Description: Describe the events you want to retrieve from the index using literal strings and search modifiers.
<time-opts>
Syntax: [<timeformat>] (<time-modifier>)*
Description: Describe the format of the starttime and endtime terms of the search

Comparison expression

<cmp>
Syntax: = | != | < | <= | > | >=
Description: Comparison operators. You can use comparison expressions when searching field/value pairs. Comparison expressions with "=" and "!=" work with all field/value pairs. Comparison expressions with < > <= >= work only with fields that have numeric values.
<field>
Syntax: <string>
Description: The name of a field.
<lit-value>
Syntax: <string> | <num>
Description: An exact or literal value of a field. Used in a comparison expression.
<value>
Syntax: <lit-value> | <field>
Description: In comparison-expressions, the literal (number or string) value of a field or another field name.

Index expression

<string>

   Syntax: "<string>" 
   Description: Specify keywords or quoted phrases to match. When searching for strings and quoted strings (anything that's not a search modifier), Splunk searches the _raw field for the matching events or results. 
<search-modifier>
Syntax: <sourcetype-specifier>|<host-specifier>|<source-specifier>|<savedsplunk-specifier>|<eventtype-specifier>|<tag-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: </code>tag=<field>::<string></code>.

Time options

Splunk allows many flexible options for searching based on time. For a list of time modifiers, see the topic "Time modifiers for search"

<timeformat>
Syntax: timeformat=<string>
Description: Set the time format for starttime and endtime terms. By default, the timestamp is formatted: timeformat=%m/%d/%Y:%H:%M:%S .
<time-modifier>
Syntax: starttime=<string> | endtime=<string> | earliest=<time_modifier> | latest=<time_modifier>
Description: Specify start and end times using relative or absolute time.
  • You can also use the earliest and latest attributes to specify absolute and relative time ranges for your search. Read more about this time modifier syntax in "Change the time range of your search" in the User manual.
starttime
Syntax: starttime=<string>
Description: Events must be later or equal to this time. Must match timeformat.
endtime
Syntax: endtime=<string>
Description: All events must be earlier or equal to this time.

Description

The search command enables you to use keywords, phrases, fields, boolean expressions, and comparison expressions to specify exactly which events you want to retrieve from a Splunk index(es).

Some examples of search terms are:

  • keywords: error login
  • quoted phrases: "database error"
  • boolean operators: login NOT (error OR fail)
  • wildcards: fail*
  • field values: status=404, status!=404, or status>200

Quotes and escaping characters

Generally, you need quotes around phrases and field values that include white spaces, commas, pipes, quotes, and/or brackets. Quotes must be balanced, an opening quote must be followed by an unescaped closing quote. For example:

  • A search such as error | stats count will find the number of events containing the string error.
  • A search such as ... | search "error | stats count" would return the raw events containing error, a pipe, stats, and count, in that order.

Additionally, you want to use quotes around keywords and phrases if you don't want to search for their default meaning, such as Boolean operators and field/value pairs. For example:

  • A search for the keyword AND without meaning the Boolean operator: error "AND"
  • A search for this field/value phrase: error "startswith=foo"

The backslash character (\) is used to escape quotes, pipes, and itself. Backslash escape sequences are still expanded inside quotes. For example:

  • The sequence \| as part of a search will send a pipe character to the command, instead of having the pipe split between commands.
  • The sequence \" will send a literal quote to the command, for example for searching for a literal quotation mark or inserting a literal quotation mark into a field using rex.
  • The \\ sequence will be available as a literal backslash in the command.

Unrecognized backslash sequences are not altered:

  • For example \s in a search string will be available as \s to the command, because \s is not a known escape sequence.
  • However, in the search string \\s will be available as \s to the command, because \\ is a known escape sequence that is converted to \.

Search with TERM()

Also, when specifying phrases to match, you can use the TERM() directive. 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 breaks or delimiters (such as underscores and spaces).

If you searched for the quoted phrase "error_type", Splunk ends up searching for "error" and "type" and post filtering the results. This would also include events that contained "error_type" as segments of other keywords or phrases, for example "error_type.default" or "this_error_type". If you use TERM(error_type), you force Splunk to exclude these other keywords.

Examples

The following are just a few examples of how to use the search command. You can find more examples in the Start Searching topic of the Splunk Tutorial.

Example 1: This example demonstrates key/value pair matching for specific values of source IP (src) and destination IP (dst).

src="10.9.165.*" OR dst="10.9.165.8"

Example 2: This example demonstrates key/value pair matching with boolean and comparison operators. Search for events with code values of either 10 or 29, any host that isn't "localhost", and an xqp value that is greater than 5.

(code=10 OR code=29) host!="localhost" xqp>5

Example 3: This example demonstrates key/value pair matching with wildcards. Search for events from all the webservers that have an HTTP client or server error status.

host=webserver* (status=4* OR status=5*)

Example 4: This example demonstrates how to use search later in the pipeline to filter out search results. This search defines a web session using the transaction command and searches for the user sessions that contain more than three events.

eventtype=web-traffic | transactions clientip startswith="login" endswith="logout" | search eventcount>3

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the search command.

This documentation applies to the following versions of Splunk: 4.1 , 4.1.1 , 4.1.2 , 4.1.3 , 4.1.4 , 4.1.5 , 4.1.6 , 4.1.7 , 4.1.8 , 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 View the Article History for its revisions.


Comments

This was minimal help. Until a saw the examples I did not understand any of it. After looking at the examples, I then realized how poorly everything about it is written. How do I know what src is code is, what are all my options. Besided src and code.

Rpieronek
April 28, 2011

What is the difference between "where" and "search"?

Danielbrowne
June 29, 2010

You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!