Splunk® Cloud Services

SPL2 Search Reference

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Understanding SPL2 Syntax

The following sections describe the syntax used for the Search Processing Language version 2 (SPL2) commands.

Required and optional arguments

SPL2 commands consist of required and optional arguments.

  • Required arguments are shown in angle brackets < >.
  • Optional arguments are enclosed in square brackets [ ].

Consider this command syntax:

bin 
[<bin-options>...] 
<field> [AS <newfield>]

The required argument is <field>. To use this command, at a minimum you must specify bin <field>.

The optional arguments are [<bin-options>...] and [AS <newfield>].

User input arguments

Consider this command syntax:

replace (<string> WITH <string>)... [IN <field-list>]

The user input arguments are: <string> and <field-list>.

Repeating arguments

Some arguments can be specified multiple times. The syntax displays ellipsis ... to specify which part of an argument can be repeated. The ellipsis always appear immediately after the part of the syntax that you can repeat.

Consider this command:

eval <field>=<expression>["," <field>=<expression>]...

The required argument is <field>=<expression>.

For example, for one expression you would specify this:

eval <field>=<expression>

The optional arguments are inside the the square brackets. The ellipsis at the end of the syntax, just after the close square bracket, indicate that you can repeat whatever is inside the square brackets as many times as you want to.

In this example, you have the option to specify more than one field expression. Each expression must be separated by comma. For example, to specify three field expressions the syntax would look like this:

eval <field>=<expression>, <field>=<expression>, <field>=<expression>

In the following syntax, you can repeat the <bin-options>....

bin [<bin-options>...] <field> [AS <newfield>]

Grouped arguments

Sometimes the syntax must display arguments as a group to show that the set of arguments are used together or that there are alternative parts to an argument.

Parenthesis ( ) are used to group arguments.

For example, consider this syntax:

| (FROM | from) <dataset>
[ WHERE <boolean-expression> ]
[ (GROUP BY | GROUPBY | BY) [ <field>[,<field>... ]   
    | ( SPAN <field>,<int><timescale> | <field> SPAN=<int><timescale> ) ] 
[ (SELECT | SELECT DISTINCT) <expr>[,<expr>...] 
    [ (ORDER BY | ORDERBY) <field> [ ASC | DESC ] [,<field> [ASC | DESC]]... ] ]
[ LIMIT <integer> ]
[ OFFSET <integer> ]

Let's look at the GROUP BY clause.

[ (GROUP BY | GROUPBY | BY) [ <field>[,<field>... ]   
    | ( SPAN <field>,<int><timescale> | <field> SPAN=<int><timescale> ) ] 

There are several sets of parentheses.

(GROUP BY | GROUPBY | BY)
This set of parentheses is used to show that you can specify the name of the clause in 1 of 3 ways:
* GROUP BY
* GROUPBY
* BY
( SPAN <field>,<int><timescale> | <field> SPAN=<int><timescale> )
This set of parentheses is used to show that you can specify the SPAN in 1 of 2 ways:
* SPAN <field>,<int><timescale>
* <field> SPAN=<int><timescale>

Keywords

Many commands use keywords with some of the arguments or options. Examples of keywords include:

  • AS
  • BY

You can specify these keywords in uppercase or lowercase in your search. However, for readability, the syntax in the Splunk documentation uses uppercase on all keywords.

Quoted elements

If an element is in quotation marks in syntax, you must include that element in your search. The most common quoted elements are parenthesis and commas.

Consider the syntax for the head command:

head  
[keeplast = (true | false)] 
[null = (true | false)] 
[while "("<boolean-expression>")"] 
[N]

There are quotation marks on the parenthesis surrounding the boolean-expression>. This means that you must enclose the <boolean-expression> in parenthesis in your search.

In the following search example, the <eval-expression> is avg(size)/max(delay) and is enclosed in parenthesis.

... | streamstats range(_time) as timerange | head while (timerange<100)

Syntax descriptions

In the command syntax, the command options must be specified before the command arguments..

In the Syntax details section for each command, the Required arguments and Optional argument sections list the arguments alphabetically. For each argument, there is a Syntax and Description. Additionally, for Optional arguments, there might be a Default.

Logical operators

Logical operators are words that you use in an expression to search for terms that match, or don't match, a condition. The result of the expression is either TRUE or FALSE.

When a logical operator is included in the syntax of a command, you must always specify the operator in uppercase.

Supported logical operators

The supported logical operators are:

  • AND
  • OR
  • NOT
  • XOR

In addition to logical operators, there are other operators that you can use in expressions. See Predicate expressions in the SPL2 Search Manual.


BY clauses

A <by-clause> and a <split-by-clause> are not the same argument.

When you use a <by-clause>, one row is returned for each distinct value <by-clause> field. A <by-clause> displays each unique item in a separate row. Think of the <by-clause> as a grouping.

The <split-by-clause> displays each unique item in a separate column. Think of the <split-by-clause> as a splitting or dividing.

Wildcard characters ( * ) are not accepted in BY clauses.

Fields and wildcard fields

When the syntax contains <field> you specify a field name from your events.

Consider this syntax:

bin [<bin-options>...] <field> [AS <newfield>]

The <field> argument is required. You can specify that the field displays a different name in the search results by using the [AS <newfield>] argument. This argument is optional.

For example, if the field is categoryId and you want the field to be named CategoryID in the output, you would specify:

categoryId AS CategoryID

Field names and quotation marks

Field names that begin with anything other than a-z, A-Z, or the underscore ( _ ) character must be enclosed in single quotation marks ( ' ).

Field names that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in single quotation marks ( ' ). This includes the wildcard ( * ) character, the dash ( - ), and the space character.

Reserved words

The following words are reserved in SPL2 syntax and have predefined meanings in the language.

  • group
  • search
  • where

If these words are field names in your datasets, you must escape these words in your in SPL2 searches.

See also

Related information
Built-in data types
Differences between SPL and SPL2
Expressions in the SPL2 Search Manual.
Last modified on 10 June, 2021
PREVIOUS
Introduction
  NEXT
Built-in data types

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this documentation topic helpful?

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

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters