
Understanding SPL syntax
The following sections describe the syntax used for the Splunk SPL commands. For additional information about using keywords, phrases, wildcards, and regular expressions, see Use the search command.
Required and optional arguments
SPL commands consist of required and optional arguments. Optional arguments are enclosed in square brackets [ ].
Consider this command syntax:
bin [<bins-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 [<bins-options>...]
and [AS <newfield>]
.
User input arguments
Required arguments are shown in angle brackets < >.
Consider this command syntax:
replace (<wc-string> WITH <wc-string>)... [IN <field-list>]
The user input arguments are: <wc-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:
convert [timeformat=string] (<convert-function> [AS <field>] )...
The required argument is <convert-function>
, with an option to specify a field with the [AS <field>]
clause.
Notice the ellipsis at the end of the syntax, just after the close parenthesis. In this example, the syntax that is inside the parenthesis can be repeated <convert-function> [AS <field>]
.
In the following syntax, you can repeat the <bins-options>...
.
bin [<bins-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. Parenthesis ( ) are used to group arguments.
For example in this syntax:
replace (<wc-string> WITH <wc-string>)... [IN <field-list>]
The grouped argument is (<wc-string> WITH <wc-string>)...
. This is a required set of arguments that you can repeat multiple times.
Keywords
Many commands use keywords with some of the arguments or options. Examples of keywords include:
- AS
- BY
- OVER
- WHERE
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.
Argument order
In the command syntax, the command arguments are presented in the order in which the arguments are meant to be used.
In the descriptions of the arguments, the Required arguments and Optional argument sections, the arguments are listed alphabetically. For each argument, there is a Syntax and Description. Additionally, for Optional arguments, there might be a Default.
Boolean values
In the values for a argument, where Boolean <bool> values are required, the documentation specifies 'true' or 'false'. Other variations are accepted in commands. For example, for 'true' you can also use 't', 'T', 'TRUE', and '1'.
Boolean operators
When a boolean operator is included in the syntax of a command, you must always specify the operator in uppercase. Boolean operators include:
- AND
- OR
- NOT
To learn more about the order in which boolean expressions are evaluated, along with some examples, see Boolean expressions in the Search Manual.
BY clauses
A <by-clause> and a <split-by-clause> are not the same argument.
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 [<bins-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
The <wc-field>
argument indicates that you can use wild card characters when specifying field names. For example, if you have a set of fields that end with "log" you can specify *log
to return all of those fields.
If you use a wild card character in the middle of a value, especially as a wild card for punctuation, the results might be unpredictable.
PREVIOUS Welcome to the Search Reference |
NEXT How to use this manual |
This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.13, 6.2.14, 6.2.15
Feedback submitted, thanks!