Splunk® Cloud Services

SPL2 Search Reference

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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.

This image shows two word clouds. The first word cloud shows all 145+ commands in SPL. The second word cloud shows the 20+ commands in SPL2.

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

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.

See also

Related information
New features in SPL2
Last modified on 22 June, 2023
PREVIOUS
Built-in data types
  NEXT
New features in SPL2

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters