Search using SPL2

From the Search page you can add, edit, and run the Search Processing Language, version 2 (SPL2) statements. See What is SPL2?.

If you are new to the Splunk search language, the Search Experience preview includes a set of sample modules to help you learn how to search your data using SPL2. See Sample modules.

How to start a search

In Search Experience, every search begins with a name, a command, and a dataset. For example:

$filter1 = FROM sample_events WHERE status=200

You can start a search by selecting the dataset you want to search, or by typing in the SPL Editor.

Start by selecting a dataset

You select a dataset to start a search statement.

• On the Search page, check the name of the dataset that you want to use and click Apply. A new search is added to the SPL Editor using the from command.
• On the Datasets page, double-click on the dataset that you want to use. A new module is opened and a search statement is started using the selected dataset.

For example, if you select the sample_events dataset, the new search statement looks like this:

$search = from sample_events

The default name of the search statement is $search. The from command is used to start the search, followed by the dataset name. While you can run this search statement as is, it is common to add a filter to a search or to limit the number of results returned.

In this example, the LIMIT clause is added to the search to specify to return only the first 10 results:

$search = from sample_events limit 10

In this example, the WHERE clause is added to filter the events and show only events where the HTTP status code is 200:

$search_2 = from sample_events where status=200

When you use the sample_events, you must set the time range to All time.

Start by typing the SPL2 syntax

You can create a search statement by typing the SPL2 into the SPL Editor panel.

1. Select a line in the SPL2 Editor and type a name for the search. See Search names.
2. Type an equal sign ( = ) and the command you want to use to start your search. See Commands you can use to start a search.

Search names

A search name is like a variable and must start with the dollar "$" symbol, followed by the name. For example: $mysearch1 or $threats_by_hour.

Names can be composed of uppercase or lowercase letters, numbers, and the underscore ( _ ) character.

Each search name in a module must be unique.

Commands you can use to start a search

You can start a search with either the from, search, or union command.

The command you use to start a search depends on what you are trying to accomplish and personal preference:

Command	Description	Example
search	Use the search command if you prefer to use Google-like searches.	$search1 = search index=sample_events host=www1
from	Use the from command if you are familiar with SQL, or want to take advantage of the enhanced power of this command. The from command can start with either the FROM clause or the SELECT clause.	$from1 = FROM sample_events WHERE host=www1 $from2 = SELECT * FROM sample_events WHERE host=www1
union	Use the union command to combine 2 or more datasets.	$union1 = union vendors1, vendors2, vendors_lookup

Run a search

1. Select the Time range for your search. To search the sample data, ensure the Global Time Range is set to All time.
2. Select the search that you want to run.
3. Click the Run button, or press Control or Command + Enter to run the search.

Cancel a search

You can cancel a running search by using the Stop button. This button appears after you click the Run button.

The power of modules

You can use a module to store groups of SPL2 statements that relate to a specific project or issue that you are working on.

Extending search statements

For example, you can retrieve specific fields from a dataset:

$method = from sample_events select _time, clientip, action, status, method

You can then use, or extend, the search results as the dataset for another search. In this example, the search statement $method is used as the dataset for a new search statement $get_stats:

$get_stats = from $method 
| stats count(method) BY status, method

You can continue to extend the use of the search statements for other searches. In this example, the first search statement $method is used as the dataset for another new search statement $get_instance:

$get_instance = FROM $method where status=404 AND method="GET"
| stats (earliest_time(_time)) AS 'First Instance'
| eval 'First Instance'=strftime('First Instance', "%Y-%m-%d %H:%M:%S")

To extend a search statement:

1. In the module outline, select a search statement.
2. Open the Options menu and select Extend.
3. Type a name for the new search statement and click Create.
4. A new search statement appears in the SPL Editor pane.

You can also type the SPL2 syntax directly in the SPL Editor pane to create the new search.

For more examples of extended searches, and to learn about branched searches, see Extend and branch search statements in the SPL2 Search Manual.

Using custom functions in search statements

You can define a custom function in a module and then use that function statement in a search statement in that module.

For example, the following function isError has one parameter $code which must be a number. The function returns a Boolean. The function includes a filter condition, returning events only where the $code is greater than or equal to 400.

