Differences between SPL and SPL2
The Search Processing Language, version 2 (SPL2) is a more concise language that supports both SPL and SQL syntax. SPL2 supports 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. Common command differences are described later in this topic.
If you are familiar with SPL, the following sections summarize the changes implemented with SPL2.
Using SPL commands in SPL2
For SPL commands that are not natively supported in SPL2, you can use one of the following alternatives to use SPL commands in your SPL2 searches:
|SPL compatibility library||A set of SPL commands implemented as SPL2 command functions.||If the SPL command and it's options are supported in the SPL compatibility library, import the library into your SPL2 module. See Compatibility library for SPL commands as functions|
|Search literal||SPL commands are enclosed in backtick ( ` ) characters and passed to splunkd.||If the SPL command is not supported in the SPL compatibility library, you can specify the SPL command in your SPL2 search by using a search literal. See Use search literals to include SPL commands in SPL2 searches in the SPL2 Search Manual.|
In SPL, there is one topic for each command that describes the syntax and shows examples.
In SPL2, there are 4 topics for each command. Here's an example:
While working with SPL2 you will 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 the search bar used with 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 inside a single module.
|SPL2 statements||SPL2 statements are searches and other types of data-related code. There are several different SPL2 statements:
|Dataset||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.
Store multiple searches in a single file
Unlike the current Search and Reporting app, an SPL2 module can contain multiple searches and other SPL2 statements in one module. This means that you can quickly switch back and forth between these searches and search results. You can create custom functions and store them in the same module with your search statements.
For example, you can create a main search and branch or extend that search into other searches, or you can create other unrelated searches in the same module. For more information, see Extend and branch search statements in the SPL2 Search Manual.
In addition, you can create custom functions, similar to SPL macros, and custom data types to use in your searches and store all of these items with your searches in a single module. For more information, see
Assigning a name to a search
To use the results from one search as the dataset in another search, you must give the original search a name. The name must start with the dollar "$" symbol. For example:
After the name, you must specify an equal symbol ( = ) and a generating command and a dataset name. For example:
$mysearch1 = from sample_data
Each search name in a module must be unique.
Valid generating commands are
The search name is like a variable, which you can refer to in subsequent searches.
For example, the name of the following search is
$prod_lookup = from sample_data where sourcetype LIKE "access_%" AND status=200 | lookup sample_products_lookup productID AS productId OUTPUTNEW product_name | fields productId, product_name
You can use the results of the
$prod_lookup search as the dataset for another search by specifying the search name where you would specify the dataset:
$prod_stats = from $prod_lookup | stats count() by product_name
For more information and examples, see Extend and branch search statements in the SPL2 Search Manual.
Common command differences
The common command differences between SPL and SPL2 are described in the following sections.
Lists must be comma-separated
If an SPL2 command needs a list of things, such as a list of fields or values, then the list must be comma-separated. In SPL, some commands required space-separated lists, while other commands required comma-separated lists.
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 = search index=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 double 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 differences
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 usage.
If you want to use SQL-like syntax with the same outcome as the
search command, you can use the
from command with a search literal. For example:
FROM main WHERE `404`
For more information, see Search literals in expressions in the SPL2 Search Manual.
From command differences
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" | stats count by action | sort action desc
$from2 = 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:
$from_example = FROM sample_data_index WHERE host="www2" GROUP BY action SELECT action, count(action) AS 'Action Count' ORDER BY action DESC
$select_example = SELECT action, count(action) AS 'Action Count' FROM sample_data_index WHERE host="www2" GROUP BY action ORDER BY action DESC
For more information about the SPL2
from command, see from command overview in the SPL2 Search Reference.
Makeresults command replaced
makeresults command has been replaced with the SPL2
results dataset function. See Overview of SPL2 dataset functions
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
Commands converted to functions
The following commands have been converted into functions in SPL2:
|cluster||Generates a cluster label, in the form of a number, for each event based on how similar the events are to each other.|
|spath||Extracts information from the structured data formats XML and JSON.|
|tojson||Returns a JSON object representation of events or search results.|
Eval expressions with stats functions
In SPL, you can embed eval expressions and functions within any of the stats functions. For example:
... | stats count(eval(method="GET")) AS GET
In SPL2, evaluation expressions are supported directly in stats functions. For example:
... | stats count(method="GET") AS GET
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:
/* */ .
Block comments can appear before, after, in the middle of your SPL statement. In this example, the block comment appears before the search statement:
/* This block comment describes the search. This searches for all of the successful web access events */ $block_comment1 = from sample_data_index where sourcetype LIKE "access_%" AND status=200
In this example, the block comment is in the middle of the search, after the
stats command and before the
eval command. To help find the comment, the word COMMENT is placed at the beginning of the block comment.
$block_comment2 = 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 /* 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 is a line comments at the end of the line:
$line_comment = from sample_data_index where like(sourcetype, "access_%") AND status=200 // Get all successful website access events.
In this example, there are line comments at the end of each line and uses the word COMMENT to help quickly find each comment:
$line_comment = from sample_data_index where like(sourcetype, "access_%") AND status=200 // COMMENT: Get all successful website access events. | lookup sample_products_lookup productID AS productId OUTPUTNEW product_name // COMMENT: 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 // COMMENT: Create counts of site views, add-to-cart actions, and purchase actions. Breaks them out by product name.
- Related information
- New features in SPL2
Built-in data types
New features in SPL2
This documentation applies to the following versions of Splunk® Cloud Services: current