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) includes 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, 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.

If you are familiar with SPL, the following sections summarize the changes implemented with SPL2.

Documentation

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

Terminology

While working with SPL2 you might 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 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.


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
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: $mysearch1 or $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_stats:

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

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 = from 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 search index=main | fields 'host*', categoryId | eval 'low-categoryId'=lower(categoryId)


You can perform the same search using the SELECT clause in the from command.
For example:

FROM main SELECT 'host*', categoryId | eval 'low-category'=lower(categoryId)

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 single quotation marks. This includes the wildcard ( * ) and dash ( - ) characters.

Version Examples
SPL index=main user=ladron
SPL2 FROM main WHERE user="ladron"


search index=main user=ladron

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

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 status=200
SPL2 search index=main status=200

For more information, see search command overview.

From command

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 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" 
| sort action desc 
| stats count by action
SPL2
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.

branch command

The branch command processes one set of events or search results, in parallel, simultaneous searches. Each search branch must end with the into command.

into command

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.

thru command

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 sort command.

SPL search example Equivalent SPL2 search

index="main" action="logon"

| stats count() by host

| sort -count

FROM main WHERE action="logon"

GROUP BY host SELECT count(), host

ORDER BY count

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

dataset functions

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

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 eval command:

$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

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. 
Last modified on 12 October, 2021
PREVIOUS
Built-in data types
  NEXT
Overview of SPL2 eval functions

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