SPL to SPL2 conversion tool

The SPL to SPL2 conversion tool assists you in converting SPL to SPL2 in the pipeline editor.

How the conversion tool works

In the pipeline editor, you can use snippets of SPL in your pipelines by enclosing the snippets in backtick ( ` ) characters. These snippets of SPL are referred to as embedded SPL.

When you specify SPL in the pipeline editor, a visual indicator appears under the SPL portion of the search. The visual indicator is a squiggly line. Additionally:

  • If the SPL can be converted to SPL2, an additional Show Code Actions icon (This image shows an icon with a light bulb.) appears.
  • If there are multiple issues, if some of the SPL can't be converted to SPL2, or if there is an error in the SPL2, the Show Code Actions icon (This image shows an icon with a light bulb.) does not appear.

The following image shows a pipeline with an SPL snippet that can be converted to SPL2:

This image shows a snippet of SPL in pipeline. A squiggly line appears under the SPL snippet, and a light bulb icon appears above the snippet.

The conversion tool proposes commands and other search language suggestions. You can either accept the conversion suggestions, or type the SPL2 yourself to convert the SPL to SPL2.

Note: The converter does not convert every piece of SPL to SPL2, but makes a best effort to convert what it can.

Sample conversion messages

When SPL can be converted to SPL2, the conversion tool displays messages similar to the following: 

This piece of SPL must be converted to SPL2. Convert to SPL2 by selecting "Quick Fix", or the light bulb icon.
Convert the 'search' clause to the 'where' clause 
by selecting "Quick Fix", or the light bulb icon.

If you position your cursor over the syntax with the visual indicator, a brief explanation of the syntax issue appears along with options to view or fix the issue.

Steps to convert SPL syntax

To convert the SPL syntax to SPL2:

  1. Ensure the SPL is enclosed in backtick ( ` ) characters.
  2. Choose one of the following methods to convert the syntax:
    • Hover your cursor over the squiggly line.
    • Position your cursor anywhere in the underlined snippet an press F8.

    A description of the syntax issue appears along with the Show Code Actions icon (This image shows an icon with a light bulb.). For example:

    This image shows a pipeline that contains an SPL snippet enclosed in backtick characters that says "search message_number != 43003".

  3. Select Quick Fix to convert the syntax.

Additional SPL2 conversion information for pipelines

The following table describes how various SPL-to-SPL2 conversion issues are handled in pipelines:

Issue Description
Unsupported commands

Some SPL commands are not supported in SPL2.

In the following example, the SPL search command is not supported in pipelines. 

$pipeline = | from $source
|rex field=_raw /(%ASA|%FTD)-\d+-(?P<message_number>\d+)/ 
| search 'message-number' != 43003 
| eval vendor_name = "Cisco" 
| fields - message-number
| into $destination;

The search command can be converted to the where command.

$pipeline = | from $source
|rex field=_raw /(%ASA|%FTD)-\d+-(?P<message_number>\d+)/ 
| where 'message-number' != 43003 
| eval vendor_name = "Cisco" 
| fields - message-number
| into $destination;
search command and literal terms

Search clauses that contain literal terms without wildcards, such as search 404, are not supported with the SPL2 profiles for edgeProcessor and ingestProcessor because the search command is not supported for those profiles.

You must rewrite the syntax using the where command with the like operator and specify a field name.

For example: 

search 404

Change this search literal using the where command: 

where like(<field>, 404)
search command and filtering by an index

In pipelines, search clauses that use an index to filter data are not supported. Pipelines are processing pre-indexed data.

You must remove the search expression that filters on the index and use some other method to filter the data.

For example, this pipeline is not supported:

$pipeline = from $source | search index=threats | into $destination
search command and wildcard characters

SPL search literals that contain a wildcard character are not supported with the SPL2 profiles for edgeProcessor and ingestProcessor.

For example: 

search error*

You must manually rewrite the search clause using the where command and the like operator.

In most cases, SPL search clauses that contain a wildcard character in a field-value pair can be converted to SPL2. The conversion uses the where command and the like operator.

For example: 

search sourcetype=*.csv

Converts to: 

where like(sourcetype, "%.csv")

SPL search clauses that contain both the wildcard character ( * ) and the percent symbol ( % ) are not supported with the SPL2 profiles for edgeProcessor and ingestProcessor.

For example, the following search clause can't be converted: 

search host=my%host*

You must use the match evaluation function and specify a regular expression to convert the SPL to SPL2.

from command The from command in SPL and SPL2 are very different. The conversion tool maps the SPL from command to the SPL2 from command syntax.
TERM search directive

The TERM search directive is not supported in the SPL2 profiles for edgeProcessor and ingestProcessor. You must change the syntax and use regular expressions to replace the SPL TERM search directive syntax.

CASE search directives

The CASE search directive converts to the where command, because both the directive and command expect case-sensitivity.

Concatenation

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

To convert concatenation from SPL to SPL2, support has been added for the period ( . ) character in eval and where commands and in the from command WHERE clause.

Time modifiers The time modifiers, such as earliest, latest, starttime, and endtime, are not supported in the SPL2 profiles for edgeProcessor and ingestProcessor. If a time modifier is detected, no conversion takes place and the pipeline remains unchanged.
IN operator

Search clauses that use the IN operator are converted to the where command and the in eval function.

For example, this SPL snippet: 

search status_code IN (400, 401, 402)

Converts to this: 

where upper(status_code) IN (upper("400"), upper("401"), upper("402"))

As another example, this SPL search clause includes wildcard characters: 

search status_code IN (40*, 50*)

It converts to the where command using the like operator which uses the percent sign ( % ) wildcard character: 

where like(status_code, "40%") OR like(status_code, "50%")
spl1 command The spl1 command, which is a new SPL2 command, is not supported in the SPL2 profiles for edgeProcessor and ingestProcessor.