Search language (version 2.1 and 2.2)

Search language (version 2.1 and 2.2)

The Splunk search API is the language that both end users and other applications use to describe their search requests to the Splunk Server. Parameters can specify what to look for, how to restrict the range of a search, how to display the results, or what special actions to perform.

Syntax

Grammar

Our nomenclature comes from Google's documentation plus the minimal augmentation necessary for Splunk's specific needs.

Splunk searches consist of one more more terms in series. In man page notation:

term [term] ...

Each term takes one of these two forms.

word

or

operator::word

This term is a single word that specifies a search for the string "apache" in each event.

apache

This term is an operator::word pair that specifies a search for events whose sourcetype metadata has the value "apache."

sourcetype::apache

There are four basic types of terms.

• a string of characters to search for, such as httpd
• a metadata value to search for, such as host::mars
• a modifier that affects either the scope of the search or the format of the results, such as hoursago::1
• an special operation to be executed, such as deletesource::

Boolean operators

AND, OR and NOT, in uppercase only, are treated as Boolean logic operators that specify a logical inclusive or exclusive relationship between the terms on either side of them.

error OR (success NOT login)

Punctuation

Terms are separated by one or more space characters.

Two colons --:: -- separate the components of operator::word terms.

host::web01

A few special characters -- :: * + ++ () [] "" -- change the way terms are evaluated. Some of these are used alone, some in pairs.

host::web0*

+*error*

report::[select _user from resultstable]

These special punctuators are listed in detail below.

Precedence

Left to Right

In the case of conflicting search parameters, the rightmost term takes precedence. For example, the search below will return 10 results, not 5.

foo maxresults::5 maxresults::10

Boolean operators

The exception to left-to-right precedence are Boolean operators. They are evaluated in this order, from highest to lowest precedence:

• ( )
• OR
• AND, NOT

Special characters

 :: two colons

Two colons in a row, if preceded by a modifier, separate the modifier from its value.

maxresults::10

host::jupiter

If not preceded by a recognized modifier, colons are treated as literal search terms. The example below searches for the literal string "fe80::1," which is part of a network configuration event.

fe80::1

* asterisk

An asterisk at the start of a word matches all words that end with the rest of the term.

*log

An asterisk at the end of a word, or at the end of an operator::word pair, matches all terms that start with the preceding part of the term.

