Understanding SPL2 syntax

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

SPL2 supports both SPL and SQL syntax

SPL2 is bimodal, it supports both SPL syntax and SQL syntax.

The following search uses the SPL syntax in SPL2:

search index = sec_ops sourcetype=crowdstrike:events:external | stats max(alert_score) AS score BY endpoint, host | where endpoint != "_*" | eval verified=if(alert_score=*, 1,0) | fields verified score endpoint host

The following is the same search using the SQL syntax in SPL2:

SELECT MAX(alert_score) AS score, IF (alert_score LIKE "%", 1, 0) AS verified FROM sec_ops WHERE sourcetype = 'crowdstrike:events:external' AND endpoint NOT LIKE '_%'; GROUP BY verified, score, endpoint, host

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.

Renaming fields

The AS keyword is used to rename a field using the syntax AS <field>. The name you specify for the field can't be a reserved word. For a list of the reserved words, see Reserved words in this topic.

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

Some words are reserved for the SPL2 syntax and have predefined meanings in the language.

You cannot use reserved words for identifiers such as field names, dataset names, function names, and so forth.

However, you can use a reserved word if you enclose the word in single quotation marks. For example, you can't use dedup for a field name but you can use 'dedup'.

Here's a list of the reserved words in SPL2:


after	and, AND	apply	as, AS	asc, ASC
before	between, BETWEEN	bin	branch	by, BY
dedup	desc, DESC	distinct, DISTINCT	eval	eventstats
exists, EXISTS	export	false	fit	from, FROM
function	group, GROUP	groupby, GROUPBY	having, HAVING	head
histperc	import	in, IN	inner, INNER	into
is, IS	join, JOIN	left, LEFT	like, LIKE	limit, LIMIT
lookup	not, NOT	null, NULL	offset, OFFSET	on, ON
onchange	or, OR	order, ORDER	orderby, ORDERBY	outer, OUTER
OUTPUT	OUTPUTNEW	rename	reset	return
rex	search	select, SELECT	sort	stats
streamstats	thru, through	timechart	timewrap	true
type	union, UNION	where, WHERE	while	xor, XOR

SPL2 Search Reference

Related Answers