Differences between SPL and SPL2
The Search Processing Language, version 2 (SPL2) includes the most popular commands from SPL, such as
- Several of the SPL commands are enhanced in SPL2, such as
- Several SPL commands have been converted to functions in SPL2, such as
- SPL2 introduces a few new commands, including
Command-specific differences are described in the
usage topic for each SPL2 command.
If you are familiar with SPL, the following sections summarize the changes implemented with SPL2.
In SPL, there is one topic for each command that describes the syntax and shows examples. In SPL2, there are four topics for each command. Here's an example:
- search command overview
- search command syntax details
- search command usage
- search command examples
While working with SPL2 you might encounter a few new terms and concepts, which are described in the following table:
|Module||A module is like a file that contains one or more related SPL2 statements. Unlike SPL, a module can contain multiple searches and other SPL2 statements in one place. This means that you can quickly switch back and forth between the searches and search results.
|SPL2 statements||SPL2 statements are searches and other types of data-related code. There are several different SPL2 statements:
|Datasets||A dataset is a collection of data that you want to search or that contains the results from a search. There are different kinds of datasets, including indexes, lookups, and search results.|
For more information, see Modules and SPL2 statements in the SPL2 Search Manual.
Searches must have a name
Every SPL2 search statement must begin with a name, a command, and a dataset. The name must start with the dollar "$" symbol, followed by the name. For example:
$threats_by_hour. The name is like a variable, which you can then refer to in subsequent searches.
For example, you can create one search and use the results of that search as a dataset for another search by specifying the search name. In the following example, the first search,
$prod_lookup, is used as the dataset for the second search
$prod_lookup = from sample_data_index where sourcetype LIKE "access_%" AND status=200 | lookup sample_products_lookup productID AS productId OUTPUTNEW product_name | fields productId, product_name $prod_stats = from $prod_lookup | stats count() by product_name
Each search name in a module must be unique.
Common command differences
The common command differences are described below.
Lists must be comma-separated
If a command needs a list of things, such as a list of fields or values, then the list must be comma-separated. Here's an example:
Options before arguments
In SPL, commands were inconsistent about where options were expected in search syntax. In SPL2, command options must be specified before command arguments.
In this example,
bins is the option and the field name,
size, is the argument.
In the following SPL2 example, the
dedup command option
keepempty must be specified before the list of fields.
$options = from sample_data_index | dedup keepempty=true clientip, productId
In SPL2, field names that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character, need single quotation marks. This includes the wildcard ( * ) and dash ( - ) characters.
This difference applies to the
eval commands and the WHERE clause in the
from command. It does not apply to the
String values that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character, need single quotation marks. This includes the wildcard ( * ) and dash ( - ) characters.
The concatenation operator has changed.
In SPL, the concatenation operator is the period ( . ) character. In SPL2, the concatenation operator is the plus ( + ) symbol.
search command in SPL2 works like it does in SPL, but is no longer implied at the beginning of a search.
You must specify the
search command explicitly at the beginning of a search:
For more information, see search command overview.
from command in SPL2 is substantially different than the
from command in SPL.
With SPL you have to qualify the dataset. In SPL2, since the names of items in a module must be unique, you don't have to qualify the dataset name.
from command is more like the SQL SELECT command. It has these clauses: FROM, JOIN, WHERE, GROUP BY, SELECT, ORDER BY, LIMIT, and OFFSET.
With SPL2 you can filter, sort, and project with the
from command, without piping to other commands:
from savedsearch:my_search | where host="www2" | sort action desc | stats count by action
from my_search where host="www2" group by action select action, count(action) order by action desc
You can start the
from command with either the FROM clause or the SELECT clause. The clauses can be specified in uppercase or lowercase.
The following SPL2 searches produce the same results. One starts with the FROM clause and the other starts with the SELECT clause:
$with_from = FROM sample_data_index WHERE host="www2" GROUP BY action SELECT action, count(action) ORDER BY action DESC
$with_select = SELECT count(), host, _time FROM sample_data_index WHERE like(sourcetype, "access_%") GROUP BY host, span(_time, 2h) HAVING count > 10 ORDER BY count DESC
For more information about the SPL2
from command, see from command overview in the SPL2 Search Reference.
New commands in SPL2
SPL2 introduces a few new commands.
The branch command processes one set of events or search results, in parallel, simultaneous searches. Each search branch must end with the
The into command appends to or replaces the contents of a dataset in the search pipeline. The
into command is a terminating command. Use the
thru command if you want to pass data into another command in the search pipeline.
The thru command writes data to a writeable dataset and then passes the same data to the next command in the search pipeline.
SPL2 commands that replace SPL commands
The clauses in the SPL2
from command replace the need for many SPL commands, as shown in the following table:
|SPL command||SPL2 command|
|search, savedsearch, mstats, inputlookup ...||from <dataset> [ as <alias>]|
|join, lookup||from <dataset1> as <alias1> join <dataset2> as <alias2> on <constraint>|
|search, where||from <dataset> where <filter>|
|stats||from <dataset> ... group by <fields>|
|eval, fields||from <dataset> ... select <expressions>|
|search, where||from <dataset> ... having <post-filter>|
|sort||from <dataset> ... orderby <fields>|
|streamstats + where||from <dataset> ... offset <integer>|
|head||from <dataset> ... limit <integer>|
Here's an example of an SPL search converted into SPL2. The clauses in the SPL2
from command replace the implied SPL
search command, the
stats command, and the
|SPL search example||Equivalent SPL2 search|
All of the functions in SPL are supported in SPL2. A few functions have changed and others have become literals.
count function must have parenthesis even when no value is specified.
You can perform the same search using the GROUP BY and SELECT clauses in the
The 'true()' function is replaced with a literal. Use 'true' instead.
false and null functions
false() function is replaced with a literal. Use
null() function is replaced with a literal. Use
This search uses the
null literals. The
null literal hides values from certain suppliers.
$null1 = from sample_prices_lookup | lookup sample_products_lookup productID AS productId OUTPUTNEW supplierID | eval onsale = if(case(supplierID="PMG-KOR", true, supplierID="BG-IRE", true, true, false) ,"yes", "no") | eval show_price = if(onsale="yes", sale_price, null) | fields product_name, productId, price, show_price, supplierID
makeresults command has been replaced with the SPL2
results dataset function. See Overview of SPL2 dataset functions
Comments in searches
The tagging for comments has changed in SPL2. In SPL, backtick characters ( ``` ) are used to add comments to searches.
In SPL2, there are 2 types of comments in SPL2: block comments and line comments. For more information, see Using comments in SPL2 in the SPL2 Search Manual.
Block comments use this tagging:
/* */ .
In this example, the block comment is in the middle of the search, after the
stats command and before the
$block_comment = from sample_data_index where sourcetype LIKE "access_%" AND status=200 | lookup sample_products_lookup productID AS productId OUTPUTNEW product_name | stats count() AS views, count(action="addtocart") AS addtocart, count(action="purchase") AS purchases by product_name, productId /*This is a block comment. The line above creates counts of site views, add-to-cart actions, and purchase actions. Breaks them out by product ID. The next line finds the ratio of site views to purchases. */ | eval cartToPurchases=(purchases/views)*100 | eval cartToPurchases=(purchases/addtocart)*100 | rename productId AS 'Product IDs', views AS 'Views', addtocart AS 'Add To Cart', purchases AS 'Purchases', product_name AS 'Products'
Line comments use this tagging:
In this example, there are line comments at the end of each line:
$line_comment = from sample_data_index where like(sourcetype, "access_%") AND status=200 // Get all successful website access events. | lookup sample_products_lookup productID AS productId OUTPUTNEW product_name // Lookup the product names based on product ID. | stats count() AS views, count(action="addtocart") AS addtocart, count(action="purchase") AS purchases by product_name, productId // Create counts of site views, add-to-cart actions, and purchase actions. Breaks them out by product name. | eval cartToPurchases=(purchases/views)*100 // Find the ratio of site views to purchases. | eval cartToPurchases=(purchases/addtocart)*100 //Find the ratio of add-to-cart actions to purchases. | rename productId AS 'Product IDs', views AS 'Views', addtocart AS 'Add To Cart', purchases AS 'Purchases', product_name AS 'Products' //Rename some table columns.
Built-in data types
Overview of SPL2 eval functions
This documentation applies to the following versions of Splunk® Cloud Services: current