/* 
This function has one parameter "$code" which must be a 
number and returns a Boolean. The function includes a filter condition, 
returning events only where the $code is greater than or equal to 400.
*/

function isError($code : number) : boolean {
  return $code >= 400 
}

/* 
You can use this function in a search statement to return events that 
match the filter conditions specified in the WHERE clause.
*/

$get_events = FROM sample_events WHERE method="GET" AND isError(status)

/*
You can extend the dataset generated by the "$get_events" search 
statement to use in another search statement.
*/

$get_method = FROM $get_events
| stats count(method) BY status, method

For more information about custom functions, see Custom eval function and Custom command functions in the SPL2 Search Reference.

Specifying time ranges

You can use one of the built-in time ranges, such as Last 4 hours, or select specific dates or a relative time. For more information see Timestamps and time ranges in the SPL2 Search Manual.

By default, the value in the time range picker is used as the time range for every search in a module. However, you can specify custom time ranges for individual searches.

Create a custom time range

1. Select the search statement that you want to apply the custom time range to.
2. On the Data tab, next to Filters, select the Add Filter icon .
3. Select Time range.
4. Select Create a new time range.
5. Specify a name for the custom time range. Names must be unique, in lowercase, and start with a letter. You can use letters, numbers, and the underscore ( _ ) character for the name of the custom time range.
6. Select a time range.
7. Select Apply.

Use an existing custom time range

1. Select the search statement that you want to apply the custom time range to.
2. On the Data tab, next to Filters, select the Add Filter icon .
3. Select Time range.
4. Select Select an existing time range and choose the time range that you want to use.
5. Select Apply.

Edit a custom time range

1. Select any search statement that uses a custom time range.
2. On the Data tab, in the Filters section, select the custom time range.
3. Next to the custom time range you want to change, select the Edit icon .
4. You can edit the name and the time range for the custom time range.
5. Select Apply.

Remove a custom time range from a specific search

When you remove a custom time range from a specific search, the global time range in the Time Range Picker is applied to the search. The custom time range is not deleted. You can still apply the custom time range to other searches in the module.

1. Select the search statement that you want to remove the custom time range from.
2. On the Data tab, in the Filters section, select the X next to the custom time range.

Delete a custom time range

1. Select any search statement that uses the custom time range.
2. On the Data tab, in the Filters section, select the custom time range.
3. Next to the custom time range, select the Edit icon .
4. Select Delete.

Search using keywords

You can search the _raw field using the Keyword search box, which appears directly below the Timeline.

You can search for an exact term or use a wildcard character ( * ) to search for part of a term. The wildcard should be used at the end of the term, for example http*.

To use the Keyword search box, type the term and press Enter.

Searching multiple datasets

You can search multiple datasets simultaneously by using the union command.

In the Search page, check the names of the datasets that you want to search and click Apply. A new search is added to the SPL Editor using the union command.

See union command overview in the SPL2 Search Reference.

Collapsing and expanding statements

Search modules can contain multiple statements. You can use the line numbers in the SPL Editor pane to collapse and expand statements:

1. In the SPL Editor pane, position your mouse pointer in the line numbers area.
2. A down chevron ( V ) appears next to statements that use multiple lines.
3. To collapse a statement into one line, click the down chevron next to that statement. A right chevron ( > ) appears on the collapsed line.
4. To expand a collapsed statement, click the right chevon next to the collapsed line.

For the list of keyboard shortcuts that you can use to collapse the active statement or collapse all statements, see Search keyboard shortcuts.

Troubleshooting SPL2 statements

There are several reasons why an SPL2 statement returns no results. There might be a syntax error or the time range might be too narrow.

Visual troubleshooting indicators

There are several visual indicators in the SPL Editor pane to identify where there is an issue with the syntax. The following table describes these indicators:

Indicator	Action	Common issues and solutions
A squiggly line appears under the syntax.	Hover over the line to see a description of the issue.	Duplicate variable assignment. There is another statement in the module with the same name. Statement names must be unique. Change the name of one of the statements.
A light bulb icon appears above the syntax.	Click on the icon to see a recommendation to resolve the issue.	Make variable unique. There is another statement in the module with the same name. Statement names must be unique. Change the name of one of the statements.

See also

Related information

What is SPL2?

Sample data

Sample modules