Specific differences between SPL and SPL2

There are general search and language changes, as well as command and function differences between SPL and SPL2.

There are general search and language changes, as well as command and function differences between SPL and SPL2. See:

Search and language differences

There are differences between SPL and SPL2 in the way you write and use searches. There are also differences that apply to most SPL2 commands.

There are some differences between SPL an SPL2 in the way you write and use searches. There are also differences that apply to most SPL2 commands. Some of these differences are as a result of being able to specify multiple searches in the SPL2 module editor. Other differences are to ensure consistency between the SPL2 commands.

Searches have names

When you use the SPL2 module editor UI to create and run your searches, you must assign a name to each search.

You can use named searches to refer back to a specific search and take advantage of these new SPL2 features:
FeatureDescription
Branch searchesCreate a series of chained searches that branch off of a base search, or create multiple branched searches, in parallel, off of a single base search. For more information, see Branching SPL2 searches in the SPL2 Search Manual.
SPL2 viewsUse SPL2 views, which are virtual views over physical indexes. For more information, see SPL2 views in the SPL2 Search Manual.

The search name must follow these guidelines:

  • Start with the dollar sign ( $ ).

  • Use a lowercase letter as the first character after the dollar sign.

  • Be comprised of lowercase letters, numbers, or the underscore character ( _ ). No spaces or special characters are allowed in search names.

  • Be unique within the module.

Searches can be branched to create chained searches

In the SPL2 module editor, a 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 main
where sourcetype LIKE "access_%" AND status=200
| lookup 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. In the other search, you specify the $prod_lookup search name where you would specify the dataset name. For example:

$prod_stats = from $prod_lookup
| stats count() by product_name

For more information and examples, see Branching SPL2 searches in the SPL2 Search Manual.

Lists must be comma-separated

If an SPL2 command needs a list of fields or values, then the list must be comma-separated. In SPL, some commands accept space-separated lists, while other commands require comma-separated lists.

Here's an example:
VersionExample
SPL 
... | dedup 2 source host
SPL2 
... | dedup 2 source, host

Specify command options before command arguments

In SPL, commands were inconsistent about where options were expected in the search syntax. For all SPL2 commands, the command options must be specified before command arguments.

In the following example, bins is the option and the field name, size, is the argument.

VersionExample
SPL 
... | bin size as bin_size bins=10
SPL2 
... | bin bins=10 size as bin-size

Here's another example. In this example, the SPL2 dedup command option keepempty must be specified before the list of fields clientip, productId.

$options = search index=main | dedup keepempty=true clientip, productId

Specifying field names might require double quotes

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 in SPL2.

In SPL2, field names that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in single quotation marks. This includes the wildcard ( * ) and dash ( - ) characters.

Here are several examples:
VersionExample
SPL 
index=main 
| fields host* categoryId 
| eval low-categoryId=lower(categoryId)
SPL2 search command 
$fields1 = search index=main 
| fields host* categoryId 
| eval low-categoryId=lower(categoryId)
SPL2 eval and where commands, and the WHERE clause in the from command 
$fields1 = FROM main 
SELECT 'host*', categoryId 
| eval 'low-categoryId'=lower(categoryId)
Note: You can perform the same search by moving the eval expression into the SELECT clause in the from command using either of these formats: 
$fields2 = FROM main 
SELECT 'host*', categoryId, lower(categoryId) AS 'low-category'

$fields2 = SELECT 'host*', categoryId, lower(categoryId) AS 'low-category'
FROM main

Specifying string values might require double quotes

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 in SPL2.

String values that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in double quotation marks. This quotation requirement includes strings that contain the wildcard ( * ) and dash ( - ) characters.

Here are several examples:
VersionExample
SPL 
index=main user=ladron
index=main sourcetype=access_*
SPL2 search command String values in the SPL2 search command do not need double quotation marks with the SPL2 search command:
$strings1 = search index=main user=ladron
$strings2 = search name=stewart-kao
$strings3 = search index=main sourcetype=access_*
SPL2 eval and where commands, and the WHERE clause in the from command 
$strings1 = FROM main WHERE user="ladron"
$strings2 = FROM main WHERE name="stewart-kao"
$strings3 = SELECT host, ipaddress FROM main 
WHERE sourcetype="access_*"

Use eval expressions directly in stats functions

In SPL, you can embed eval expressions and functions in any of the statistical functions. However, in SPL2 eval expressions are supported directly in statistical functions.

Here is an example:
VersionExample
SPL 
... | stats count(eval(method="GET")) AS GET
SPL2 
... | stats count(method="GET") AS GET

Concatenation operator is different

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

Here's an example:

VersionExample
SPL 
... | eval full_name = first_name." ".last_name
SPL2 
... | eval full_name = first_name+" "+last_name

Command differences

There are important differences between the search and from commands in SPL and SPL2.

There are important differences between the search command and from command in SPL and SPL2:

  • Several of the SPL commands are enhanced in SPL2, such as stats, from, and join.

  • New commands are introduced in SPL2, primarily to support curating and managing data. These include branch, into, ocsf, and thru. These new commands are described in the SPL2 Search Reference.

  • A few SPL commands have been converted to functions in SPL2, such as cluster and tojson. The SPL spath command is supported as a command and as an eval function in SPL2.

Use the following links to learn about the differences in specific commands:

Differences using the search command

The search command in SPL2 is similar to the search command in SPL. However, in some situations, the command is not implied at the beginning of a search.

For example, when you use SPL-like syntax in the Search bar, if the first expression in your SPL2 search is anything other than index=<index_name>, you must include the search command at the beginning of the search, such as in searches like search 404 or host=www3.

