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 stats, eval, timechart, and rex.

Several of the SPL commands are enhanced in SPL2, such as stats, from, and join.
Several SPL commands have been converted to functions in SPL2, such as cluster and spath.
SPL2 introduces a few new commands, including branch, into, and thru.

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:

Alternative	Description	Usage
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.

Documentation

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:

Terminology

While working with SPL2 you will encounter a few new terms and concepts, which are described in the following table:

Term	Description
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. In addition, you can create custom functions (like macros) and custom data types to use in your searches and store all of these items with your searches in a single module.
SPL2 statements	SPL2 statements are searches and other types of data-related code. There are several different SPL2 statements: Searches Custom functions Custom data types Imports Exports
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: $mysearch1 or $threats_by_hour.

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 search, from, select, and union.

Extending searches

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:

$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.

Keyword search differences

In SPL and SPL2, a <field>=<value> keyword search used with the search command is not case sensitive. This means that when you search for a value like webaccess, the field values that are any combination of upper and lower case are returned, such as webAccess,WebAccess, and WEBACCESS,.

However, in SPL2 a <field>=<value> keyword search used with the from command WHERE clause is case sensitive. If you search for webaccess, only the field values that are an exact match are returned.

In SPL2, the from command is supported in all SPL2 compatibility profiles - splunkd, edgeProcessor, and ingestProcessor. The search command is supported only in the splunkd profile.

In SPL2, if the field values are not an exact match the number of search results returned by a from command search will be different than the number of results returned by a search command search.

Example

For example, suppose you have the following values in the sourcetype field:

Result	sourcetype value
1	cisco_syslog
2	cisco_Syslog
3	Cisco_Syslog
4	cisco_syslog

If you use the search command to search for sourcetype="cisco_syslog", in SPL and SPL2 all 4 results are returned. However in SPL2, if you use the from command WHERE clause only 2 results are returned:

Result	sourcetype value
1	cisco_syslog
4	cisco_syslog

Workaround

To avoid this issue with the SPL2 from command, use an eval function to convert the field values to either all uppercase or all lowercase.

The following example make all of the values of the sourcetype field lowercase, then returns the events where the field values are equal to the string "cisco_syslog":

from <dataset> | where lower(sourcetype)="cisco_syslog"

You could also convert field values to uppercase and compare the values to an uppercase version of a string. For example:

from <dataset> | where upper(categoryID)=upper("strategy")

Converting the case on both sides of the expression makes the entire expression case insensitive, which matches the search command search behavior.

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:

Version	Example
SPL	`... \| dedup 2 source host`
SPL2	`... \| dedup 2 source, host`

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.

Version	Example
SPL	`... \| bin size bins=10`
SPL2	`... \| bin bins=10 size`

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

Field names

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.

Version	Examples
SPL	`index=main \| fields host* categoryId \| eval low-categoryId=lower(categoryId)`
SPL2	`$fields1 = search index=main \| fields 'host', categoryId \| eval 'low-categoryId'=lower(categoryId)` You can perform the same search by moving the eval expression into the SELECT clause in the `from` command. For example: `$fields2 = FROM main SELECT 'host', categoryId, lower(categoryId) AS 'low-category'`

String values

This difference applies to the where and eval commands and the WHERE clause in the from command. It does not apply to the search command.

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.

Version	Examples
SPL	`index=main user=ladron`
SPL2	`$strings1 = search index=main user=ladron` `$strings2 = FROM main WHERE user="ladron"` `$strings3 = search index=main \| where user="ladron"`

The concatenation operator has changed

In SPL, the concatenation operator is the period ( . ) character. In SPL2, the concatenation operator is the plus ( + ) symbol.

Version	Examples
SPL	`... \| eval full_name = first_name." ".last_name`
SPL2	`... \| eval full_name = first_name+" "+last_name`

Search command differences

The 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:

Version	Example
SPL	`index=main 404`
SPL2	`search index=main 404`

For more information, see search command usage.

SQL-like syntax

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

The 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.

Version	Example
SPL	`from savedsearch:my_search`
SPL2	`$from1 = from mysearch`

The SPL2 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:

Version	Example
SPL	from savedsearch:my_search \| where host="www2" \| stats count by action \| sort action desc
SPL2	$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

The SPL makeresults command has been replaced with the SPL2 results dataset function. See Overview of SPL2 dataset functions

Functions

All of the functions in SPL are supported in SPL2. A few functions have changed and others have become literals.

count function

The count function must have parenthesis even when no value is specified.

Version	Examples
SPL	`index=sample_data_index \| stats count by host`
SPL2	`$count_function = search index=sample_data_index \| stats count() by host` You can perform the same search using the GROUP BY and SELECT clauses in the `from` command: `FROM sample_data_index GROUP BY host SELECT host, count()`

true function

The 'true()' function is replaced with a literal. Use 'true' instead.

Version	Examples
SPL	`index=sample_data_index \| eval description=case(status==200,"OK", status==404, "Not found", true(), "Other")`
SPL2	`$true_function = FROM sample_data_index \| eval description=case(status==200,"OK", status==404, "Not found", true, "Other")`

false and null functions

The false() function is replaced with a literal. Use false instead. The null() function is replaced with a literal. Use null instead.

This search uses the true, false, and 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:

Name	Description
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

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

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 answers from Splunk Community