/var/log/*

host::*

The asterisk cannot be used to wildcard operators, only words. For example =source*::foo= is not supported.

+ plus sign

A plus sign at the start of a term designates the term as a literal string to be matched, free of operators or special punctuation. For example, the search below find the literal string "foo::bar*" in events.

+foo::bar*

To search for a single "+" ...

++

To search for a term that starts with a + ...

++foobar

( ) parentheses

Parentheses around a Boolean grouping enforce the precedence of that grouping over the normal Boolean precedence order.

term1 OR (term2 AND term3)

[ ] square brackets

Brackets after a report:: modifier constrain the SQL command for the report.

report::[select * from resultstable]

To search for a term that contains a [ square bracket, escape it by wrapping it in quotes

"[bar]"

" " quote marks

Quote marks around a single term without whitespace are ignored. The term within is evaluated normally.

"whatever"

Quote marks around a term that includes an operator can match whitespace in the word, if it was indexed as metadata with the space.

"username::Joe Smith"

Quote marks around multiple terms separated by whitespace are currently not supported. The search will return no results. This will change in the next major release.

"this will not work yet"

Quote marks around a left bracket "[" escape the bracket to allow searching for events that contain left brackets.

"[bar"

 !++cmd++ !++param1++ !++param2++

These idiomatic command and parameter names execute a few deliberately obscure, undocumented commands.

!++cmd++::roll

This example would change the root logging level within the Splunk Server to "debug"

!++cmd++::logchange !++param1++::root !++param2++::DEBUG

Operators

Boolean Operators

These operators are used to specify the relationships between other terms.

AND

Search strings have an implied AND between each term.

• Usage: Placed between two search terms
• Definition: Specifies that both terms must be matched within each event returned
• Example: term1 AND term2

OR

• Usage: Placed between two search terms
• Definition: Specifies that either term must be matched within each event returned
• Example: term1 OR term2

NOT

• Usage: Placed before a search term
• Definition: Specifies that the term must not be matched within each event returned
• Example: NOT term1

( )

• Usage: Placed around terms joined by Boolean operators
• Definition: Forces evaluation of the contained terms before normal Boolean precedence
• Example: term1 OR (term2 NOT term3)

Search Operators

sourcetype::

• Value: string
• Range:
• Definition: Specifies a sourcetype metadata value to match
• Example: sourcetype::apache

source::

• Value: string
• Range:
• Definition: Specifies a source metadata value to match
• Example: source::/var/log/messages

host::

• Value: string
• Range:
• Definition: Specifies a host metadata to match
• Example: host::jupiter.splunk.com

savedsplunk::

• Value: string
• Range: Must match an existing Saved Splunk name on the server
• Definition: This term is replaced by the search string of the matching Saved Splunk. The search is then evaluated normally.
• Example: savedsplunk::nightly_errors NOT host::jupiter

eventtype::

• Value: string
• Range: Either a locally-assigned event type value, such as "?14", or a global value from Splunk Base, such as "SP-CAAAEBG"
• Definition: Specifies an event type to match
• Example: eventtype::?14
• Example: eventtype::SP-CAAAEBG

tag::

• Value: string
• Range:
• Definition: Specifies an event type tag to match
• Example: tag::java

typetag::

Synonym for tag::

eventtypetag::

Synonym for tag::

maxresults::

• Value: integer
• Range: 1 or greater
• Definition: Specifies the maximum number of matching events to return
• Example: maxresults::10

All searches have a default of maxresults::10000

hosttag::

• Value: string
• Range:
• Definition: Specifies a host tag to match
• Example: hosttag::production

index::

• Value: string
• Range:
• Definition: Specifies the name of a Splunk
• Example: index::production

All searches have a default of index::default

related::

• Value: event_id ( non user enterable )
• Range:
• Definition: Specifies events that are related to the event of id event_id using inverse document frequency.
• Example: related::0:12345

relatedmaxwords::

• Value: integer
• Range: 1 or greater
• Definition: Only use the most rare N terms for the event to be related to for the idf search. The default is 5.
• Example: relatedmaxwords::2

All searches have a default of relatedmaxwords::5

relatedweight::

• Value: float
• Range: 0.1 - 10.0
• Definition: Influence the relatedness of events that have co-occurring related terms.
• Example: {{relatedweight::2.0= will make events that share more than 1 related term to be far more related that events that don't.

All searches have a default of relatedweight::1.0

delete::source::

• Value: Any indexed source
• Range:
• Definition: Delete all events with a matching source:: value.
• Example: delete::source::/var/log/messages

delete::host::

• Value: Any indexed host
• Range:
• Definition: Delete all events with a matching host:: value.
• Example: delete::host::juno

deleterestrict::host::bar

• Value: Any indexed host
• Range:
• Definition: Restrict the delete::source by host foo.
• Example: delete::source::/var/log/messages deleterestrict::host::web1 will delete all events from /var/log/messages that are from host web1

linecount::

• Value: integer
• Range: 0 or greater
• Definition: Specify the number of lines each matching event must have
• Example: linecount::42

report::

• Value: string
• Range: A SQLite SELECT command within square brackets
• Definition: Specifies a SQL select command to be run on resultstable created from the search results
• Example: report::[select * from resultstable]

server::

• Value: string
• Range:
• Definition: Specifies a Splunk Server name to match within each event
• Example: server::splunk02

similar

There is no similar modifier; it's a special syntax version of eventtype.

eventtype::?91-3

Time Operators

Time operators apply to the whole query. These two queries are equivalent.

( foo NOT bar daysago::1 ) OR ( baz NOT bat hoursago::1 )

( foo NOT bar ) ( baz NOT bat ) hoursago::1

Start time operators

starttime::

• Value: time_format ( by default %m/%d/%Y:%H:%M:%S )
• Range:
• Definition: All events must be later or equal to this time.
• Example: starttime::01/01/2001:01:01:01

startdaysago::

• Value: integer
• Range: 1 or greater
• Definition: All events must be later or equal to now - this many days
• Example: startdaysago::1

startminutesago::

• Value: integer
• Range: 1 or greater
• Definition: All events must be later or equal to now - this many minutes
• Example: startminutesago::60

starthoursago::

• Value: integer
• Range: 1 or greater
• Definition: All events must be later or equal to now - this many hours
• Example: starthoursago::6

startmonthsago::

• Value: integer
• Range: 1 or greater
• Definition: All events must be later or equal to now - this many months
• Example: startmonthsago::12

starttimeu::

• Value: integer
• Range: 1 or greater
• Definition: Specifies a start time in seconds since the Unix epoch
• Example: starttimeu::9234567891

End time operators

endtime::

• Value: time_format ( by default %m/%d/%Y:%H:%M:%S )
• Range:
• Definition: All events must be earlier or equal to this time.
• Example: endtime::12/24/2006:01:00:00

enddaysago::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: enddaysago::2

endminutesago::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: endminutesago::5

endhoursago::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: endhoursago::3

endmonthsago::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: endmonthsago::3

endtimeu::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: endtimeu::6278346234283424

timeformat::

• Value: strftime_format
• Range:
• Definition:
• Example: timeformat::%Y/%m/%d:%H:%M:%S

All searches have a default of timeformat::%m/%d/%Y:%H:%M:%S

Time span operators

Time span operators are always applied from the last time boundry set. If an endtime operator is closest to the left of a timespan operator, it will be applied to the starttime.

These two queries are equivalent.

enddaysago::1 searchtimespanhours::5

starthoursago::29 enddaysago::1

If no start time or end time operator is supplied before setting the time span an error is returned.

searchtimespanhours:

• Value: integer
• Range: 1 or greater
• Definition:
• Example: searchtimespanhours::3

searchtimespanminutes:

• Value: integer
• Range: 1 or greater
• Definition:
• Example: searchtimespanminutes::3

searchtimespandays::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: searchtimespandays::1

searchtimespanmonths::

• Value: integer
• Range: 1 or greater
• Definition:
• Example: searchtimespanmonths:2

Ago operators

daysago::

• Value: integer
• Range: 1 or greater
• Definition: Search the last N days. ( equivalent to startdaysago )
• Example: daysago::3

minutesago::

• Value: integer
• Range: 1 or greater
• Definition: Search the last N minutes. ( equivalent to startmonthsago )
• Example: minutesago::30

hoursago::

• Value: integer
• Range: 1 or greater
• Definition: Search the last N hours. ( equivalent to starthoursago )
• Example: hoursago::3

monthsago::

• Value: integer
• Range: 1 or greater
• Definition: Search the last N months. ( equivalent to startmonthsago )
• Example: monthsago::2

Date & time operators

Note that these operators operate on the exact text that was in the file so an event file from a different timezone that was timestamped as happening at 8am will not match hour::8

year::

• Value: integer
• Range: 1969 - 2036
• Definition:
• Example: year::2006

month::

• Value: string
• Range: january - december
• Definition:
• Example: month::march

mday::

• Value: integer
• Range: 1 - 31
• Definition:
• Example: mday::21

wday::

• Value: string
• Range: sunday - saturday
• Definition:
• Example: wday::thursday

hour::

• Value: integer
• Range: 0 - 23
• Definition:
• Example: hour::12

minute::

• Value: integer
• Range: 0 - 59
• Definition:
• Example: minute::23

second::

• Value: integer
• Range: 0 - 59
• Definition:
• Example: second::58

zone::

• Value: integer or "local"
• Range: -720 to 720
• Definition: Specifies a timezone to match, in minutes offset from UTC
• Example: zone::480
• Example: zone::local

• Was this topic useful?
• Post a comment