In the SPL2 module editor, you must always specify the search command after you specify the search name.

The following table illustrates the differences between using the search command in SPL and SPL2:

VersionExamples
SPL 
index=main
404
host=www2
SPL2 in the Search bar 
index=main
search 404
search host=www2
SPL2 in the SPL2 module editor 
$search1 = search index=main
$search2 = search 404 
$search3 = search host=www2
Note: There might be other differences using the search command, based on the feature, app, or product that you're using.

For more information, see search command: Overview and syntax in the SPL2 Search Reference.

Differences using the from command

The from command in SPL2 is substantially different than the from command in SPL. The key differences are:

  • The way you specify a dataset.

  • Support for SQL-like syntax.

With SPL you must qualify the dataset you use with the from command. In SPL2, since the search names in a module must be unique, you don't have to qualify the dataset name that you are using.

The following table shows this difference between SPL and SPL2:

VersionExample
SPL 
from savedsearch:my_search
SPL2 
$search1 = from my_search

The SPL2 from command is like the SQL SELECT command. The SPL2 from command has a flexible syntax, so you can start a search with either the FROM clause or the SELECT clause.

The following table lists the optional clauses in the order that they are supported, depending on whether you're starting your search with the FROM clause or the SELECT clause.
Start with the FROM clauseStart with the SELECT clause
  • FROM
  • JOIN
  • WHERE
  • GROUP BY
  • SELECT
  • HAVING
  • ORDER BY
  • LIMIT
  • OFFSET
  • SELECT
  • FROM
  • JOIN
  • WHERE
  • GROUP BY
  • HAVING
  • ORDER BY
  • LIMIT
  • OFFSET

The following SPL2 searches produce the same results. One starts with the SELECT clause and the other starts with the FROM clause:

Starts withExample
SELECT 
$select_example = SELECT action, count(action) AS 'Action Count' 
FROM sample_data_index 
WHERE host="www2" 
GROUP BY action 
ORDER BY action DESC
FROM 
$from_example = FROM sample_data_index 
WHERE host="www2" 
GROUP BY action 
SELECT action, count(action) AS 'Action Count' 
ORDER BY action DESC

With the SPL2 from command syntax, you can filter, sort, and select fields without piping to other commands. For example:

VersionExample
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

For more information, see from command: Overview in the SPL2 Search Reference.

Stats command includes a span option

With SPL2, you can specify a time span in the stats command. The field you use in the <by-clause> must be either the _time field, or another field in UNIX time.

For example, both of the following searches return the count of events in 5-minute intervals:
Version Example
SPL SPL does not support the span option in the stats command. You can use the bin command to specify a span.

The SPL equivalent is ...| bin _time span=5min | stats count (error) BY _time

SPL2 ...| stats count(error) BY _time span=5min

For more information, see stats command: Overview, syntax, and usage in the SPL2 Search Reference.

Case-sensitive searches

In SPL2, there is a case-sensitivity difference between the search and from commands with the values that are returned from a field-value search.

The search command in SPL and SPL2 is not case-sensitive when you use a field=value keyword in your search. This means that when you search for a value like webaccess, field values that are any combination of upper and lower case are returned, such as webAccess, WebAccess, and WEBACCESS.

With the from in SPL2, you use the WHERE clause to specify the field=value keyword, which is case-sensitive. If you search for webaccess, only the field values that are an exact match are returned.

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

There a workaround for this difference in the from command behavior, see Case-sensitive searches with field-value keywords in the SPL2 Search Reference.

SPL commands converted to SPL2 functions

The following SPL commands are converted to functions in SPL2.

cluster
The SPL cluster command is converted to an eval function in SPL2, in the informational functions category.

The SPL2 cluster function generates a cluster label, in the form of a number, for each event based on how similar the events are to each other. For more information, see cluster in the SPL2 Search Reference.

spath
The SPL spath command is available as a command and also as an eval function in SPL2. The spath function is included in the Text functions category.

The SPL2 spath function extracts information from the structured data formats XML and JSON. For more information, see spath in the SPL2 Search Reference.

tojson
The SPL tojson command is converted to an eval function in SPL2, in the Conversion functions category.

The SPL2 tojson function returns a JSON object representation of events or search results. For more information, see tojson in the SPL2 Search Reference.

Function differences

SPL2 supports all of the stats and eval functions in SPL. However, a few of the functions have changed and some SPL functions have become literals.

SPL2 supports all of the statistical and evaluation functions in SPL. However, a few of the functions have changed, and some SPL functions have become literals.

Count function

You must include parentheses when using the count function in SPL2, even when no value is specified.

The following table shows examples of using the count function in both SPL and SPL2:

VersionExample
SPL 
index=my_index 
| stats count by host
SPL2 
$count_function = search index=my_index  
| stats count() by host
Note: You can perform the same search using the GROUP BY and SELECT clauses in the from command: 
FROM my_index 
GROUP BY host 
SELECT host, count()

True function

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

The following table shows examples of using the true function in both SPL and SPL2:

VersionExample
SPL 
index=main | eval description=case(status==200,"OK", status==404, "Not found", true(), "Other")
SPL2 
$true_function = FROM main | eval description=case(status==200,"OK", status==404, "Not found", true, "Other")

False function

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

The following search uses the true, false, and null literals. 

$null1 = from prices_lookup
| lookup 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)

Null function

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

The following search uses the true, false, and null literals. In this example, the null literal hides values from certain suppliers.

$null1 = from prices_lookup
| lookup 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)