faiss.pkl

��T
�langchain.vectorstores.faiss�FAISS�)�}�(�embedding_function�builtins�getattr�langchain.embeddings.openai�OpenAIEmbeddings�)�}�(�__dict__�}�(�client�openai.api_resources.embedding�	Embedding�document_model_name�text-embedding-ada-002�query_model_name�h�openai_api_key�Nu�__fields_set__�__private_attribute_values__�}�ub�embed_query�R�index�N�docstore�langchain.docstore.in_memory�InMemoryDocstore�)�}�_dict�}�(�$36ba7a93-c724-4f28-8f8d-256e208153e6�langchain.docstore.document�Document�)�}�(h}�(�page_content�X�search
Description
Use the search command to retrieve events from indexes or filter the results of a previous search command in the pipeline. You can retrieve events from your indexes, using keywords, quoted phrases, wildcards, and field-value expressions. The search command is implied at the beginning of any search. You do not need to specify the search command at the beginning of your search criteria.

You can also use the search command later in the search pipeline to filter the results from the previous command in the pipeline.

The search command can also be used in a subsearch. See about subsearches in the Search Manual.

After you retrieve events, you can apply commands to transform, filter, and report on the events. Use the vertical bar ( | ) , or pipe character, to apply a command to the retrieved events.

The search command supports IPv4 and IPv6 addresses and subnets that use CIDR notation.

Syntax
search <logical-expression>

Required arguments

<expression>
Syntax: <logical-expression> | <time-opts> | <search-modifier> | NOT <logical-expression> | <index-expression>
| <comparison-expression> | <logical-expression> [OR] <logical-expression>
Description: Includes all keywords or field-value pairs used to describe the events to retrieve from the index. Include parenthesis as necessary. Use Boolean expressions, comparison operators, time modifiers, search modifiers, or combinations of expressions for this argument.

The AND operator is always implied between terms and expressions. For example, web error is the same as web AND error. Specifying clientip=192.0.2.255 earliest=-1h@h is the same as clientip=192.0.2.255 AND earliest=-1h@h. So unless you want to include it for clarity reasons, you do not need to specify the AND operator.

Logical expression options

<comparison-expression>
Syntax: <field><comparison-operator><value> | <field> IN (<value-list>)
Description: Compare a field to a literal value or provide a list of values that can appear in the field.

<index-expression>�
lookup_str��metadata�}�lookup_index�Kuh�(h3h/�h}�ub�$9b5ff9fc-5b2d-44d5-8477-dfe174da26c3�h+)�}�(h}�(h/XSyntax: <field><comparison-operator><value> | <field> IN (<value-list>)
Description: Compare a field to a literal value or provide a list of values that can appear in the field.

<index-expression>
Syntax: "<string>" | <term> | <search-modifier>
Description: Describe the events you want to retrieve from the index using literal strings and search modifiers.

<time-opts>
Syntax: [<timeformat>] (<time-modifier>)...
Description: Describe the format of the starttime and endtime terms of the search. See Time options.
 
Comparison expression options

<comparison-operator>
Syntax: = | != | < | <= | > | >=
Description: You can use comparison operators when searching field/value pairs. Comparison expressions with the equal ( = ) or not equal ( != ) operator compare string values. For example, "1" does not match "1.0".
Comparison expressions with greater than or less than operators < > <= >= numerically compare two numbers and lexicographically compare other values. See Usage.

 
<field>


<value>
 

Syntax: <string>
Description: The name of a field.

Syntax: <literal-value>
Description: In comparison-expressions, the literal number or string value of a field.
 

<value-list>
Syntax: (<literal-value>, <literal-value>, ...)
Description: Used with the IN operator to specify two or more values. For example use error IN (400, 402, 404, 406) instead of error=400 OR error=402 OR error=404 OR error=406

Index expression options

<string>
Syntax: "<string>"
Description: Specify keywords or quoted phrases to match. When searching for strings and quoted strings (anything that's not a search modifier), Splunk software searches the _raw field for the matching events or results.

<search-modifier>
Syntax: <sourcetype-specifier> | <host-specifier> | <hosttag-specifier> | <source-specifier> |�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9bfbc638-dd6f-4525-9949-f0503133c70b�h+)�}�(h}�(h/X�<search-modifier>
Syntax: <sourcetype-specifier> | <host-specifier> | <hosttag-specifier> | <source-specifier> |
<savedsplunk-specifier> | <eventtype-specifier> | <eventtypetag-specifier> | <splunk_server-specifier> Description: Search for events from specified fields or field tags. For example, search for one or a combination of hosts, sources, source types, saved searches, and event types. Also, search for the field tag, with the format: tag::<field>=<string>.
	Read more about searching with default fields in the Knowledge Manager manual.
	Read more about using tags and field aliases in the Knowledge Manager manual.

<sourcetype-specifier>
Syntax: sourcetype=<string>
Description: Search for events from the specified sourcetype field.

<host-specifier>
Syntax: host=<string>
Description: Search for events from the specified host field.

<hosttag-specifier>
Syntax: hosttag=<string>
Description: Search for events that have hosts that are tagged by the string.

<eventtype-specifier>
Syntax: eventtype=<string>
 
Description: Search for events that match the specified event type.

<eventtypetag-specifier>
Syntax: eventtypetag=<string>
Description: Search for events that would match all eventtypes tagged by the string.

<savedsplunk-specifier>
Syntax: savedsearch=<string> | savedsplunk=<string>
Description: Search for events that would be found by the specified saved search.

<source-specifier>
Syntax: source=<string>
Description: Search for events from the specified source field.

<splunk_server-specifier>
Syntax: splunk_server=<string>
Description: Search for events from a specific server. Use "local" to refer to the search head.

Time options

For a list of time modifiers, see Time modifiers for search.

<timeformat>
Syntax: timeformat=<string>
Description: Set the time format for starttime and endtime terms.
Default: timeformat=%m/%d/%Y:%H:%M:%S.

<time-modifier>
Syntax: starttime=<string> | endtime=<string> | earliest=<time_modifier> | latest=<time_modifier>�h1h2h3}�h5Kuh�(h3h/�h}�ub�$802b1255-1064-4d74-8faa-0b2bfac1003b�h+)�}�(h}�(h/X�Default: timeformat=%m/%d/%Y:%H:%M:%S.

<time-modifier>
Syntax: starttime=<string> | endtime=<string> | earliest=<time_modifier> | latest=<time_modifier>
Description: Specify start and end times using relative or absolute time.


starttime
Syntax: starttime=<string>
Description: Events must be later or equal to this time. Must match timeformat.

 
endtime


Usage
 

Syntax: endtime=<string>
Description: All events must be earlier or equal to this time.
 

The search command is an event-generating command when it is the first command in the search, before the first pipe. When the search command is used further down the pipeline, it is a distributable streaming command. See Command types.

A subsearch can be initiated through a search command such as the search command. See Initiating subsearches with search commands in the Splunk Cloud Platform Search Manual.
 
The implied search command

The search command is implied at the beginning of every search.

When search is the first command in the search, you can use terms such as keywords, phrases, fields, boolean expressions, and comparison expressions to specify exactly which events you want to retrieve from Splunk indexes. If you don't specify a field, the search looks for the terms in the the _raw field.

Some examples of search terms are:

•	keywords: error login, which is the same as specifying for error AND login
•	quoted phrases: "database error"
•	boolean operators: login NOT (error OR fail)
•	wildcards: fail*
•	field-value pairs: status=404, status!=404, or status>200


See Use the search command in the Search Manual.

Using the search command later in the search pipeline

In addition to the implied search command at the beginning of all searches, you can use the search command later in the search pipeline. The search terms that you can use depend on which fields are passed into the search command.

If the _raw field is passed into the search command, you can use the same types of search terms as you can when the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$78b35ae8-7275-4bf6-a55d-772442fb7d17�h+)�}�(h}�(h/X�If the _raw field is passed into the search command, you can use the same types of search terms as you can when the
search command is the first command in a search.

However, if the _raw field is not passed into the search command, you must specify field-values pairs that match the fields passed into the search command. Transforming commands, such as stats and chart, do not pass the _raw field to the next command in the pipeline.

Boolean expressions

The order in which Boolean expressions are evaluated with the search is:

1.	Expressions within parentheses
2.	NOT clauses
3.	OR clauses
4.	AND clauses

This evaluation order is different than the order used with the where command. The where command evaluates AND clauses before OR clauses.

Comparing two fields

To compare two fields, do not specify index=myindex fieldA=fieldB or index=myindex fieldA!=fieldB with the search command. When specifying a comparison_expression, the search command expects a <field> compared with a <value>. The search command interprets fieldB as the value, and not as the name of a field.
 
Use the where command to compare two fields.

index=myindex | where fieldA=fieldB


For not equal comparisons, you can specify the criteria in several ways.

index=myindex | where fieldA!=fieldB

or

index=myindex | where NOT fieldA=fieldB


See Difference between NOT and != in the Search Manual.

Multiple field-value comparisons with the IN operator

Use the IN operator when you want to determine if a field contains one of several values.

For example, use this syntax:
... error_code IN (400, 402, 404, 406) | ...
Instead of this syntax:
... error_code=400 OR error_code=402 OR error_code=404 OR error_code=406 | ...

When used with the search command, you can use a wildcard character in the list of values for the IN operator. For example:

... error_code IN (40*) | ...

You can use the NOT operator with the IN operator. For example:

... NOT clientip IN (211.166.11.101, 182.236.164.11, 128.241.220.82) | ...�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9a68813a-98e8-4aee-9d21-852598f1a3e3�h+)�}�(h}�(h/X�... error_code IN (40*) | ...

You can use the NOT operator with the IN operator. For example:

... NOT clientip IN (211.166.11.101, 182.236.164.11, 128.241.220.82) | ...

There is also an IN function that you can use with the eval and where commands. Wild card characters are not allowed in the values list when the IN function is used with the eval and where commands. See Comparison and Conditional functions.

CIDR matching

The search command can perform a CIDR match on a field that contains IPv4 and IPv6 addresses. Suppose the ip field contains these values:
10.10.10.12
50.10.10.17
10.10.10.23

If you specify ip="10.10.10.0/24", the search returns the events with the first and last values: 10.10.10.12 and 10.10.10.23.
 
Lexicographical order

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, this is almost always UTF-8 encoding, which is a superset of ASCII.

•	Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 70, 100 are sorted lexicographically as 10, 100, 70, 9.
•	Uppercase letters are sorted before lowercase letters.
•	Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or after letters.

You can specify a custom sort order that overrides the lexicographical order. See the blog Order Up! Custom Sort Orders.

Quotes and escaping characters

In general, you need quotation marks around phrases and field values that include white spaces, commas, pipes, quotations, and brackets. Quotation marks must be balanced. An opening quotation must be followed by an unescaped closing quotation. For example:

•	A search such as error | stats count will find the number of events containing the string error.
•	A search such as ... | search "error | stats count" would return the raw events containing error, a pipe, stats, and count, in that order.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$35b3790c-3ea9-44b7-a07b-8b7292511027�h+)�}�(h}�(h/X�•	A search such as ... | search "error | stats count" would return the raw events containing error, a pipe, stats, and count, in that order.

Additionally, you want to use quotation marks around keywords and phrases if you do not want to search for their default meaning, such as Boolean operators and field/value pairs. For example:

•	A search for the keyword AND without meaning the Boolean operator: error "AND"
•	A search for this field/value phrase: error "startswith=foo"


The backslash character ( \ ) is used to escape quotes, pipes, and itself. Backslash escape sequences are still expanded inside quotation marks. For example:

•	The sequence \| as part of a search will send a pipe character to the command, instead of having the pipe split between commands.
•	The sequence \" will send a literal quotation mark to the command, for example for searching for a literal quotation mark or inserting a literal quotation mark into a field using rex.
•	The \\ sequence will be available as a literal backslash in the command.


Unrecognized backslash sequences are not altered:

•	For example \s in a search string will be available as \s to the command, because \s is not a known escape sequence.
•	However, in the search string \\s will be available as \s to the command, because \\ is a known escape sequence that is converted to \.

Search with TERM()

You can use the TERM() directive to force Splunk software to match whatever is inside the parentheses as a single term in the index. TERM is more useful when the term contains minor segmenters, such as periods, and is bounded by major segmenters, such as spaces or commas. In fact, TERM does not work for terms that are not bounded by major breakers.
 
See Use CASE and TERM to match phrases in the Search Manual.

Search with CASE()

You can use the CASE() directive to search for terms and field values that are case-sensitive. See Use CASE and TERM to match phrases in the Search Manual.
Examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$bfb7faa1-89bb-4c5f-b2f8-d7a0a730014e�h+)�}�(h}�(h/X�Search with CASE()

You can use the CASE() directive to search for terms and field values that are case-sensitive. See Use CASE and TERM to match phrases in the Search Manual.
Examples
These examples demonstrate how to use the search command. You can find more examples in the Start Searching topic of the Search Tutorial.

1.	Field-value pair matching

This example demonstrates field-value pair matching for specific values of source IP (src) and destination IP (dst).

src="10.9.165.*" OR dst="10.9.165.8"

2.	Using boolean and comparison operators

This example demonstrates field-value pair matching with boolean and comparison operators. Search for events with code values of either 10 or 29, and any host that isn't "localhost", and an xqp value that is greater than 5.

(code=10 OR code=29) host!="localhost" xqp>5

In this example you could also use the IN operator since you are specifying two field-value pairs on the same field. The revised search is:

code IN(10, 29) host!="localhost" xqp>5

3.	Using wildcards

This example demonstrates field-value pair matching with wildcards. Search for events from all the web servers that have an HTTP client or server error status.

host=webserver* (status=4* OR status=5*)

In this example you could also use the IN operator since you are specifying two field-value pairs on the same field. The revised search is:

host=webserver* status IN(4*, 5*)

4.	Using the IN operator

This example shows how to use the IN operator to specify a list of field-value pair matchings. In the events from an access.log file, search the action field for the values addtocart or purchase.

sourcetype=access_combined_wcookie action IN (addtocart, purchase)
 
5.	Specifying a secondary search

This example uses the search command twice. The search command is implied at the beginning of every search with the criteria eventtype=web-traffic. The search command is used again later in the search pipeline to filter out the results.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$997da8e4-b23e-425b-9e61-f137c47a3af8�h+)�}�(h}�(h/X�This search defines a web session using the transaction command and searches for the user sessions that contain more than three events.

eventtype=web-traffic | transaction clientip startswith="login" endswith="logout" | search eventcount>3

6.	Using the NOT or != comparisons

Searching with the boolean "NOT"comparison operator is not the same as using the "!=" comparison. The following search returns everything except fieldA="value2", including all other fields.
NOT fieldA="value2"

The following search returns events where fieldA exists and does not have the value "value2".

fieldA!="value2"

If you use a wildcard for the value, NOT fieldA=* returns events where fieldA is null or undefined, and fieldA!=* never returns any events.

See Difference between NOT and != in the Search Manual.

7.	Using search to perform CIDR matching

You can use the search command to match IPv4 and IPv6 addresses and subnets that use CIDR notation. For example, this search identifies whether the specified IPv4 address is located in the subnet.

| makeresults | eval ip="192.0.2.56" | search ip="192.0.2.0/24"

The IP address is located in the subnet, so search displays it in the search results, which look like this.

time	ip
2020-11-19 16:43:31	192.0.2.56
Note that you can get identical results using the eval command with the cidrmatch("X",Y) function, as shown in this example.

| makeresults | eval ip="192.0.2.56" | where cidrmatch("192.0.2.0/24", ip)

Alternatively, if you're using IPv6 addresses, you can use the search command to identify whether the specified IPv6 address is located in the subnet.

| makeresults | eval ip="2001:0db8:ffff:ffff:ffff:ffff:ffff:ff99" | search ip="2001:0db8:ffff:ffff:ffff:ffff:ffff:ff00/120"

The IP address is in the subnet, so the search results look like this.

 
	
2020-11-19 16:43:31	2001:0db8:ffff:ffff:ffff:ffff:ffff:ff99
See also

Commands
iplocation lookup

Functions
cidrmatch

 














 
Introduction 
 


Introduction�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cc79abaa-17fe-4dad-bf2a-f323ee0198f7�h+)�}�(h}�(h/XO2020-11-19 16:43:31	2001:0db8:ffff:ffff:ffff:ffff:ffff:ff99
See also

Commands
iplocation lookup

Functions
cidrmatch

 














 
Introduction 
 


Introduction 
 
The Search Processing Language (SPL) is a set of commands that you use to search your data. 
 

There are two versions of SPL: SPL and SPL, version 2 (SPL2). This manual describes SPL2. SPL2 is a product-agnostic 
language that supports both SPL and SQL syntax patterns. 
 

If you are looking for information about using SPL: For Splunk Cloud Platform, see Search Reference in the Splunk 
Cloud Platform documentation. For Splunk Enterprise, see Search Reference in the Splunk Enterprise documentation. 
 

Where SPL2 is used? 
 

Several Splunk products use SPL2: 
 

• Splunk Edge Processor 
 


Splunk Data Stream Processor (DSP) uses a set of custom functions, some of which are similar to SPL2 commands and 
functions. See DSP functions by category in the Splunk Data Stream Processor Function Reference. 
 

Learning SPL2 
 

SPL2 makes the search language easier to use, removes infrequently used commands, and improves the consistency of 
the command syntax. 
 

There are two Splunk manuals that contain information about SPL2: 
 

SPL2 Search Reference 
 

command syntax, data types, and functions. 
 

SPL2 Search Manual 
 

get started searching, how to use expressions and predicates, even how to add comments to your search strings. 
 

Useful links to SPL2 documentation 
 

The following list contains links to SPL2 getting started and quick reference information: 
 

• Understanding SPL2 Syntax 
 

• SPL2 eval functions Quick Reference 
 

• Start searching using SPL2 in the SPL2 Search Manual 
• Types of expressions in the SPL2 Search Manual 
 


1 
 
• New features in SPL2 
 


Understanding SPL2 Syntax 
 
The following sections describe the syntax used for the Search Processing Language version 2 (SPL2) commands. 
 

Required and optional arguments 
 

SPL2 commands consist of required and optional arguments. 
 

• Required arguments are shown in angle brackets < >. 
 


Consider this command syntax: 
 


bin�h1h2h3}�h5Kuh�(h3h/�h}�ub�$509be07b-881a-4ae7-828f-f38be117a76a�h+)�}�(h}�(h/XRequired and optional arguments 
 

SPL2 commands consist of required and optional arguments. 
 

• Required arguments are shown in angle brackets < >. 
 


Consider this command syntax: 
 


bin 
[<bin-options>...] 
 

The required argument is <field>. To use this command, at a minimum you must specify bin <field>. 
 

The optional arguments are [<bin-options>...] and [AS <newfield>]. 
 

User input arguments 
 

Consider this command syntax: 
 

replace (<string> WITH <string>)... [IN <field-list>] 
 

The user input arguments are: <string> and <field-list>. 
 

Repeating arguments 
 

Some arguments can be specified multiple times. The syntax displays ellipsis ... to specify which part of an argument can 
be repeated. The ellipsis always appear immediately after the part of the syntax that you can repeat. 
 

Consider this command: 
 


eval <field>=<expression>["," <field>=<expression>]... 
 
The required argument is <field>=<expression>. 
 

For example, for one expression you would specify this: 
 


eval <field>=<expression> 
 
The optional arguments are inside the the square brackets. The ellipsis at the end of the syntax, just after the close 
square bracket, indicate that you can repeat whatever is inside the square brackets as many times as you want to. 
 

In this example, you have the option to specify more than one field expression. Each expression must be separated by 
comma. For example, to specify three field expressions the syntax would look like this: 
 

2 
 
eval <field>=<expression>, <field>=<expression>, <field>=<expression> 
 
In the following syntax, you can repeat the <bin-options>.... 
 

bin [<bin-options>...] <field> [AS <newfield>] 
 

Grouped arguments 
 

Sometimes the syntax must display arguments as a group to show that the set of arguments are used together or that 
there are alternative parts to an argument. 
 

Parenthesis ( ) are used to group arguments. 
 

For example, consider this syntax: 
 


| (FROM | from) <dataset> 
 

[ (GROUP BY | GROUPBY | BY) [ <field>[,<field>... ]�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8b3ed02d-4ed2-4fe3-847a-9db44b6dbb59�h+)�}�(h}�(h/X�Parenthesis ( ) are used to group arguments. 
 

For example, consider this syntax: 
 


| (FROM | from) <dataset> 
 

[ (GROUP BY | GROUPBY | BY) [ <field>[,<field>... ]   
 

[ (SELECT | SELECT DISTINCT) <expr>[,<expr>...] 
 

[ LIMIT <integer> ] 
[ OFFSET <integer> ] 
 
Let's look at the GROUP BY clause. 
 


[ (GROUP BY | GROUPBY | BY) [ <field>[,<field>... ]   
 

There are several sets of parentheses. 
 

(GROUP BY | GROUPBY | BY) 
 

* GROUP BY 
* GROUPBY 
* BY 
 

( SPAN <field>,<int><timescale> | <field> SPAN=<int><timescale> ) 
 

* SPAN <field>,<int><timescale> 
* <field> SPAN=<int><timescale> 
 

Keywords 
 

Many commands use keywords with some of the arguments or options. Examples of keywords include: 
 

• AS 
• BY 
 

You can specify these keywords in uppercase or lowercase in your search. However, for readability, the syntax in the 
Splunk documentation uses uppercase on all keywords. 
 




3 
 
Renaming fields 
 

The AS keyword is used to rename a field using the syntax AS <field>. The name you specify for the field can't be a 
reserved word. For a list of the reserved words, see Reserved words in this topic. 
 

Quoted elements 
 

If an element is in quotation marks in syntax, you must include that element in your search. The most common quoted 
elements are parenthesis and commas. 
 

Consider the syntax for the head command: 
 


head  
 

[null = (true | false)] 
 

[N] 
 
There are quotation marks on the parenthesis surrounding the boolean-expression>. This means that you must enclose 
the <boolean-expression> in parenthesis in your search. 
 

In the following search example, the <eval-expression> is avg(size)/max(delay) and is enclosed in parenthesis. 
 

... | streamstats range(_time) as timerange | head while (timerange<100) 
 

Syntax descriptions 
 

In the command syntax, the command options must be specified before the command arguments.. 
 

In the Syntax details section for each command, the Required arguments and Optional argument sections list the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f2177d58-9d6a-42c6-a195-dd3af37eb0a1�h+)�}�(h}�(h/X�In the Syntax details section for each command, the Required arguments and Optional argument sections list the 
arguments alphabetically. For each argument, there is a Syntax and Description. Additionally, for Optional arguments, 
there might be a Default. 
 

Logical operators 
 

Logical operators are words that you use in an expression to search for terms that match, or don't match, a condition. The 
result of the expression is either TRUE or FALSE. 
 

When a logical operator is included in the syntax of a command, you must always specify the operator in uppercase. 
 

Supported logical operators 
 

The supported logical operators are: 
 

• AND 
• OR 
 

• XOR 
 

In addition to logical operators, there are other operators that you can use in expressions. See Predicate expressions in 
the SPL2 Search Manual. 
 



4 
 
BY clauses 
 

A <by-clause> and a <split-by-clause> are not the same argument. 
 

When you use a <by-clause>, one row is returned for each distinct value <by-clause> field. A <by-clause> displays each 
unique item in a separate row. Think of the <by-clause> as a grouping. 
 

The <split-by-clause> displays each unique item in a separate column. Think of the <split-by-clause> as a splitting or 
dividing. 
 

Wildcard characters ( * ) are not accepted in BY clauses. 
 

Fields and wildcard fields 
 

When the syntax contains <field> you specify a field name from your events. 
 

Consider this syntax: 
 

bin [<bin-options>...] <field> [AS <newfield>] 
 

The <field> argument is required. You can specify that the field displays a different name in the search results by using 
the [AS <newfield>] argument. This argument is optional. 
 

For example, if the field is categoryId and you want the field to be named CategoryID in the output, you would specify: 
 

categoryId AS CategoryID 
 

Field names and quotation marks 
 

Field names that begin with anything other than a-z, A-Z, or the underscore ( _ ) character must be enclosed in single 
quotation marks ( ' ).�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ceafdc08-86df-4e34-b124-3cf94bdd1d6a�h+)�}�(h}�(h/X�Field names and quotation marks 
 

Field names that begin with anything other than a-z, A-Z, or the underscore ( _ ) character must be enclosed in single 
quotation marks ( ' ). 
 

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 ( * ) character, the dash ( - ), and the space character. 
 

Reserved words 
 

Some words are reserved for the SPL2 syntax and have predefined meanings in the language. 
 

You cannot use reserved words for identifiers such as field names, dataset names, function names, and so forth. 
 

However, you can use a reserved word if you enclose the word in single quotation marks. For example, you can't use 
dedup for a field name but you can use 'dedup'. 
 

Here's a list of the reserved words in SPL2: 
 


after 
 


and, 
 


apply 
 


as, 
 


asc, 
 



5 
 
AND 
 
AS 
 
ASC 
 
between, 
 
by, 
 
before 
 
bin 
 
branch 
 
BETWEEN 
 
BY 
 
desc, 
 
distinct, 
 
dedup 
 
eval 
 
eventstats 
 
DESC 
 
DISTINCT 
 
exists, 
 
from, 
 
export 
 
false 
 
fit 
 
EXISTS 
 
FROM 
 
group, 
 
groupby, 
 
having, 
 
function 
 
head 
 
GROUP 
 
GROUPBY 
 
HAVING 
 
in, 
 
inner, 
 
histperc 
 
import 
 
into 
 
IN 
 
INNER 
 
is, 
 
join, 
 
left, 
 
like, 
 
limit, 
 

IS 
 

JOIN 
 

LEFT 
 

LIKE 
 

LIMIT 
 
not, 
 
null, 
 
offset, 
 
on, 
 
lookup 
 
NOT 
 
NULL 
 
OFFSET 
 
ON 
 
or, 
 
order, 
 
orderby, 
 
outer, 
 
onchange 
 
OR 
 
ORDER 
 
ORDERBY 
 
OUTER 
 
OUTPUT 
 
OUTPUTNEW 
 
rename 
 
reset 
 
return 
 
select, 
 
rex 
 
search 
 
sort 
 
stats 
 
SELECT 
 
thru, 
 
streamstats 
 
timechart 
 
timewrap 
 
true 
 
through 
 
union, 
 
where, 
 
xor, 
 
type 
 
while 
 
UNION 
 
WHERE 
 
XOR 
 
See also 
 

Related information 
	Built-in data types 
 

Types of expressions in the SPL2 Search Manual 
Wildcards in the SPL2 Search Manual 
 





6 
 
Built-in data types 
 
SPL2 supports a set of built-in data types, such as strings, numbers, Booleans, arrays, objects, timespans, relative times, 
and datasets. All of these data types have corresponding literal syntax that you can use to represent constants in SPL�h1h2h3}�h5Kuh�(h3h/�h}�ub�$95ca7e50-9b7f-4d5f-8fee-242dd0369e64�h+)�}�(h}�(h/XPand datasets. All of these data types have corresponding literal syntax that you can use to represent constants in SPL 
expressions. See Types of expressions in the SPL2 Search Manual. 
 

Quick reference for SPL2 built-in data types 
 

The following table describes and shows examples of the built-in SPL2 data types: 
 

	Type 
name 
 


Description 
 


Examples 
 

any 
 
The default data type used when a data 
type isn't specified. Means that any data 
type is allowed. 
 

"firstname", false, 1776, -1d, 450925.123, {name:"Ticket to 
Ride", type:"competitive"} 
 

array 
 
An ordered collection of values. The 
values in the array can be a mixture of 
data types. 
 

["buttercup", "fluttershy", 3.15] 
 

boolean 
 
A Boolean value of true or false. The 
value must be lowercase. 
 

true 
 
main 
 

dataset 
 
A collection of data that you either want 
to search or that contains the results 
from a search. 
 


[{day: "sun", temp: 65}, {day: "mon", temp: 42}, {day: "tue", 
temp: 40}, {day: "wed", temp: 31}, {day: "thu", temp: 47}, 
{day: "fri", temp: 53}, {day: "sat", temp: 64}] 
 


double 
 

A double floating-point number. If the 
number is an integer, you must include 
the D suffix. 
 
56.11D 


1.2e-3D 
 
3.14F 
 
float 
 
A floating-point number. Must include 
the F suffix. 
 
-1.2e5F 
 
365 
 
int 
 
An integer number. 
 
-32 
 
log_span 
 
A logarithm-based span value. 
 
2log10 
 

long 
 
A long integer number. Must include the 
L suffix. 
 

1500000000000L 
 
object 
 
An SPL2 structured object. 
 
{name:"Settlers of Catan", type:"competitive"} 
 
regex 
 
A regular expression. 
 
/^[a-z][a-z0-9_]*/ 
 


relative_time 
 

A relative time value. See Specifying 
relative time in the SPL2 Search 
Manual. 
 
-10h@h 


earliest=-5m 
 
string 
 
A string value. 
 
"surname" 
 

7 
 
	Type 
name 
 
Description 
 
Examples 
 


"198.51.100.255" 
 

"Number of bytes" 
 
10m 
 
timespan 
 
A time span. See Specifying time spans 
in the SPL2 Search Manual. 
 
1h 
 
any 
 

The default data type that is used when a data type is not specified. 
 

Any supported data type is allowed. 
 

array�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b493c0c1-907f-4124-9d45-cf69bea6edb5�h+)�}�(h}�(h/XBA time span. See Specifying time spans 
in the SPL2 Search Manual. 
 
1h 
 
any 
 

The default data type that is used when a data type is not specified. 
 

Any supported data type is allowed. 
 

array 
 

An array is an ordered collection of values. The values in the array can be a mixture of data types. There is no option to 
specify that an array contains homogeneous array types, which are arrays where all of the values must be the same type. 
 

The format of an SPL array is similar to a JSON array: 
 

• The array must be enclosed in square brackets [ ]. 
 

• Separate each object with a comma, except for the last object. 
 


For more information about objects, see the object data type. 
 

You can use expressions and constants for the values of SPL2 arrays. 
 

Here are some array examples: 
 

Types of 
	values 
 


Examples 
 
String values 
 
["Settlers of Catan","Terraforming Mars","Ticket to Ride"] 
 
Objects 
 
[{ name: "Tower Bridge", length: 801 }, { name: "Millennium Bridge", length: 1066 }] 
 
[a+2, b-4] 
 

Expressions 
 


For examples of the types of expressions you can use, see Types of expressions in the SPL2 Search 
Manual 
 
boolean 
 

In SPL2, a Boolean value is expressed using a lowercase Boolean literal: 
 

• true 
 

8 
 
• false 
 
Uppercase, mixed case, and numeric equivalents ( 0 | 1 ) aren't valid. 
 

dataset 
 

A collection of data that you either want to search or that contains the results from a search. 
 

A dataset literal is an array of objects that you type into your search criteria, instead of specifying a dataset name. You 
can use a dataset literal anywhere you can specify a dataset name. 
 

For more information about datasets, see the following topics in the SPL2 Search Manual: 
 

• Datasets 
 


double 
 

A double data type is a signed 8-byte (64-bit) precision floating-point number. If the number is an integer, the D suffix is 
required. 
 

To specify a double number in SPL2, use the D suffix. For example: 
 

… | eval x = 1.23D 
 

In this example, the eval command sets the value of x to a double value of 1.23.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d1a6c2f4-6b4f-4c55-ba23-013510da307e�h+)�}�(h}�(h/Xarequired. 
 

To specify a double number in SPL2, use the D suffix. For example: 
 

… | eval x = 1.23D 
 

In this example, the eval command sets the value of x to a double value of 1.23. 
 

Here are some examples of double floating-point numbers: 
 


• .345 or .345D 
• 12.3 or 12.3D 
 

• 5.6e-2 or 5.6e-2D 
• 5.6E-2 or 5.6e-2 
 

SPL2 accepts double floating-point numbers expressed as exponents using either an uppercase E or lowercase e. 
 

float 
 

A float data type is a signed 4-byte (32-bit) precision floating-point number. You must include the F suffix. 
 

To specify a float number in SPL2, use the F suffix. For example: 
 

… | eval x = 1.23F 
 

In this example, the eval command sets the value of x to a float value of 1.23. 
 

Here are some examples of floating-point numbers: 
 


• 12.3F 
 

9 
 
• 5.6e-2F 
 

SPL2 accepts floating-point numbers expressed as exponents using either an uppercase E or lowercase e. 
 

int 
 

An integer data type is a positive or negative whole number. Integers don't include fractions. 
 

Here are some integer examples: 
 


• -32000 
 

log-span 
 

A logarithm-based span that consists of a coefficient and a base. The first number is the coefficient. The second number 
is the base. 
 

• The coefficient is optional. If supplied, the coefficient must be a real number greater than or equal to 1.0 and less 
	than the base. 
 


Here are some log-span examples: 
 

• 2log10 
 

long 
 

A long data type is a signed 8-byte (64-bit) integer number. You must include the L suffix. 
 

To specify a long number in SPL2, use the L suffix. For example: 
 

… | eval x = 2147483647L 
 

In this example, the eval command sets the value of x to a long value of 2147483647. 
 

Here are some examples of long numbers: 
 

• -9,223,372,036,854,775,808L 
 

object 
 

Some SPL2 commands and functions accept or return objects. The format of a SPL2 object is similar to a JSON object, 
with the exception of field names: 
 

• The object must be enclosed in curly brackets { }. 
 

• For each field-value pair, separate the field from the value with a colon.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$44391a8e-d3bd-46bc-947b-5eed08804565�h+)�}�(h}�(h/Xwith the exception of field names: 
 

• The object must be enclosed in curly brackets { }. 
 

• For each field-value pair, separate the field from the value with a colon. 
 

10 
 
• Field names that contain characters a-z, A-Z, 0-9, or the underscore ( _ ) character don't need to be quoted. Field 
	names that contain any other characters must be enclosed in either single or double quotation marks. A SPL 
	object literal is a convenient way to create JSON objects. To be JSON compatible, field names are stored 
	internally with double quotation marks. 
 

• Field values that are strings must be enclosed in double quotation marks. 
 

Here are some SPL2 object examples: 
 


• {type: "competitive", 'game-name': "Ticket to Ride"} 
 
regex 
 

A regular expression that matches patterns of characters. Splunk regular expressions are Perl Compatible Regular 
Expressions (PCRE) and use the PCRE C library. See About Splunk regular expressions in the SPL2 Search Manual. 
 

Here are some examples of regular expressions: 
 


• "^([a-z0-9_\.-]+)@([\da-z\.-]+)\.([a-z\.]{2,6})$" 
 
relative_time 
 

Relative time is time that is based on the current time, such as last 5 minutes and last hour. 
 

You define relative time in your search by using time modifiers along with a time amount integer and unit. In addition, you 
can specify a "snap-to" time which takes the relative time and rounds down to the start of the time unit. 
 

For more information about relative time, see Specifying relative time in the SPL2 Search Manual. 
 

Here are some relative time examples: 
 





• @d+12h 
 
string 
 

In SPL2, every string must be enclosed in double quotation marks. 
 

If the string itself contains a double quote, that double quote must be escaped, using a backslash ( \ ). For example, \". 
 

If the string includes a backslash, the backslash must be escaped also. For example, \\. 
 

Here are some string examples: 
 

String 
 

SPL 2 string literal 
 
Hello 
 
"Hello" 
 


11 
 
String 
 
SPL 2 string literal 
 
Hello World 
 
"Hello World"�h1h2h3}�h5Kuh�(h3h/�h}�ub�$56921fac-9010-47ad-ac8d-0fb2b302ff04�h+)�}�(h}�(h/XHere are some string examples: 
 

String 
 

SPL 2 string literal 
 
Hello 
 
"Hello" 
 


11 
 
String 
 
SPL 2 string literal 
 
Hello World 
 
"Hello World" 
 
Maria said "Hello World"    "Maria said \"Hello World\"" 
 
C:\Windows\System32 
 
"C:\\Windows\\System32" 
 
Edge \"Case 
 
"Edge \\\"Case" 
 


timespan 
 

Time spans are used to organize search results by time increments. Some SPL2 commands include an argument where 
you can specify a time span. 
 

A time span can contain two elements, a time unit and timescale: 
 

• A time unit is an integer that designates the amount of time, such as 5 or 30. 
 


When you specify a time span, the timescale is required. If you don't specify a time unit, 1 is used as the default time unit. 
For example, if you specify min, 1 minute is used. 
 

For more information about time spans, see Specifying time spans in the SPL2 Search Manual. 
 

Here are some time span examples: 
 





• 1qtr 
 
See also 
 

Related information 
 



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. 
 












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

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


Terminology 
 

While working with SPL2 you will encounter a few new terms and concepts, which are described in the following table: 
 

Term 
 

Description 
 
A module is like a file that contains one or more related SPL2 statements. Unlike SPL, a module can contain multiple searches�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e93e320e-5ccb-4975-a613-87c234409732�h+)�}�(h}�(h/XTerm 
 

Description 
 
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 inside a single module. 
 
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: 
 


13 
 
Term 
 
Description 
 
• Searches 
 
• Custom data types 
• Imports 
 


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 file. This means that you can quickly switch back and forth between these searches and search results. 
 

For example, you can create a main search and branch or extend that search into other searches Or you can create other 
related searches in the same 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. 
 

For more information about modules and statements, see New terms and concepts. 
 

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:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6ea9ecb5-4867-42e8-8ba6-af1cf5649c92�h+)�}�(h}�(h/X�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 
 

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



14 
 
$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�h1h2h3}�h5Kuh�(h3h/�h}�ub�$34275524-6055-4697-9fa4-5b9ba5983e6f�h+)�}�(h}�(h/X�$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' 
 

15 
 
Version 
 
Examples 
 

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 
 
$strings1 = search index=main user=ladron 
 


SPL2 
 


$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�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0c2a2b67-1c64-49b5-98ef-230566cd027d�h+)�}�(h}�(h/XHVersion 
 

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. 
 



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

| sort action desc 
 

$from2 = 
 

SPL2 
 

where host="www2" 
group by 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 = 
 

WHERE host="www2" 
GROUP BY action 
 

ORDER BY action DESC 
 

$select_example = 
 

FROM sample_data_index 
WHERE host="www2" 
 

ORDER BY action DESC 
 
For more information about the SPL2 from command, see from command overview in the SPL2 Search Reference. 
 





17 
 
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�h1h2h3}�h5Kuh�(h3h/�h}�ub�$07dcf688-629c-44ba-a1b2-151b64365c0f�h+)�}�(h}�(h/Xdataset 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 
 
$count_function = search index=sample_data_index | stats count() by host 
 
SPL2 
 

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 
 

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

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. 
 


18 
 
Name 
 
Description 
 

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�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f9e434b2-5070-449c-b139-a7045ff28f63�h+)�}�(h}�(h/X�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. 
 

$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 
 

product_name, productId 
 

them out by product ID. The next line finds the ratio of site views to purchases. */ 
| eval cartToPurchases=(purchases/views)*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 
 

19 
 
successful website access events.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4393f677-25de-4b5c-b7bc-e598843670d2�h+)�}�(h}�(h/X$line_comment = from sample_data_index where like(sourcetype, "access_%") AND status=200  // Get all 
 

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

product names based on product ID. 
 

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 
 
With the Search Processing Language, Version 2 (SPL2) you can perform tasks that weren't possible with SPL. 
 

SPL2 includes enhanced support for actions with and against arrays and objects. This includes support for new 
commands, functions, and expressions. 
 

New commands 
 

SPL2 introduces several new commands. 
 

branch command 
 

Use the branch command to process one set of events or search results, in parallel, simultaneous searches. Each search 
branch must end with the into command. See the branch command overview. 
 

expand command 
 

Use the expand command on a field that contains an array of values to produce a separate result row for each object in the 
array. If there are other fields in the original event, those field values are included in the new rows when the array is 
expanded. See the expand command overview. 
 

flatten command 
 

Use the flatten command on an object to convert the key-value pairs in the object into separate fields in an event. The 
flatten command can flatten only the first level of an object. See the flatten command overview. 
 

into command 
 

Use the into command to append or replace 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. See 
the into command overview. 
 




20 
 
spl1 command�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2a87558a-f7a8-42e2-b189-bcae6ef4355b�h+)�}�(h}�(h/X�terminating command. Use the thru command if you want to pass data into another command in the search pipeline. See 
the into command overview. 
 




20 
 
spl1 command 
 

Use the spl1 command to embed all or part of an SPL search into an SPL2 search. This command is useful when SPL2 
doesn't support an SPL command. See the spl1 command overview. 
 

thru command 
 

Use the thru command to write data to a writeable dataset, and then pass the same data to the next command in the 
search pipeline. See the thru command overview. 
 

New built-in functions 
 

Dataset functions 
 

Dataset functions are functions that create events to form a dataset. You can use dataset functions with any generating 
command, such as the from, join, and union commands. 
 

indexes function 
 

dataset functions. 
 

repeat function 
 

the SPL makeresults command. See Overview of SPL2 dataset functions. 
 

Evaluation functions 
 

Use evaluation functions to evaluate an expression, based on your events, and return a result. 
 

object_to_array function 
 

Conversion functions. 
 

Stats and chart functions 
 

Use statistical and charting functions to generate a calculation, such as an average or percentage, based on the fields in 
your events. 
 

dataset function 
 

functions. 
 

pivot function 
 

array functions. 
 

Custom functions and data types 
 

With SPL2, you can create custom functions and custom data types. 
 




21 
 
Custom eval functions 
 

Create your own custom eval functions to extend SPL2. Custom eval functions are user-defined functions that you declare 
in an SPL2 module. Custom functions have zero or more parameters and return a single value. See Custom eval 
functions. 
 

Custom command functions 
 

You create a custom SPL2 command by declaring a custom command function. A custom command function is a function 
that performs like a command. You can create generating and non-generating command functions. See Custom 
command functions. 
 

Custom data types�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b07ab086-b4f5-4fb8-9631-2fbaa3eecc5c�h+)�}�(h}�(h/X�that performs like a command. You can create generating and non-generating command functions. See Custom 
command functions. 
 

Custom data types 
 

You can define your own data types by using either the built-in data types or other custom data types. Data types define 
the characteristics of the data. With custom data types, you can specify a set of complex characteristics that define the 
shape of your data. See Custom data types. 
 

Field and string templates 
 

You can use field and string templates as part of eval expressions. Templates start with the dollar sign ( $ ) and use curly 
braces { } to enclose the expression. In addition, field templates must be enclosed in single quotation marks, such as 
'${expression}'. 
 

Field templates 
 

A field template generates a field name by using a template. You can use field templates in expressions in the eval 
command. Field templates must be enclosed in single quotation marks, for example '${expression}'. See Field templates 
in the SPL2 Search Manual. 
 

String templates 
 

A string template is a string literal that includes one or more embedded expressions. Use string templates when you want 
a more readable result for your formatted strings. You can use field names and functions in string templates. See String 
templates in the SPL2 Search Manual. 
 

Literals 
 

SPL2 includes the ability to specify literal values in many parts of the syntax. 
 

Array literals 
 

An array of values or a multivalue field. Arrays are enclosed in square brackets. You can specify constant values and 
expressions in array literal expressions. See Array and object literals in expressions in the SPL2 Search Manual. 
 

Dataset literals 
 

A dataset literal is an array of objects that you type into your search criteria, instead of specifying a dataset name. You 
can use a dataset literal anywhere you can specify a dataset name. See Dataset literals in the SPL2 Search Manual. 
 




22 
 
Object literals�h1h2h3}�h5Kuh�(h3h/�h}�ub�$75a81cc8-98ce-442b-b4dd-05dce2ad1e07�h+)�}�(h}�(h/XRcan use a dataset literal anywhere you can specify a dataset name. See Dataset literals in the SPL2 Search Manual. 
 




22 
 
Object literals 
 

A list of comma-separated values enclosed in curly brackets. A SPL2 object literal is a convenient way to create JSON 
objects. To be JSON compatible, internally field names are stored with double quotation marks. See Array and object 
literals in expressions in the SPL2 Search Manual. 
 

Raw string literals 
 

A string value in which the backslash character ( \ ) is not processed. Raw string literals must be preceded by the at 
symbol ( @ ) and enclosed in double quotation marks. See Types of expressions in the SPL2 Search Manual. 
 

Search literals 
 

A search literal is a predicate that you can use wherever an <expression> is used. Search literals simplify and streamline 
your search syntax. Search literals must be enclosed in backtick characters ( ` ). See Search literals in the SPL2 Search 
Manual. 
 

See also 
 

Related information 
 







































23 
 
SPL2 compatibility profiles and quick references 
 


SPL2 compatibility profiles 
 
The Search Processing Language, version 2 (SPL2) is a product-agnostic language that supports both SPL and SQL 
syntax patterns. SPL2 is designed to serve as the single entry point to the Splunk portfolio. 
 

Each product that implements SPL2 might include a subset of the commands and functions that are available in the 
language, based on what the product is designed to do. When a product uses an SPL2 command or function, the SPL2 
syntax is used. The syntax does not change for that product. 
 

An SPL2 profile maps to a set of SPL2 commands and functions that are used by a given product. 
 

Current SPL2 profiles 
 

The following table lists the SPL2 profiles: 
 


Splunk product 
 

Profile 
	name 
 


Related information 
 

Splunk Edge Processor 
 

edgeProcessor 
 

• SPL2 commands for Edge Processor pipelines 
 

Splunk Cloud Platform Search 
Experience (preview) 
 


splunkd 
 

The splunkd profile is currently used by only the Splunk Cloud Platform Search Experience�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0cb08f12-5e9e-46c4-bc96-b5e41bd52985�h+)�}�(h}�(h/Xc• SPL2 commands for Edge Processor pipelines 
 

Splunk Cloud Platform Search 
Experience (preview) 
 


splunkd 
 

The splunkd profile is currently used by only the Splunk Cloud Platform Search Experience 
product, which is in preview. See Getting started with the Search Experience preview. 
 
See also 
 

Compatibility Quick Reference for SPL2 commands 
Compatibility Quick Reference for SPL2 evaluation functions 
 


Compatibility Quick Reference for SPL2 commands 
 
An SPL2 profile maps to a set of SPL2 commands and functions that are used by a given product. See SPL2 compatibility 
profiles. 
 

The following table shows which SPL2 commands are supported for each product profile: 
 


	SPL2 
Command 
 


Description 
 


splunkd 
	profile 
 


1 
 

	edge 
Processor 
 

bin 
 

Puts continuous numerical values into discrete sets, or bins. 
 

Yes 
 

branch 
 
Processes one set of events or search results, in parallel, in two or more branches. Each 
branch must end with the into command. 
 

Yes 
 

dedup 
 
Removes the events that contain an identical combination of values for the fields that you 
specify. 
 

Yes 
 



24 
 
	SPL2 
Command 
 

Description 
 
splunkd 
	profile 
 
1 
 
	edge 
Processor 
 

eval 
 

Calculates an expression and puts the resulting value into a search results field. 
 

Yes 
 

Yes 
 

eventstats 
 
Generates summary statistics from fields in your events and saves those statistics into a new 
field. 
 

Yes 
 
expand 
 
Produce a separate result row for each object in an array that is in a field. 
 
Yes 
 
Yes 
 
fields 
 
Keeps or removes fields from search results based on the list of fields that you specify. 
 
Yes 
 
Yes 
 

fieldsummary 
 
Calculates summary statistics for one or more fields in your events, displayed as a results 
table. 
 

Yes 
 

flatten 
 
Converts the key-value pairs in the object into separate fields in an event. Flattens only the first 
level of an object. 
 

Yes 
 

Yes 
 
Retrieves data from a dataset, such as an index, metric index, lookup, view, or job. 
 
from 
 

The from command has a flexible syntax, which enables you to start a search�h1h2h3}�h5Kuh�(h3h/�h}�ub�$38ad0ea6-c80b-4edc-9372-6c6bd20528f2�h+)�}�(h}�(h/X!level of an object. 
 

Yes 
 

Yes 
 
Retrieves data from a dataset, such as an index, metric index, lookup, view, or job. 
 
from 
 

The from command has a flexible syntax, which enables you to start a search 
with either the FROM clause or the SELECT clause. 
 
Yes 
 

head 
 
Returns the first search results, in search order, based on the <limit> specified. For historical 
searches, returns the most recent events. For real-time searches, searches the first captured 
events. 
 

Yes 
 

into 
 
Appends to or replaces the contents of a dataset in the search data pipeline. The dataset must 
be a writeable dataset, also referred to as a dataset sink. 
 

Yes 
 
join 
 
Combines the results from two datasets by using one or more common fields. 
 
Yes 
 
lookup 
 
Invokes field value lookups. 
 
Yes 
 

mvexpand 
 
Expands the values of a multivalue field into separate events, one event for each value in the 
multivalue field. 
 

Yes 
 

Yes 
 
rename 
 
Renames one or more fields. 
 
Yes 
 
Yes 
 
reverse 
 
Reverses the order of the search results. 
 
Yes 
 

rex 
 

Use to either extract fields using regular expression named groups, or replace or substitute 
characters in a field using sed expressions. 
 
Yes 
using 
PCRE 
 

Yes 
 
search 
 
Retrieve events from indexes or filter the results of a previous search command in the pipeline. 
 
Yes 
 

select 
 
See the from command. The SELECT clause is part of the from command. You can start a 
search with the SELECT clause. 
 

Yes 
 
sort 
 
Sorts all of the results by the specified fields. 
 
Yes 
 

spl1 
 
Embed all or part of an SPL search into an SPL2 search. The spl1 command supports two 
syntaxes: backtick ( ` ) character syntax and explicit spl1 command syntax. 
 

Yes 
 
stats 
 
Calculates aggregate statistics such as average, count, and sum, over the results set. 
 
Yes 
 
streamstats 
 
Adds a cumulative statistical value to each search result as each result is processed. 
 
Yes 
 

thru 
 
Writes data to a writeable dataset and then passes the same data to the next command in the�>

h1h2h3}�h5Kuh�(h3h/�h}�ub�$59a91365-dff1-471f-bca6-f1ea92311ce0�h+)�}�(h}�(h/XuAdds a cumulative statistical value to each search result as each result is processed. 
 
Yes 
 

thru 
 
Writes data to a writeable dataset and then passes the same data to the next command in the 
search string. By default, the thru command appends data to the dataset. 
 

Yes 
 



25 
 
	SPL2 
Command 
 

Description 
 
splunkd 
	profile 
 
1 
 
	edge 
Processor 
 

timechart 
 

Creates a time series chart with corresponding table of statistics. 
 

Yes 
 

timewrap 
 
Compare data over a specific time period, such as day-over-day or month-over-month, or 
multiple time periods, such as a two week period over another two week period. 
 

Yes 
 

union 
 
Merges the results from two or more datasets into one dataset. One dataset can be piped into 
the union command and merged with a second dataset. 
 

Yes 
 
where 
 
Filters search results based on the outcome of a Boolean expression. 
 
Yes 
 
Yes 
 
 The splunkd profile is currently used by only the Splunk Cloud Platform Search Experience product, which is in preview. 
 

See also 
 

Additional compatibility information 
 

SPL2 compatibility profiles 
 

Edge Processor information 
 

Regular expression syntax for Edge Processor pipelines 
 

SPL2 information 
 

Understanding SPL2 Syntax 
 


Compatibility Quick Reference for SPL2 evaluation functions 
 
An SPL2 profile maps to a set of SPL2 commands and functions that are used by a given product. See SPL2 compatibility 
profiles. 
 

The following table shows which SPL2 evaluation functions are supported for each product profile: 
 


Supported functions and syntax 
 


Description 
 


1 
 

	edge 
Processor 
 
abs(<num>) 
 
Returns the absolute value of a number. 
 
Yes 
 
acos(<x>) 
 
Computes the arc cosine of x. 
 
Yes 
 
acosh(<x>) 
 
Computes the arc hyperbolic cosine of x. 
 
Yes 
 
asin(<x>) 
 
Computes the arc sine of x. 
 
Yes 
 
asinh(<x>) 
 
Computes the arc hyperbolic sine of x. 
 
Yes 
 
atan(<x>) 
 
Computes the arc tangent of x. 
 
Yes 
 
atan2(<y>,<x>) 
 
Computes the arc tangent of y,x. 
 
Yes 
 
atanh(<x>) 
 
Computes the arc hyperbolic tangent of x. 
 
Yes 
 


26 
 
Supported functions and syntax�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d625aa5e-ecad-4c70-ac89-a5db66398df0�h+)�}�(h}�(h/X�atan(<x>) 
 
Computes the arc tangent of x. 
 
Yes 
 
atan2(<y>,<x>) 
 
Computes the arc tangent of y,x. 
 
Yes 
 
atanh(<x>) 
 
Computes the arc hyperbolic tangent of x. 
 
Yes 
 


26 
 
Supported functions and syntax 
 
Description 
 
splunkd 
 
	edge 
Processor 
 

case(<condition>,<value>, ...) 
 

Accepts alternating conditions and values. Returns the first value 
for which the condition evaluates to TRUE. 
 

Yes 
 

Yes 
 
ceiling(<num>)or ceil(<num>) 
 
Rounds a number up to the next highest integer. 
 
Yes 
 

cidrmatch(<cidr>,<ip>) 
 
Returns TRUE or FALSE based on whether an IP address 
matches a CIDR notation. 
 

Yes 
 

Yes 
 

cluster(<field>,<threshold>,<match>,<delims>) 
 
Generates a cluster label, in the form of a number, for each event 
based on how similar the events are to each other. 
 

Yes 
 

coalesce(<values>) 
 
Takes one or more values and returns the first value that is not 
NULL. 
 

Yes 
 
cos(<x>) 
 
Computes the cosine of an angle of x radians. 
 
Yes 
 
cosh(<x>) 
 
Computes the hyperbolic cosine of x radians. 
 
Yes 
 

exact(<expression>) 
 
Returns the result of a numeric eval calculation with a larger 
amount of precision in the formatted output. 
 

Yes 
 
exp(<num>) 
 
Returns the exponential function e  of a number. 
 
Yes 
 
floor(<num>) 
 
Rounds a number down to the nearest whole integer. 
 
Yes 
 
hypot(<x>,<y>) 
 
Computes the hypotenuse of a triangle. 
 
Yes 
 

if(<predicate>,<true_value>,<false_value>) 
 
If the <predicate> expression evaluates to TRUE, returns the 
<true_value>. Otherwise the function returns the 
<false_value>. 
 

Yes 
 

Yes 
 

in(<value>,<list>) 
 
Returns TRUE if one of the values in the list matches a value that 
you specify. 
 

Yes 
 

Yes 
 

ipmask(<mask>,<IP>) 
 
Generates a new masked IP address by applying a mask to a 
IPv4 address. 
 

Yes 
 

Yes 
 
isbool(<value>) 
 
Returns TRUE if the value is Boolean. 
 
Yes 
 
Yes 
 
isint(<value>) 
 
Returns TRUE if the value is an integer. 
 
Yes 
 
Yes 
 
isnotnull(<value>) 
 
Returns TRUE if the value is not NULL. 
 
Yes 
 
Yes 
 
isnull(<value>) 
 
Returns TRUE if the value is NULL. 
 
Yes 
 
Yes 
 
isnum(<value>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e96dfd74-cd19-43e6-adb8-ecc40c366caa�h+)�}�(h}�(h/X�Yes 
 
Yes 
 
isnotnull(<value>) 
 
Returns TRUE if the value is not NULL. 
 
Yes 
 
Yes 
 
isnull(<value>) 
 
Returns TRUE if the value is NULL. 
 
Yes 
 
Yes 
 
isnum(<value>) 
 
Returns TRUE if the value is a number. 
 
Yes 
 
Yes 
 
isstr(<value>) 
 
Returns TRUE if the value is a string. 
 
Yes 
 
Yes 
 
json_append(<json>, <path_value_pairs>) 
 
Appends elements to the contents of a valid JSON object. 
 
Yes 
 
Yes 
 
json_array(<values>) 
 
Creates a JSON array using a list of values. 
 
Yes 
 
Yes 
 
json_array_to_mv(<json_array>, <boolean>) 
 
Maps the elements of a JSON array to a multivalued field. 
 
Yes 
 
Yes 
 

json_extend(<json>, <path_value_pairs>) 
 
Extends the contents of a valid JSON object with the values of an 
array. 
 

Yes 
 

Yes 
 
json_extract(<field>,<paths>) 
 
Returns a value from a field and zero or more paths. The value is 
returned in either a JSON array, or a Splunk software native type 
 
Yes 
 
Yes 
 


27 
 
Supported functions and syntax 
 
Description 
 
splunkd 
 
	edge 
Processor 
 


json_extract_exact(<json>, <keys>) 
 

Returns Splunk software native type values from a piece of 
JSON by matching literal strings in the event and extracting the 
strings as keys. 
 


Yes 
 


Yes 
 

json_keys(<json>) 
 
Returns the keys from the key-value pairs in a JSON object. The 
keys are returned as a JSON array. 
 

Yes 
 

Yes 
 
json_object(<key>,<value>,...) 
 
Creates a new JSON object from members of key-value pairs. 
 
Yes 
 
Yes 
 

json_set(<field>,<path_value_pairs>) 
 
Inserts or overwrites values for a JSON node with the path and 
value pairs provided and returns an updated JSON object. 
 

Yes 
 

Yes 
 

json_set_exact(<json>, <key_value_pairs>) 
 
Generates or overwrites a JSON object using the key-value pairs 
specified. 
 

Yes 
 

Yes 
 

json_valid(<field>) 
 
Evaluates whether a JSON object uses valid JSON syntax and 
returns either TRUE or FALSE. 
 

Yes 
 
len(<str>) 
 
Returns the character length of a string. 
 
Yes 
 
Yes 
 
like(<str>,<pattern>) 
 
Returns TRUE if the string value matches the pattern. 
 
Yes 
 
Yes 
 
ln(<num>) 
 
Returns the natural logarithm of a number. 
 
Yes�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2e1d32f6-aa26-458d-a053-3d2cf642278c�h+)�}�(h}�(h/XuYes 
 
Yes 
 
like(<str>,<pattern>) 
 
Returns TRUE if the string value matches the pattern. 
 
Yes 
 
Yes 
 
ln(<num>) 
 
Returns the natural logarithm of a number. 
 
Yes 
 

log(<num>,<base>) 
 
Returns the logarithm of a number using a base. The base is 
optional, and if omitted the log function uses base 10. 
 

Yes 
 
lower(<str>) 
 
Converts a string to lowercase. 
 
Yes 
 
Yes 
 
ltrim(<str>,<trim_chars>) 
 
Removes the trim characters from the left side of the string. 
 
Yes 
 
Yes 
 

match(<str>,<regex>) 
 

Returns TRUE if the regular expression finds a match against 
any substring of the string value. Otherwise returns FALSE. 
 
Yes 
using 
PCRE 
 

Yes 
 
max(<values>) 
 
Returns the maximum of the string or numeric values. 
 
Yes 
 
md5(<str>) 
 
Computes and returns the MD5 hash of a string value. 
 
Yes 
 
min(<values>) 
 
Returns the minimum of the string or numeric values. 
 
Yes 
 
mvappend(<values>) 
 
Returns a single multivalue result from a list of values. 
 
Yes 
 

mvcount(<mv>) 
 
Returns the count of the number of values in the specified 
multivalue field. 
 

Yes 
 
mvdedup(<mv>) 
 
Removes all of the duplicate values from a multivalue field. 
 
Yes 
 

mvfilter(<predicate>) 
 
Filters a multivalue field based on a predicate expression. The 
expression can reference only one field. 
 

Yes 
 

mvfind(<mv>,<regex>) 
 
Returns the index for the first value in a multivalue field that 
matches a regular expression. 
 

Yes 
 

Yes 
 

mvindex(<mv>,<start>,<end>) 
 
Returns a subset of the multivalue field using the start and end 
index values. 
 

Yes 
 

Yes 
 

mvjoin(<mv>,<delim>) 
 
Concatenates the individual values within the multivalue field 
using the value of the delimiter as a separator. 
 

Yes 
 

Yes 
 
mvrange(<start>,<end>,<step>) 
 
Yes 
 

28 
 
Supported functions and syntax 
 
Description 
 
splunkd 
 
	edge 
Processor 
 
Creates a multivalue field based on a range of specified 
numbers. 
 
mvsort(<mv>) 
 
Returns the values of a multivalue field sorted lexicographically. 
 
Yes 
 


mvzip(<mv_left>,<mv_right>,<delim>) 
 
Combines the values in two multivalue fields. Stitches together�h1h2h3}�h5Kuh�(h3h/�h}�ub�$79f38ead-5fb1-4325-81ca-ac1faa51aa16�h+)�}�(h}�(h/XZnumbers. 
 
mvsort(<mv>) 
 
Returns the values of a multivalue field sorted lexicographically. 
 
Yes 
 


mvzip(<mv_left>,<mv_right>,<delim>) 
 
Combines the values in two multivalue fields. Stitches together 
the first value in each field, then the second value in each field, 
and so on. The delimiter is used to specify a delimiting character 
to join each pair of values. 
 


Yes 
 
mv_to_json_array(<field>,<infer_types>) 
 
Maps the elements of a multivalue field to a JSON array. 
 
Yes 
 
now() 
 
Returns the time that the search was started. 
 
Yes 
 
null() 
 
This function takes no arguments and returns NULL. 
 
Yes 
 

nullif(<value1>,<value2>) 
 
Compares two values and returns NULL if <value1> = <value2>. 
Otherwise it returns <value1>. 
 

Yes 
 
object_to_array(<object>,<key>,<value>) 
 
Converts data that is in an object format into an array format. 
 
Yes 
 
pi() 
 
Returns the constant pi to 11 digits of precision. 
 
Yes 
 
pow(<num>,<exp>) 
 
Returns a number to the power of the exponent. 
 
Yes 
 

printf(<format>,<values>) 
 
Builds a string value, based on a string format and the values 
specified. 
 

Yes 
 
random() 
 
Returns a pseudo-random integer ranging from 0 to 2 
 
Yes 
 

relative_time(<time>,<specifier>) 
 
Takes a UNIX time and a relative time specifier and returns the 
UNIX time value of the specifier applied to the time. 
 

Yes 
 

Yes 
 


replace(<str>,<regex>,<replacement>) 
 

Substitutes the replacement string for every occurrence of the 
regular expression in the string. 
 
Yes 
using 
PCRE 
 

Yes 
 

round(<num>,<precision>) 
 
Returns a number rounded to the decimal places specified by the 
precision. The default is to round to an integer. 
 

Yes 
 
rtrim(<str>,<trim_chars>) 
 
Removes the trim characters from the right side of the string. 
 
Yes 
 
Yes 
 
searchmatch(<search_str>) 
 
Returns TRUE if the event matches the search string. 
 
Yes 
 

sha1(<str>) 
 
Computes and returns the secure hash of a string value, based 
on the FIPS compliant SHA-1 hash function. 
 

Yes 
 

sha256(<str>) 
 
Computes and returns the secure hash of a string value, based�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c3cc1764-1693-41a6-beeb-8a1101182976�h+)�}�(h}�(h/X~Computes and returns the secure hash of a string value, based 
on the FIPS compliant SHA-1 hash function. 
 

Yes 
 

sha256(<str>) 
 
Computes and returns the secure hash of a string value, based 
on the FIPS compliant SHA-256 hash function. 
 

Yes 
 

sha512(<str>) 
 
Computes and returns the secure hash of a string value, based 
on the FIPS compliant SHA-512 hash function. 
 

Yes 
 

sigfig(<num>) 
 
Rounds a number to the appropriate number of significant 
figures. 
 

Yes 
 
sin(<x>) 
 
Computes the sine of x. 
 
Yes 
 
sinh(<x>) 
 
Computes the hyperbolic sine of x. 
 
Yes 
 
spath(<value>,<path>) 
 
Yes 
 
Yes 
 

29 
 
Supported functions and syntax 
 
Description 
 

1 
 
	edge 
Processor 
 
Extracts information from the structured data formats XML and 
JSON. 
 

split(<str>,<delim>) 
 
Splits the string values on the delimiter and returns the string 
values as a multivalue field. 
 

Yes 
 
sqrt(<num>) 
 
Returns the square root of a number. 
 
Yes 
 

strftime(<time>,<format>) 
 
Takes a UNIX time value and renders the time as a string using 
the format specified. The UNIX time must be in seconds. 
 

Yes 
 

Yes 
 

strptime(<str>,<format>) 
 
Takes a human readable time, represented by a string, and 
parses the time into a UNIX timestamp using the format. 
 

Yes 
 

Yes 
 

substr(<str>,<start>,<length>) 
 
Returns a substring of a string, beginning at the start index. The 
length of the substring specifies the number of characters to 
return. 
 

Yes 
 

Yes 
 
tan(<x>) 
 
Computes the tangent of x. 
 
Yes 
 
tanh(<x>) 
 
Computes the hyperbolic tangent of x. 
 
Yes 
 

time() 
 
Returns the wall-clock time, in the UNIX time format, with 
microsecond resolution. 
 

Yes 
 

Yes 
 

tojson(<internal_fields>) 
 
Returns a JSON object representation of events or search 
results. 
 

Yes 
 

tonumber(<str>,<base>) 
 
Converts a string to a number. The base is optional. If not 
specified, base 10 is used. 
 

Yes 
 

Yes 
 
tostring(<value>,<format>) 
 
Converts a value to a string using the specified format. 
 
Yes 
 
Yes 
 
trim(<str>,<trim_chars>) 
 
Removes the trim characters from both sides of the string. 
 
Yes 
 
Yes�h1h2h3}�h5Kuh�(h3h/�h}�ub�$af3932d2-1120-4663-8332-7e431fbe3e87�h+)�}�(h}�(h/XsYes 
 
tostring(<value>,<format>) 
 
Converts a value to a string using the specified format. 
 
Yes 
 
Yes 
 
trim(<str>,<trim_chars>) 
 
Removes the trim characters from both sides of the string. 
 
Yes 
 
Yes 
 

typeof(<value>) 
 
Returns a string that indicates the field type, such as Number, 
String, Boolean, and so forth. 
 

Yes 
 
upper(<str>) 
 
Returns a string in uppercase. 
 
Yes 
 
Yes 
 
urldecode(<url>) 
 
Returns a URL as an unescaped or decoded URL string. 
 
Yes 
 

validate(<condition>,<value>,...) 
 
Takes a list of conditions and values and returns the value that 
corresponds to the condition that evaluates to FALSE. This 
function defaults to NULL if all conditions evaluate to TRUE. 
 

Yes 
 
 The splunkd profile is currently used by only the Splunk Cloud Platform Search Experience product, which is in preview. 
 

See also 
 

Additional compatibility information 
 

SPL2 compatibility profiles 
 

Edge Processor information 
 

Regular expression syntax for Edge Processor pipelines 
 

SPL2 information 
 

30 
 
SPL2 eval functions Quick Reference 
Understanding SPL2 Syntax 
 





























































31 
 
Evaluation Functions 
 


Overview of SPL2 eval functions 
 
Use evaluation functions to evaluate an expression, based on your events, and return a result. 
 

Quick reference 
 

See the Eval functions Quick Reference for a list of the supported evaluation functions, along with a brief description and 
the syntax for each function. 
 

Commands that use eval functions 
 

You can use evaluation functions with the following commands: 
 

• In the WHERE and SELECT clauses of the from command 
• With the eval and  where commands 
 


Evaluation expressions are case-sensitive. 
 

Using functions 
 

• All functions that accept strings can accept either a literal string or any field. 
 


Specifying literal strings 
 

For most evaluation functions, when a string argument is expected you can specify either an literal string or a field. The 
literal string must be enclosed in double quotation marks. For example, you have a field called  name which contains the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$15bba263-49e9-4555-b386-6b1065ad0675�h+)�}�(h}�(h/X2literal string must be enclosed in double quotation marks. For example, you have a field called  name which contains the 
names of your servers. You want to append the literal string server at the end of the name. You would specify this: name + 
"server".  
 

Nested functions 
 

You can specify a function as an argument to another function. 
 

In the following example, the cidrmatch function is used as the first argument in the if function. 
 

... | eval isLocal=if(cidrmatch("123.132.32.0/25",ip), "local", "not local") 
 


The following example uses the in function as the first parameter for the if function. 
 

... | eval error=if(in(status, "error", "failure", "severe"), "true", "false") 
 






32 
 
Operators 
 

The following tables list the basic mathematical operations that you can use with the evaluation functions. For these 
operations to work, the values need to be valid for the type of operation. For example, with the exception of addition, 
arithmetic operations might not produce valid results if the values are not numerical. When concatenating values, Splunk 
software reads the values as strings, regardless of the value. 
 

Arithmetic operators 
 

Operators 
 

Action 
 

Description 
 
+ 
 
Addition 
 
Accepts two numbers and produces a number. 
 
- 
 
Subtraction 
 
Accepts two numbers and produces a number. 
 
* 
 
Multiplication 
 
Accepts two numbers and produces a number. 
 
/ 
 
Division 
 
Accepts two numbers and produces a number. 
 
% 
 
Modulo 
 
Accepts two numbers and produces a number. 
 
Concatenation operator 
 

Operator 
 

Action 
 

Description 
 
+ 
 
Concatenation 
 
Accepts both strings and numbers. Numbers are concatenated as strings. Produces a string. 
 
Boolean operators 
 

Operators 
 

Action 
 

Description 
 

AND 
 
Logical AND 
operator 
 

Accepts two Boolean values and produces a Boolean. 
 

OR 
 
Logical OR 
operator 
 

Accepts two Boolean values and produces a Boolean. 
 

NOT 
 
Logical NOT 
operator 
 

Accepts one Boolean value and produces the inverse of the value. 
 

XOR 
 
Exclusive OR 
operator�h1h2h3}�h5Kuh�(h3h/�h}�ub�$03d0455b-40b0-4d9b-a951-14709d9f2315�h+)�}�(h}�(h/X3OR 
 
Logical OR 
operator 
 

Accepts two Boolean values and produces a Boolean. 
 

NOT 
 
Logical NOT 
operator 
 

Accepts one Boolean value and produces the inverse of the value. 
 

XOR 
 
Exclusive OR 
operator 
 

Accepts two Boolean values and produces a Boolean. 
 
< 
 
Less than 
 
Accepts two numbers and produces a Boolean. 
 
> 
 
Greater than 
 
Accepts two numbers and produces a Boolean. 
 

<= 
 
Less than or equal 
to 
 

Accepts two numbers or two strings and produces a Boolean. 
 

>= 
 
Greater than or 
equal to 
 

Accepts two numbers and produces a Boolean. 
 
!= 
 
Not equal to 
 
Accepts two numbers or two strings and produces a Boolean. 
 

= or == 
 

Equal to 
 
In expressions, the = and == operators are synonymous. These operators compare the value of right side 
and left side of the expression. Returns 1 (true) if the sides are equal. Returns 0 (false) if the sides are not 
equal. 
 
LIKE 
 
Text pattern 
matching operator 
 
Accepts two strings. For example string LIKE pattern. The pattern operator supports literal text, a 
percent ( % ) character for a wildcard, and an underscore ( _ ) character for a single character match. 
 



33 
 
Operators 
 
Action 
 
Description 
 
For example, field LIKE "a%b_" matches any string starting with a, followed by anything, 
followed by b, followed by one character. 
 


See also 
 

Commands 
 

where command overview 
 

Functions 
 

Overview of SPL2 dataset_functions 
Custom eval functions 
 



SPL2 eval functions Quick Reference 
 
There are two ways to find information about the supported evaluation functions: 
 

• Function list by category 
 


Function list by category 
 

The following table is a quick reference of the supported evaluation functions. This table lists the syntax and provides a 
brief description for each of the functions. Use the links in the Type of function column for more details and examples. 
 

Type of function 
 

Supported functions and syntax 
 

Description 
 
Comparison and 
Conditional 
functions 
 

case(<condition>,<value>, ...) 

cidrmatch(<cidr>,<ip>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5f89911c-d549-4c67-9072-bbf2a1c3adf9�h+)�}�(h}�(h/X)Type of function 
 

Supported functions and syntax 
 

Description 
 
Comparison and 
Conditional 
functions 
 

case(<condition>,<value>, ...) 

cidrmatch(<cidr>,<ip>) 
 
Accepts alternating conditions and values. Returns the 
first value for which the condition evaluates to TRUE. 
Returns TRUE or FALSE based on whether an IP 
address matches a CIDR notation. 
 

coalesce(<values>) 
 
Takes one or more values and returns the first value that 
is not NULL. 
 

if(<predicate>,<true_value>,<false_value>) 
 
If the <predicate> expression evaluates to TRUE, 
returns the <true_value>. Otherwise the function 
returns the <false_value. 
 

in(<value>,<list>) 
 
Returns TRUE if one of the values in the list matches a 
value that you specify. 
 
like(<str>,<pattern>) 
 
Returns TRUE if the string value matches the pattern. 
 

match(<str>,<regex>) 
 
Returns TRUE if the regular expression finds a match 
against any substring of the string value. Otherwise 
returns FALSE. 
 
nullif(<value1>,<value2>) 
 

34 
 
Supported functions and syntax 
 
Description 
 
Compares two values and returns NULL if <value1> = 
<value2>. Otherwise it returns <value1>. 
 
searchmatch(<search_str>) 
 
Returns TRUE if the event matches the search string. 
 


Type of function 
 


validate(<condition>,<value>,...) 
 
Takes a list of conditions and values and returns the 
value that corresponds to the condition that evaluates to 
FALSE. This function defaults to NULL if all conditions 
evaluate to TRUE. 
 
Conversion 
functions 
 

ipmask(<mask>,<IP>) 
 
Generates a new masked IP address by applying a 
mask to a IPv4 address. 
 
object_to_array(<object>,<key>,<value>) 
 
Converts data that is in an object format into an array 
format. 
 

printf(<format>,<values>) 
 
Builds a string value, based on a string format and the 
values specified. 
 

tojson(<internal_fields>) 
 
Returns a JSON object representation of events or 
search results. 
 

tonumber(<str>,<base>) 
 
Converts a string to a number. The base is optional. If 
not specified, base 10 is used. 
 
tostring(<value>,<format>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f9a5c119-43bc-4459-ab71-fdb1ab47bfa7�h+)�}�(h}�(h/Xsearch results. 
 

tonumber(<str>,<base>) 
 
Converts a string to a number. The base is optional. If 
not specified, base 10 is used. 
 
tostring(<value>,<format>) 
 
Converts a value to a string using the specified format. 
 
md5(<str>) 
 
Computes and returns the MD5 hash of a string value. 
 

sha1(<str>) 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-1 hash function. 
 

sha256(<str>) 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-256 hash function. 
 


Cryptographic 
functions 
 

sha512(<str>) 

now() 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-512 hash function. 
Returns the time that the search was started. 
 


Date and Time 
functions 
 

relative_time(<time>,<specifier>) 


strftime(<time>,<format>) 
 
Takes a UNIX time and a relative time specifier and 
returns the UNIX time value of the specifier applied to 
the time. 
Takes a UNIX time value and renders the time as a 
string using the format specified. The UNIX time must be 
in seconds. 
 

strptime(<str>,<format>) 
 
Takes a human readable time, represented by a string, 
and parses the time into a UNIX timestamp using the 
 


time() 
 

Returns the wall-clock time, in the UNIX time format, 
with microsecond resolution. 
 
	Generates a cluster label, in the form of a number, for 
cluster(<field>,<threshold>,<match>,<delims>) each event based on how similar the events are to each 
 

Informational 
functions 
 

isbool(<value>) 
isint(<value>) 
 

Returns TRUE if the value is Boolean. 
Returns TRUE if the value is an integer. 
 
isnotnull(<value>) 
 
Returns TRUE if the value is not NULL. 
 


35 
 
Type of function 
 
Supported functions and syntax 
 
Description 
 
isnull(<value>) 
 
Returns TRUE if the value is NULL. 
 
isnum(<value>) 
 
Returns TRUE if the value is a number. 
 
isstr(<value>) 
 
Returns TRUE if the value is a string. 
 

typeof(<value>) 
 
Returns the data type of the value, such as Number, 
String, Boolean, and so forth�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ba4fa9a4-76d1-4c58-9310-f3cdcfccce2b�h+)�}�(h}�(h/X+Returns TRUE if the value is a number. 
 
isstr(<value>) 
 
Returns TRUE if the value is a string. 
 

typeof(<value>) 
 
Returns the data type of the value, such as Number, 
String, Boolean, and so forth 
 

json_append(<json>, <path_value_pairs>) 
 
Appends elements to the contents of a valid JSON 
object. 
 
json_array(<values) 
 
Creates a JSON array using a list of values. 
 
JSON functions 
 

json_array_to_mv(<json_array>, <boolean>) 
 
Maps the elements of a JSON array to a multivalued 
field. 
 

json_extend(<json>, <path_value_pairs>) 
 
Extends the contents of a valid JSON object with the 
values of an array. 
 

json_extract(<field>,<paths>) 
 
Returns a value from a field and zero or more paths. 
The value is returned in either a JSON array, or a 
 


json_extract_exact(<json>, <keys>) 
 

Returns Splunk software native type values from a piece 
of JSON by matching literal strings in the event and 
extracting the strings as keys. 
 

json_keys(<json>) 
 
Returns the keys from the key-value pairs in a JSON 
object. The keys are returned as a JSON array. 
 

json_object(<key>,<value,...) 
 
Creates a new JSON object from members of key-value 
pairs. 
 

json_set(<json>,<path_value_pairs>) 
 
Inserts or overwrites values for a JSON node with the 
path and value pairs provided and returns an updated 
JSON object. 
 

json_set_exact(<json>, <key_value_pairs>) 
 
Generates or overwrites a JSON object using the 
key-value pairs specified. 
 

json_valid(<field>) 
 
Evaluates whether a JSON object uses valid JSON 
syntax and returns either TRUE or FALSE. 
 
abs(<num>) 
 
Returns the absolute value of a number. 
 
ceiling(<num>) or ceil(<num>) 
 
Rounds a number up to the next highest integer. 
 

exact(<expression>) 
 
Returns the result of a numeric eval calculation with a 
larger amount of precision in the formatted output. 
 
exp(<num>) 
 
Returns the exponential function e 
 
floor(<num>) 
 
Rounds a number down to the nearest whole integer. 
 

Mathematical 
functions 
 
ln(<num>) 

log(<num>,<base>) 
 
Returns the natural logarithm of a number.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$60808c0f-d8a3-4433-99e5-6dc189b7f9de�h+)�}�(h}�(h/X7Returns the exponential function e 
 
floor(<num>) 
 
Rounds a number down to the nearest whole integer. 
 

Mathematical 
functions 
 
ln(<num>) 

log(<num>,<base>) 
 
Returns the natural logarithm of a number. 
Returns the logarithm of a number using a base. The 
base is optional, and if omitted the log function uses 
base 10. 
 
pi() 
 
Returns the constant pi to 11 digits of precision. 
 
pow(<num>,<exp>) 
 
Returns a number to the power of the exponent. 
 
round(<num>,<precision>) 
 

36 
 
Type of function 
 
Supported functions and syntax 
 
Description 
 
Returns a number rounded to the decimal places 
specified by the precision. The default is to round to an 
integer. 
 

sigfig(<num>) 
 
Rounds a number to the appropriate number of 
significant figures. 
 
sqrt(<num>) 
 
Returns the square root of a number. 
 
mvappend(<values>) 
 
Returns a single multivalue result from a list of values. 
 


mvcount(<mv>) 
 


Returns the count of the number of values in the 
specified multivalue field. 
 

Multivalue eval 
functions 
 

mvdedup(<mv>) 

mvfilter(<predicate>) 
 
Removes all of the duplicate values from a multivalue 
field. 
Filters a multivalue field based on a predicate 
expression. The expression can reference only one field. 
 

mvfind(<mv>,<regex>) 
 
Returns the index for the first value in a multivalue field 
that matches a regular expression. 
 

mvindex(<mv>,<start>,<end>) 
 
Returns a subset of the multivalue field using the start 
and end index values. 
 

mvjoin(<mv>,<delim>) 
 
Concatenates the individual values within the multivalue 
field using the value of the delimiter as a separator. 
 

mvrange(<start>,<end>,<step>) 
 
Creates multivalue field based on a range of specified 
numbers. 
 

mvsort(<mv>) 
 
Returns the values of a multivalue field sorted 
lexicographically. 
 


mvzip(<mv_left>,<mv_right>,<delim>) 
 
Combines the values in two multivalue fields. Stitches 
together the first value in each field, then the second 
value in each field, and so on. The delimiter is used to 
specify a delimiting character to join each pair of values.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c496a32f-59fd-4478-8b6a-e20b30290bd9�h+)�}�(h}�(h/X2together the first value in each field, then the second 
value in each field, and so on. The delimiter is used to 
specify a delimiting character to join each pair of values. 
 
mv_to_json_array(<field>,<infer_types>) 
 
Maps the elements of a multivalue field to a JSON array. 
 

split(<str>,<delim>) 
 
Splits the string values on the delimiter and returns the 
string values as a multivalue field. 
 
max(<values>) 
 
Returns the maximum of the string or numeric values. 
 


min(<values>) 
 


Returns the minimum of the string or numeric values. 
 

random() 
 
Returns a pseudo-random integer ranging from 0 to 
2  -1. 
 
len(<str>) 
 
Returns the character length of a string. 
 
Text functions 
 

lower(<str>) 
 
Converts a string to lowercase. 
 
Statistical eval 
functions 
 

ltrim(<str>,<trim_chars>) 
 
Removes the trim characters from the left side of the 
string. 
 

replace(<str>,<regex>,<replacement>) 
 
Substitutes the replacement string for every occurrence 
of the regular expression in the string. 
 


37 
 
Supported functions and syntax 
 
Description 
 

rtrim(<str>,<trim_chars>) 
 
Removes the trim characters from the right side of the 
string. 
 

spath(<value>,<path>) 
 
Extracts information from the structured data formats 
XML and JSON. 
 

Type of function 
 

substr(<str>,<start>,<length>) 
 
Returns a substring of a string, beginning at the start 
index. The length of the substring specifies the number 
of characters to return. 
 

trim(<str>,<trim_chars>) 
 
Removes the trim characters from both sides of the 
string. 
 
upper(<str>) 
 
Returns a string in uppercase. 
 
urldecode(<url>) 
 
Returns a URL as an unescaped or decoded URL string. 
 
acos(<x>) 
 
Computes the arc cosine of x. 
 
acosh(<x>) 
 
Computes the arc hyperbolic cosine of x. 
 
asin(<x>) 
 
Computes the arc sine of x. 
 
Trigonometry and    asinh(<x>) 
 
Computes the arc hyperbolic sine of x. 
 

functions 
 
atan(<x>) 
atan2(<y>,<x>) 
 
Computes the arc tangent of x. 
Computes the arc tangent of y, x. 
 
atanh(<x>) 
 
Computes the arc hyperbolic tangent of x. 
 
cos(<x>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ccd4b767-3ca7-4cfe-b206-7976530cb5f4�h+)�}�(h}�(h/Xnfunctions 
 
atan(<x>) 
atan2(<y>,<x>) 
 
Computes the arc tangent of x. 
Computes the arc tangent of y, x. 
 
atanh(<x>) 
 
Computes the arc hyperbolic tangent of x. 
 
cos(<x>) 
 
Computes the cosine of an angle of x radians. 
 
cosh(<x>) 
 
Computes the hyperbolic cosine of x radians. 
 
hypot(<x>,<y>) 
 
Computes the hypotenuse of a triangle. 
 
sin(<x>) 
 
Computes the sine of x. 
 
sinh(<x>) 
 
Computes the hyperbolic sine of x. 
 
tan(<x>) 
 
Computes the tangent of x. 
 
tanh(<x>) 
 
Computes the hyperbolic tangent of x. 
 
Alphabetical list of functions 
 


Supported functions and syntax 
 


Description 
 

	Type of 
function 
 

abs(<num>) 
 

Returns the absolute value of a number. 
 
Mathematical 
functions 
 

acos(<x>) 
 

Computes the arc cosine of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

acosh(<x>) 
 

Computes the arc hyperbolic cosine of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

asin(<x>) 
 

Computes the arc sine of x. 
 
Trigonometry and 
Hyperbolic 
 



38 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

asinh(<x>) 
 

Computes the arc hyperbolic sine of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

atan(<x>) 
 

Computes the arc tangent of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

atan2(<y>,<x>) 
 

Computes the arc tangent of y,x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

atanh(<x>) 
 

Computes the arc hyperbolic tangent of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

case(<condition>,<value>, ...) 
 

Accepts alternating conditions and values. Returns the first 
value for which the condition evaluates to TRUE. 
 
Comparison and 
Conditional 
functions 
 

ceiling(<num>) or ceil(<num>) 
 

Rounds a number up to the next highest integer. 
 
Mathematical 
functions 
 

cidrmatch(<cidr>,<ip>) 
 

Returns TRUE or FALSE based on whether an IP address 
matches a CIDR notation. 
 
Comparison and 
Conditional 
functions 
 

cluster(<field>,<threshold>,<match>,<delims>) 
 
Generates a cluster label, in the form of a number, for each 
event based on how similar the events are to each other. 
 
Informational 
functions 
 

coalesce(<values>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3f8a3ac9-54ca-4e2b-8c97-d2506e4682d5�h+)�}�(h}�(h/XlGenerates a cluster label, in the form of a number, for each 
event based on how similar the events are to each other. 
 
Informational 
functions 
 

coalesce(<values>) 
 

Takes one or more values and returns the first value that is 
not NULL. 
 
Comparison and 
Conditional 
functions 
 

cos(<x>) 
 

Computes the cosine of an angle of x radians. 
 
Trigonometry and 
Hyperbolic 
functions 
 

cosh(<x>) 
 

Computes the hyperbolic cosine of x radians. 
 
Trigonometry and 
Hyperbolic 
functions 
 

exact(<expression>) 
 
Returns the result of a numeric eval calculation with a larger 
amount of precision in the formatted output. 
 
Mathematical 
functions 
 

exp(<num>) 
 

Returns the exponential function e 
 
Mathematical 
functions 
 

floor(<num>) 
 

Rounds a number down to the nearest whole integer. 
 
Mathematical 
functions 
 

hypot(<x>,<y>) 
 

Computes the hypotenuse of a triangle. 
 
Trigonometry and 
Hyperbolic 
functions 
 

if(<predicate>,<true_value>,<false_value>) 
 
If the <predicate> expression evaluates to TRUE, returns 
the <true_value>. Otherwise the function returns the 
<false_value>. 
 
Comparison and 
Conditional 
functions 
 
in(<value>,<list>) 
 
Returns TRUE if one of the values in the list matches a 
value that you specify. 
 
Comparison and 
Conditional 
 



39 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

ipmask(<mask>,<IP>) 
 

Generates a new masked IP address by applying a mask to 
a IPv4 address. 
 

Conversion 
functions 
 

isbool(<value>) 
 

Returns TRUE if the value is Boolean. 
 
Informational 
functions 
 

isint(<value>) 
 

Returns TRUE if the value is an integer. 
 
Informational 
functions 
 

isnotnull(<value>) 
 

Returns TRUE if the value is not NULL. 
 
Informational 
functions 
 

isnull(<value>) 
 

Returns TRUE if the value is NULL. 
 
Informational 
functions 
 

isnum(<value>) 
 

Returns TRUE if the value is a number. 
 
Informational 
functions 
 

isstr(<value>) 
 

Returns TRUE if the value is a string. 
 
Informational 
functions 
 
json_append(<json>, <path_value_pairs>) 
 
Appends elements to the contents of a valid JSON object.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3d99e349-5c03-4dde-b83b-5b8995c61662�h+)�}�(h}�(h/X'functions 
 

isstr(<value>) 
 

Returns TRUE if the value is a string. 
 
Informational 
functions 
 
json_append(<json>, <path_value_pairs>) 
 
Appends elements to the contents of a valid JSON object. 
 
JSON functions 
 
json_array(<values>) 
 
Creates a JSON array using a list of values. 
 
JSON functions 
 
json_array_to_mv(<json_array>, <boolean>) 
 
Maps the elements of a JSON array to a multivalued field. 
 
JSON functions 
 

json_extend(<json>, <path_value_pairs>) 
 
Extends the contents of a valid JSON object with the values 
of an array. 
 

JSON functions 
 

json_extract(<field>,<paths>) 
 
Returns a value from a field and zero or more paths. The 
value is returned in either a JSON array, or a Splunk 
software native type value. 
 

JSON functions 
 

json_extract_exact(<json>, <keys>) 
 
Returns Splunk software native type values from a piece of 
JSON by matching literal strings in the event and extracting 
the strings as keys. 
 

JSON functions 
 

json_keys(<json>) 
 
Returns the keys from the key-value pairs in a JSON object. 
The keys are returned as a JSON array. 
 

JSON functions 
 

json_object(<key>,<value>,...) 
 
Creates a new JSON object from members of key-value 
pairs. 
 

JSON functions 
 

json_set(<field>,<path_value_pairs>) 
 
Inserts or overwrites values for a JSON node with the path 
and value pairs provided and returns an updated JSON 
 

JSON functions 
 


json_set_exact(<json>, <key_value_pairs>) 
 

Generates or overwrites a JSON object using the key-value 
pairs specified. 
 


JSON functions 
 

json_valid(<field>) 
 
Evaluates whether a JSON object uses valid JSON syntax 
and returns either TRUE or FALSE. 
 

JSON functions 
 
len(<str>) 
 
Returns the character length of a string. 
 
Text functions 
 

like(<str>,<pattern>) 
 

Returns TRUE if the string value matches the pattern. 
 
Comparison and 
Conditional 
functions 
 

ln(<num>) 
 

Returns the natural logarithm of a number. 
 
Mathematical 
functions 
 


40 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

log(<num>,<base>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c4a95291-ffad-418a-ac16-720867c8b5ca�h+)�}�(h}�(h/X\Conditional 
functions 
 

ln(<num>) 
 

Returns the natural logarithm of a number. 
 
Mathematical 
functions 
 


40 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

log(<num>,<base>) 
 
Returns the logarithm of a number using a base. The base 
is optional, and if omitted the log function uses base 10. 
 
Mathematical 
functions 
 
lower(<str>) 
 
Converts a string to lowercase. 
 
Text functions 
 
ltrim(<str>,<trim_chars>) 
 
Removes the trim characters from the left side of the string. 
 
Text functions 
 

match(<str>,<regex>) 
 
Returns TRUE if the regular expression finds a match 
against any substring of the string value. Otherwise returns 
FALSE. 
 
Comparison and 
Conditional 
functions 
 

max(<values>) 
 

Returns the maximum of the string or numeric values. 
 
Statistical eval 
functions 
 

md5(<str>) 
 

Computes and returns the MD5 hash of a string value. 
 
Cryptographic 
functions 
 

min(<values>) 
 

Returns the minimum of the string or numeric values. 
 
Statistical eval 
functions 
 

mvappend(<values>) 
 

Returns a single multivalue result from a list of values. 
 
Multivalue eval 
functions 
 

mvcount(<mv>) 
 
Returns the count of the number of values in the specified 
multivalue field. 
 
Multivalue eval 
functions 
 

mvdedup(<mv>) 
 

Removes all of the duplicate values from a multivalue field. 
 
Multivalue eval 
functions 
 

mvfilter(<predicate>) 
 
Filters a multivalue field based on a predicate expression. 
The expression can reference only one field. 
 
Multivalue eval 
functions 
 

mvfind(<mv>,<regex>) 
 
Returns the index for the first value in a multivalue field that 
matches a regular expression. 
 
Multivalue eval 
functions 
 

mvindex(<mv>,<start>,<end>) 
 
Returns a subset of the multivalue field using the start and 
end index values. 
 
Multivalue eval 
functions 
 

mvjoin(<mv>,<delim>) 
 
Concatenates the individual values within the multivalue 
field using the value of the delimiter as a separator. 
 
Multivalue eval 
functions 
 

mvrange(<start>,<end>,<step>) 
 
Creates a multivalue field based on a range of specified 
numbers.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dedca1e1-543c-49f9-a582-e0b0455484a7�h+)�}�(h}�(h/XPfield using the value of the delimiter as a separator. 
 
Multivalue eval 
functions 
 

mvrange(<start>,<end>,<step>) 
 
Creates a multivalue field based on a range of specified 
numbers. 
 
Multivalue eval 
functions 
 

mvsort(<mv>) 
 
Returns the values of a multivalue field sorted 
lexicographically. 
 
Multivalue eval 
functions 
 


mvzip(<mv_left>,<mv_right>,<delim>) 
 
Combines the values in two multivalue fields. Stitches 
together the first value in each field, then the second value 
in each field, and so on. The delimiter is used to specify a 
delimiting character to join each pair of values. 
 

Multivalue eval 
functions 
 

mv_to_json_array(<field>,<infer_types>) 
 

Maps the elements of a multivalue field to a JSON array. 
 
Multivalue eval 
functions 
 

now() 
 

Returns the time that the search was started. 
 
Date and Time 
functions 
 

null() 
 

This function takes no arguments and returns NULL. 
 
Comparison and 
Conditional 
functions 
 
nullif(<value1>,<value2>) 
 


41 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 
Compares two values and returns NULL if <value1> = 
<value2>. Otherwise it returns <value1>. 
 
Comparison and 
Conditional 
functions 
 

object_to_array(<object>,<key>,<value>) 
 
Converts data that is in an object format into an array 
format. 
 
Conversion 
functions 
 

pi() 
 

Returns the constant pi to 11 digits of precision. 
 
Mathematical 
functions 
 

pow(<num>,<exp>) 
 

Returns a number to the power of the exponent. 
 
Mathematical 
functions 
 

printf(<format>,<values>) 
 
Builds a string value, based on a string format and the 
values specified. 
 
Conversion 
functions 
 

random() 
 

Returns a pseudo-random integer ranging from 0 to 2 
 
Statistical eval 
functions 
 

relative_time(<time>,<specifier>) 
 
Takes a UNIX time and a relative time specifier and returns 
the UNIX time value of the specifier applied to the time. 
 
Date and Time 
functions 
 

replace(<str>,<regex>,<replacement>) 
 
Substitutes the replacement string for every occurrence of 
the regular expression in the string. 
 

Text functions�h1h2h3}�h5Kuh�(h3h/�h}�ub�$26f9acb0-d5ae-4c9d-82aa-4106df367f45�h+)�}�(h}�(h/XcDate and Time 
functions 
 

replace(<str>,<regex>,<replacement>) 
 
Substitutes the replacement string for every occurrence of 
the regular expression in the string. 
 

Text functions 
 

round(<num>,<precision>) 
 
Returns a number rounded to the decimal places specified 
by the precision. The default is to round to an integer. 
 
Mathematical 
functions 
 

rtrim(<str>,<trim_chars>) 
 
Removes the trim characters from the right side of the 
string. 
 

Text functions 
 

searchmatch(<search_str>) 
 

Returns TRUE if the event matches the search string. 
 
Comparison and 
Conditional 
functions 
 

sha1(<str>) 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-1 hash function. 
 
Cryptographic 
functions 
 

sha256(<str>) 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-256 hash function. 
 
Cryptographic 
functions 
 

sha512(<str>) 
 
Computes and returns the secure hash of a string value, 
based on the FIPS compliant SHA-512 hash function. 
 
Cryptographic 
functions 
 

sigfig(<num>) 
 
Rounds a number to the appropriate number of significant 
figures. 
 
Mathematical 
functions 
 

sin(<x>) 
 

Computes the sine of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

sinh(<x>) 
 

Computes the hyperbolic sine of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

spath(<value>,<path>) 
 
Extracts information from the structured data formats XML 
and JSON. 
 

Text functions 
 

split(<str>,<delim>) 
 
Splits the string values on the delimiter and returns the 
string values as a multivalue field. 
 
Multivalue eval 
functions 
 
sqrt(<num>) 
 
Returns the square root of a number. 
 
Mathematical 
functions 
 


42 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 


strftime(<time>,<format>) 
 

Takes a UNIX time value and renders the time as a string 
using the format specified. The UNIX time must be in 
seconds. 
 

Date and Time 
functions 
 

strptime(<str>,<format>) 
 
Takes a human readable time, represented by a string, and 
parses the time into a UNIX timestamp using the format. 
 
Date and Time�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9f9892ad-80db-4bfb-b49f-e0357db1d737�h+)�}�(h}�(h/X�seconds. 
 

Date and Time 
functions 
 

strptime(<str>,<format>) 
 
Takes a human readable time, represented by a string, and 
parses the time into a UNIX timestamp using the format. 
 
Date and Time 
functions 
 

substr(<str>,<start>,<length>) 
 
Returns a substring of a string, beginning at the start index. 
The length of the substring specifies the number of 
characters to return. 
 

Text functions 
 

tan(<x>) 
 

Computes the tangent of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

tanh(<x>) 
 

Computes the hyperbolic tangent of x. 
 
Trigonometry and 
Hyperbolic 
functions 
 

time() 
 
Returns the wall-clock time, in the UNIX time format, with 
microsecond resolution. 
 
Date and Time 
functions 
 

tojson(<internal_fields>) 
 
Returns a JSON object representation of events or search 
results. 
 
Conversion 
functions 
 

tonumber(<str>,<base>) 
 
Converts a string to a number. The base is optional. If not 
specified, base 10 is used. 
 
Conversion 
functions 
 

tostring(<value>,<format>) 
 

Converts a value to a string using the specified format. 
 
Conversion 
functions 
 
trim(<str>,<trim_chars>) 
 
Removes the trim characters from both sides of the string. 
 
Text functions 
 

typeof(<value>) 
 
Returns a string that indicates the field type, such as 
Number, String, Boolean, and so forth. 
 
Informational 
functions 
 
upper(<str>) 
 
Returns a string in uppercase. 
 
Text functions 
 
urldecode(<url>) 
 
Returns a URL as an unescaped or decoded URL string. 
 
Text functions 
 


validate(<condition>,<value>,...) 
 
Takes a list of conditions and values and returns the value 
that corresponds to the condition that evaluates to FALSE. 
This function defaults to NULL if all conditions evaluate to 
TRUE. 
 

Comparison and 
Conditional 
functions 
 
See also 
 

• Overview of SPL2 eval functions 
• Stats Functions Quick Reference 
 


Comparison and Conditional functions 
 
The following list contains the functions that you can use to compare values or specify conditional statements.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dd132514-3c21-45db-92fd-bc17880f1b21�h+)�}�(h}�(h/X�• Stats Functions Quick Reference 
 


Comparison and Conditional functions 
 
The following list contains the functions that you can use to compare values or specify conditional statements. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 evaluation 
functions. 
 



43 
 
case(<condition>, <value>, ...) 
 

This function takes pairs of <condition> and <value> arguments and returns the first value for which the condition 
evaluates to TRUE. 
 

Usage 
 

The <condition> arguments are Boolean expressions that are evaluated from first to last. When the first <condition> 
expression is encountered that evaluates to TRUE, the corresponding <value> argument is returned. The function defaults 
to NULL if none of the <condition> arguments are true. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns descriptions for the corresponding HTTP status code. 
 

|from my_dataset where sourcetype="access_*" | eval description=case(status == 200, "OK", status ==404, 
"Not found", status == 500, "Internal Server Error") | fields status, description 
 

The results look something like this: 
 

status 
 

description 
 
200 
 
OK 
 
200 
 
OK 
 
408 
 
200 
 
OK 
 
404 
 
Not found 
 
200 
 
OK 
 
406 
 
500 
 
Internal Server Error 
 
200 
 
OK 
 
Specifying a default value 
 

In the above example, the description column is empty for status=406 and status=408. 
 

To display a default value when the status does not match one of the values specified, use the literal true. For example: 
 

|from my_dataset where sourcetype="access_*" | eval description=case(status == 200, "OK", status ==404, 
"Not found", status == 500, "Internal Server Error", true, "Other") | table status description 
 

The word Other displays in the search results for status=406 and status=408. 
 





44 
 
Extended example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$118043ce-db65-4527-b770-db71b540f3e6�h+)�}�(h}�(h/X�"Not found", status == 500, "Internal Server Error", true, "Other") | table status description 
 

The word Other displays in the search results for status=406 and status=408. 
 





44 
 
Extended example 
 

This example shows you how to use the case function in two different ways, to create categories and to create a custom 
sort order. 
 

This example uses earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that 
contains magnitude (mag), coordinates (latitude, longitude), region (place), and so forth, for each earthquake recorded. 
 
You want classify earthquakes based on depth. Shallow-focus earthquakes occur at depths less than 70 km. Mid-focus 
earthquakes occur at depths between 70 and 300 km. Deep-focus earthquakes occur at depths greater than 300 km. 
We'll use Low, Mid, and Deep for the category names. 
 

| from my_dataset where source="all_month.csv" | eval Description=case(depth<=70, "Low", depth>70 AND 
depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) by Description 
 

The eval command is used to create a field called Description, which takes the value of "Low", "Mid", or "Deep" based 
 

example, if the depth is less than 70 km, the earthquake is characterized as a shallow-focus quake; and the resulting 
Description is Low. 
 

The search also pipes the results of the eval command into the stats command to count the number of earthquakes and 
display the minimum and maximum magnitudes for each Description. 
 

The results look something like this: 
 

Description 
 

count 
 

min(Mag) 
 

max(Mag) 
 
Deep 
 
35 
 
4.1 
 
6.7 
 
Low 
 
6236 
 
-0.60 
 
7.70 
 
Mid 
 
635 
 
0.8 
 
6.3 
 
You can sort the results in the Description column by clicking the sort icon in Splunk Web. However in this example the 
order would be alphabetical returning results in Deep, Low, Mid or Mid, Low, Deep order. 
 

You can also use the case function to sort the results in a custom order, such as Low, Mid, Deep. You create the custom�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0bec38a0-c323-4bea-a1e4-4467ef975dd0�h+)�}�(h}�(h/X!You can also use the case function to sort the results in a custom order, such as Low, Mid, Deep. You create the custom 
sort order by giving the values a numerical ranking and then sorting based on that ranking. 
 

from my_dataset where source="all_month.csv" | eval Description=case(depth<=70, "Low", depth>70 AND 
depth<=300, "Mid", depth>300, "Deep") | stats count min(mag) max(mag) by Description | eval 
sort_field=case(Description="Low", 1, Description="Mid", 2, Description="Deep",3) | sort sort_field 
 

The results look something like this: 
 

Description 
 

count 
 

min(Mag) 
 

max(Mag) 
 
Low 
 
6236 
 
-0.60 
 
7.70 
 
Mid 
 
635 
 
0.8 
 
6.3 
 
Deep 
 
35 
 
4.1 
 
6.7 
 






45 
 
cidrmatch(<cidr>, <ip>) 
 

Returns TRUE or FALSE based on whether an IP address matches a CIDR notation. 
 

This function returns TRUE when an IP address, <ip>, belongs to a particular CIDR subnet, <cidr>. This function is 
compatible with IPv6. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Both <cidr> and <ip> are string arguments. If you specify a literal string value, instead of a field name, that value must be 
enclosed in double quotation marks. 
 

Basic examples 
 

The following example uses the cidrmatch and if functions to set a field, isLocal, to "local" if the field ipAddress matches 
the subnet. If the ipAddress field does not match the subnet, the isLocal field is set to "not local". 
 

... | eval isLocal=if(cidrmatch("192.0.2.0/24",ipAddress), "local", "not local") 
 


The following example uses the cidrmatch function as a filter to remove events where the values in the mycidr field do not 
match the IP address. 
 

... | where NOT cidrmatch(mycidr, "203.0.113.255") 
 

coalesce(<values>) 
 

This function takes one or more values and returns the first value that is not NULL. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part�h1h2h3}�h5Kuh�(h3h/�h}�ub�$781f9d8e-09f0-49eb-87e0-3e4a2ea62fe0�h+)�}�(h}�(h/X�Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

You have a set of events where the IP address is extracted to either clientip or ipaddress. This example defines a new 
field called ip, that takes the value of either the clientip field or ipaddress field, depending on which field is not NULL 
(does not exist in that event). If both the clientip and ipaddress field exist in the event, this function returns the value in 
first argument, the clientip field. 
 

... | eval ip=coalesce(clientip, ipaddress) 
 

If neither field exists in the events, you can specify a default value: 
 

... | eval ip=coalesce(clientip, ipaddress, "203.0.113.255") 
 





46 
 
if(<predicate>, <true_value>, <false_value>) 
 

If the <predicate> expression evaluates to TRUE, returns the <true_value>, otherwise the function returns the 
<false_value>. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The if function is frequently used in combination with other functions. 
 

Basic examples 
 

The following example looks at the values of the error field. If error=200, the function returns err=OK. Otherwise the 
function returns err=Error. 
 

... | eval err=if(error == 200, "OK", "Error") 
 


The following example uses the cidrmatch and if functions to set a field, isLocal, to "local" if the field ip matches the 
subnet. If the ip field does not match the subnet, the isLocal field is set to "not local". 
 

... | eval isLocal=if(cidrmatch("123.132.32.0/25",ip), "local", "not local") 
 


You can use the if function to replace the values in a field, based on the predicate expression. The following example 
works on an existing field score. If the value in the test field is Passed, the value in the score field remains unchanged.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b9b1305e-272b-4a3a-a1e0-39f7a84e7764�h+)�}�(h}�(h/X�works on an existing field score. If the value in the test field is Passed, the value in the score field remains unchanged. 
Otherwise the value in the score field is changed to 0 in the search results. 
 

... | eval score=if(test="Passed", score, 0) 
 

You can also reverse this search to something like this: 
 

... | eval score=if(test="Failed", 0, score) 
 

If the value in the test field is Failed, the value in the score field is changed to 0 in the search results. Otherwise the 
value in the score field remains unchanged. 
 

in(<value>, <list>) 
 

The function returns TRUE if one of the values in the list matches a value that you specify. 
 

This function takes a list of comma-separated values. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The following syntax is supported: 
 


47 
 
...WHERE in(<value>, [<list>]) or ...| where in(<value>, [<list>]) 
...WHERE <value> in([<list>]) or ...| where <value> in([<list>]) 
 
...| eval new_field=if(in(<value>, [<list>]), "true_value", "false_value") 
 

The eval command cannot accept a Boolean value. You must specify the in() function inside a function that can accept 
a Boolean value as input. Those functions are: code, if, and validate. 
 

The string values must be enclosed in quotation marks. You cannot specify wildcard characters in the list of values to 
specify a group of similar values, such as HTTP error codes or CIDR IP address ranges. Use the IN operator instead. 
 

The IN predicate operator is similar to the in() function. You can use the IN operator with the search command, as well 
 

Manual. 
 

Basic examples 
 

Specifying a list of values 
 

The following example uses the where command to return in=TRUE if one of the values in the status field matches one of 
the values in the list. 
 

... | where status in("400", "401", "403", "404") 
 

Specifying a list of fields�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1901cdd7-b47c-4920-b44a-86551affc2b7�h+)�}�(h}�(h/X%the values in the list. 
 

... | where status in("400", "401", "403", "404") 
 

Specifying a list of fields 
 

The following example uses the where command to return in=TRUE if the value 203.0.113.255 appears in either the 
ipaddress or clientip fields. 
 

... | where "203.0.113.255" in(ipaddress, clientip) 
 

Using the in function inside another function 
 

The following example uses the in() function as the first parameter for the if() function. The evaluation expression 
returns TRUE if the value in the status field matches one of the values in the list. 
 

... | eval error=if(in(status, "error", "failure", "severe"),"true","false") 
 

Extended example 
 

The following example combines the in function with the if function to evaluate the status field. The value of true is 
placed in the new field error if the status field contains one of the values 404, 500, or 503. Then a count is performed of 
the values in the error field. 
 

... | eval error=if(in(status, "404","500","503"),"true","false") | stats count() by error 
 

For additional in function examples, see the blog Smooth operator | Searching for multiple field values. 
 

like(<str>, <pattern>) 
 

This function returns TRUE only if str matches pattern. The match can be an exact match or a match using a wildcard: 
 

• Use the percent ( % ) symbol as a wildcard for matching multiple characters 
 

48 
 
• Use the underscore ( _ ) character as a wildcard to match a single character 
 

Usage 
 

The <str> can be a field name or a string value. The <pattern> must be a string expression enclosed in double quotation 
marks. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The following syntax is supported: 
 

command 
 

syntax 
 
...WHERE like(<str>, <pattern>) 
 
WHERE clause 
 
...WHERE <str> LIKE <pattern> 
 
eval command 
 
...|eval new_field=if(like(<str>, <pattern>) 
 
...| where like(<str>, <pattern>) 
 
where command 
 
...| where <str> LIKE <pattern>�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7493afbc-d858-465c-86fe-54dcf74b463f�h+)�}�(h}�(h/X�WHERE clause 
 
...WHERE <str> LIKE <pattern> 
 
eval command 
 
...|eval new_field=if(like(<str>, <pattern>) 
 
...| where like(<str>, <pattern>) 
 
where command 
 
...| where <str> LIKE <pattern> 
 
The eval command cannot accept a Boolean value. You must specify the like() function inside the if() function, which 
can accept a Boolean value as input. 
 

The LIKE predicate operator is similar to the like() function. You can use the LIKE operator with the same commands 
and clauses where you can use the like() function. See Predicate expressions in the SPL2 Search Manual. 
 

Basic examples 
 

The following example returns like=TRUE if the field value starts with foo: 
 

... | eval is_a_foo=if(like(field, "foo%"), "yes a foo", "not a foo") 
 


The following example uses the where command to return like=TRUE if the ipaddress field starts with the value 198.. The 
percent ( % ) symbol is a wildcard with the like function: 
 

... | where like(ipaddress, "198.%") 
 

match(<str>, <regex>) 
 

This function returns TRUE if the regular expression <regex> finds a match against any substring of the string value <str>. 
Otherwise returns FALSE. 
 

Usage 
 

The match function is regular expression, using the perl-compatible regular expressions (PCRE) syntax. For example use 
the backslash ( \ ) character to escape a special character, such as a quotation mark. Use the pipe ( | ) character to 
specify an OR condition. 
 




49 
 
The Edge Processor solution supports Regular Expression 2 (RE2) syntax instead of PCRE syntax. In particular RE2 
and PCRE accept different syntax for named capture groups. See Regular expression syntax for Edge Processor 
pipelines in Use Edge Processors. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns TRUE if, and only if, field matches the basic pattern of an IP address. This examples uses�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dbef65e4-9862-4cac-ad7f-f4b9c4774fc3�h+)�}�(h}�(h/Xof evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns TRUE if, and only if, field matches the basic pattern of an IP address. This examples uses 
the caret ( ^ ) character and the dollar ( $ ) symbol to perform a full match. 
 

... | eval n=if(match(field, "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"), 1, 0) 
 


The following example uses the match function in an <eval-expression>. The <str> is a calculated field called test. The 
<regex> is the string yes. 
 

... | eval matches = if(match(test,"yes"), 1, 0) 
 

If the value is stored with quotation marks, you must use the backslash ( \ ) character to escape the embedded quotation 
marks. For example: 
 

| from [{ }] | eval test="\"yes\"" | eval matches = if(match(test, "\"yes\""), 1, 0) 
 

This example creates a single event using the from command and an empty dataset literal string value [{ }], which 
returns the _time field. 
 

nullif(<field1>, <field2>) 
 

This function compares the values in two fields and returns NULL if the value in <field1> is equal to the value in 
<field2>. Otherwise the function returns the value in <field1>. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

Using the repeat dataset function, the following search creates a field called names. Another field called ponies is created 
based on the names field. The if function is used to change the name buttercup to mistmane in the ponies field. 
 

from repeat({},1) | eval _time=now() | eval names="buttercup rarity tenderhoof dash" | eval 
names=split(names," ") | mvexpand names | eval ponies = if(test="buttercup", "pinto", names) 
 

The results look like this: 
 

_time 
 

names 
 

ponies 
 
14:57:12 PM 17 Oct 2022 
 
buttercup 
 
mistmane 
 


50 
 
_time 
 
names 
 
ponies 
 

14:57:12 PM 17 Oct 2022 
 

rarity 
 

rarity 
 
14:57:12 PM 17 Oct 2022 
 
tenderhoof 
 
tenderhoof 
 
14:57:12 PM 17 Oct 2022 
 
dash 
 
dash�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2b387f60-7b0d-42b1-9f57-f4111253c388�h+)�}�(h}�(h/Xf14:57:12 PM 17 Oct 2022 
 
buttercup 
 
mistmane 
 


50 
 
_time 
 
names 
 
ponies 
 

14:57:12 PM 17 Oct 2022 
 

rarity 
 

rarity 
 
14:57:12 PM 17 Oct 2022 
 
tenderhoof 
 
tenderhoof 
 
14:57:12 PM 17 Oct 2022 
 
dash 
 
dash 
 
Using the nullif function, you can compare the values in the names and ponies fields. If the values are different, the value 
from the first field specified are displayed in the compare field. If the values are the same, no value is returned. 
 

... eval compare = nullif(names, ponies) 
 

The results look like this: 
 

_time 
 

compare 
 

names 
 

ponies 
 
14:57:12 PM 17 Oct 2022 
 
buttercup 
 
buttercup 
 
mistmane 
 
14:57:12 PM 17 Oct 2022 
 
rarity 
 
rarity 
 
14:57:12 PM 17 Oct 2022 
 
tenderhoof 
 
tenderhoof 
 
14:57:12 PM 17 Oct 2022 
 
dash 
 
dash 
 
searchmatch(<search_str>) 
 

This function returns TRUE if the event matches the search string. 
 

Usage 
 

To use the searchmatch function with the eval command, you must use the searchmatch function inside the if function. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

The following example creates an event the contains a timestamp and two fields x and y. 
 

| from [{ }] | eval x="hi" | eval y="goodbye" 
 

The results look like this: 
 

_time 
 

x 
 

y 
 
9/2/2020 1:29:58.000 PM 
 
hi 
 
goodbye 
 
Add the searchmatch function to determine if the <search_str> matches the event: 
 

| from [{ }] | eval x="hi" | eval y="goodbye" | eval test=if(searchmatch("x=hi y=*"), "yes", "no") | fields 
test x y 
 


The results look like this: 
 


51 
 
test 
 
x 
 
y 
 
yes 
 
hi 
 
goodbye 
 
validate(<condition>, <value>, ...) 
 

This function takes a list of conditions and values and returns the value that corresponds to the condition that evaluates to 
FALSE. This function defaults to NULL if all conditions evaluate to TRUE. 
 

This function is the opposite of the case function. 
 

Usage 
 

The <condition> arguments must be expressions. 
 

The <value> arguments must be strings.�
h1h2h3}�h5Kuh�(h3h/�h}�ub�$5ccd90ad-1d02-4efb-b937-e6a8a82fc6ec�h+)�}�(h}�(h/XThis function is the opposite of the case function. 
 

Usage 
 

The <condition> arguments must be expressions. 
 

The <value> arguments must be strings. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

The following example runs a simple check for valid ports. 
 

... | eval n=validate(isint(port), "ERROR: Port is not an integer", port >= 1 AND port <= 65535, "ERROR: 
Port is out of range") 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 



Conversion functions 
 
The following list contains the functions that you can use to mask IP addresses and convert numbers to strings and 
strings to numbers. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

ipmask(<mask>,<ip>) 
 

Description 
 

This function generates a new masked IP address by applying a mask to an IP address through a bitwise AND operation. 
You can use this function to simplify the isolation of an IPv4 address octet without splitting the IP address. 
 




52 
 
Usage 
 

The <mask> argument must be a valid IPv4 address. The <ip> argument must be a valid IPv4 address or a field name 
where the field value is a valid IPv4 address. 
 

A valid IPv4 address is a quad-dotted notation of four decimal integers, each ranging from 0-255. 
 

For the <mask> argument, you can specify one of the default subnet masks such as 255.255.255.0. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example shows how to use the ipmask function with the eval command. The output of this example is 
10.20.30.0. 
 

... | eval maskedIP = ipmask("255.255.255.0", "10.20.30.120") 
 

The following example shows how to use the ipmask function in the SELECT clause of the from command. This example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$bb52922a-a954-408f-9cf1-378158265fab�h+)�}�(h}�(h/X 10.20.30.0. 
 

... | eval maskedIP = ipmask("255.255.255.0", "10.20.30.120") 
 

The following example shows how to use the ipmask function in the SELECT clause of the from command. This example 
masks every IP address in the clientip field and returns the results in an aliased field called maskedip. 
 

FROM main SELECT ipmask("0.255.0.244", clientip) AS maskedip 
 



The following example shows how to use the ipmask function in the WHERE clause of the from command to filter the 
events on a specific mask value. In this example, the masked value is 0.20.0.96. 
 

FROM main WHERE ipmask("0.255.0.224", clientip)="10.20.30.120" 
 

object_to_array(<object>, <key>, <value>) 
 

Converts data that is in an object format into an array format. 
 

Usage 
 

You can use this function with the eval command. 
 

The <object> is the data that is formatted as an object. 
 

The <key> is the label you want to use for the name of the keys in the array of key-value pairs. The <key> must be 
enclosed in quotation marks. 
 

The <value> is the label you want to use as the name of the values in the array of key-value pairs. The <value> must be 
enclosed in quotation marks. 
 

Examples 
 






53 
 
Converting a single object into an array 
 

Consider the following field, called statePop which consists of a set of state names and the population in those states: 
 


{"Washington": 7535591, "California": 39557045, "Oregon": 4190714} 
 
Use the object_to_array function to create an array from the objects. 
 

... | eval stateData=object_to_array(statePop,"state", "population") 
 

The results look something like this: 
 

Event 
 
stateData: "[{"state":"Washington","population":7535591},{"state":"California","population":39557045},{"state":"Oregon","population":4190714}]" 
 
You can separate the objects in the array by adding the expand command to the search: 
 

... | eval stateData=object_to_array(statePop,"state", "population") | expand stateData 
 

The results look something like this: 
 

Event 
 
stateData: "{"state":"Washington","population":7535591}"�h1h2h3}�h5Kuh�(h3h/�h}�ub�$26a5c183-2cff-457a-bf92-6472330763cb�h+)�}�(h}�(h/X... | eval stateData=object_to_array(statePop,"state", "population") | expand stateData 
 

The results look something like this: 
 

Event 
 
stateData: "{"state":"Washington","population":7535591}" 
 
stateData: "{"state":"California","population":39557045}" 
 
stateData: "{"state":"Oregon","population":4190714}" 
 
Converting nested objects into an array 
 

Consider the following field, called employees which consists of information about employees organized by city: 
 


{ 
 

    { 
 

      "lastName": "Martin", "firstName": "Alex", 
 

    }, 
 

      "employeeID": "015", 
 

      "department": "Sales", "hireDate": "2001-08-15 00:00:00.000" 
 

    { 
 

      "lastName": "Dubois", "firstName": "Maria", 
 

    } 
 

  "Prague": [ 
 

      "employeeID": "023", 
 

      "department": "Engineering", "hireDate": "2015-12-15 00:00:00.000" 
 

    { 
 

54 
 
      "employeeID": "025", 
 

      "department": "Sales", "hireDate": "2019-06-15 00:00:00.000" 
 

  ], 
 

    { 
 

      "lastName": "Zhang", "firstName": "Wei", 
 

    }, 
 

      "employeeID": "036", 
 

      "department": "Sales", "hireDate": "2018-04-15 00:00:00.000" 
 

  ] 
} 
 
Use the object_to_array function to create an array from the nested objects. 
 

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info") 
 

The results look something like this: 
 

Dept 
 
"[{"city":"Berlin","employee_info":[{"employeeID":"011","lastName":"Martin","firstName":"Alex","department":"Sales","hireDate":"2004-11-15 
00:00:00.000"},{"employeeID":"015","lastName":"Garcia","firstName":"Claudia","department":"Sales","hireDate":"2001-08-15 
00:00:00.000"},{"employeeID":"017","lastName":"Dubois","firstName":"Maria","department":"Marketing","hireDate":"2017-03-15 00:00:00.000"}]}, 
 







All of the Information appears on a single row. 
 


Add the expand command to the search to separate out each nested array: 
 

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info") | expand Dept 
 

The results look something like this: 
 

Dept�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5584c4fc-f544-4259-bf6c-86a318d44b82�h+)�}�(h}�(h/XFROM employees | eval Dept=object_to_array(employees,"city", "employee_info") | expand Dept 
 

The results look something like this: 
 

Dept 
 
{"city":"Berlin","employee_info":[{"employeeID":"011","lastName":"Martin","firstName":"Alex","department":"Sales","hireDate":"2004-11-15 
00:00:00.000"},{"employeeID":"015","lastName":"Garcia","firstName":"Claudia","department":"Sales","hireDate":"2001-08-15 
00:00:00.000"},{"employeeID":"017","lastName":"Dubois","firstName":"Maria","department":"Marketing","hireDate":"2017-03-15 00:00:00.000"}]} 
 
{"city":"Prague","employee_info":[{"employeeID":"023","lastName":"Sullivan","firstName":"Rutherford","department":"Engineering","hireDate":"2015-12-15 
00:00:00.000"},{"employeeID":"025","lastName":"Patel","firstName":"Vanya","department":"Sales","hireDate":"2019-06-15 00:00:00.000"}]} 
 
{"city":"Dublin","employee_info":[{"employeeID":"031","lastName":"Zhang","firstName":"Wei","department":"Human Resources","hireDate":"2019-09-15 
00:00:00.000"},{"employeeID":"036","lastName":"Mayer","firstName":"David","department":"Sales","hireDate":"2018-04-15 00:00:00.000"}]} 
 
Information for each city appears on a separate row. 
 


55 
 
Add the flatten command to the search to create fields for the city and employee_info information: 
 

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info") | expand Dept | flatten Dept 
 

The results look something like this: 
 

city 
 

employee_info 
 


Berlin 
 



Prague 
 



Dublin 
 




printf(<format>, <arguments>) 
 

This function builds a string value, based on a string format and the arguments specified. You can specify zero or more 
values. The values can be strings, numbers, computations, or fields. 
 

The SPL2 printf function is similar to the C sprintf() function and similar functions in other languages such as Python, 
Perl, and Ruby. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

format�h1h2h3}�h5Kuh�(h3h/�h}�ub�$22d0db1c-daab-442d-88b4-83054e22a981�h+)�}�(h}�(h/XPerl, and Ruby. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

format 
 


Description: The <format> is a character string that can include one or more format conversion specifiers. Each 
conversion specifier can include optional components such as flag characters, width specifications, and precision 
 

Syntax: "(%[flags][width][.precision]<conversion_specifier>)..." 
 

arguments 
 

<arguments> can be strings, numbers, or field names. 
Syntax: [width][.precision][value] 
 

Supported conversion specifiers 
 

The following table describes the supported conversion specifiers. 
 

Alias 
 

Description 
 

Examples 
 

56 
 
Conversion 
	specifier 
 


%a or %A 
 


Floating point number in hexadecimal 
format 
 
This example returns the value of pi to 3 decimal points, in hexadecimal 
format. 
 
printf("%.3A",pi()) which returns 0X1.922P+1 
 


%c 
 


Single Unicode code point 
 
This example returns the unicode code point for 65 and the first letter of 
the string "Foo". 
 
printf("%c,%c",65,"Foo") which returns A,F 
 


%d 
 


%i 
 


Signed decimal integer 
 
This example returns the positive or negative integer values, including 
any signs specified with those values. 
 
printf("%d,%i,%d",-2,+4,30) which returns -2,4,30 
 


%e or %E 
 

Floating point number, exponential 
format 
 
This example returns the number 5139 in exponential format with 2 
decimal points. 
printf("%.2e",5139) which returns 5.14e+03 
 
This example returns the value of pi to 2 decimal points. 
 
%f or %F 
 
Floating point number 
 
printf("%.2f",pi()) which returns 3.14 
 



%g or %G 
 


Floating point number. This specifier 
uses either %e or %f depending on the 
range of the numbers being formatted. 
 
This example returns the value of pi to 2 decimal points (using the %f 
specifier) and the number 123 in exponential format with 2 decimal points 
(using %e specifier). 
 
printf("%.2g,%.2g",pi(),123) which returns 3.1,1.2e+02�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2c7419ef-a59c-46fb-b705-706a9d0b49f4�h+)�}�(h}�(h/X[specifier) and the number 123 in exponential format with 2 decimal points 
(using %e specifier). 
 
printf("%.2g,%.2g",pi(),123) which returns 3.1,1.2e+02 
 
This example returns the base-8 number for 255. 
 
%o 
 
Unsigned octal number 
 
printf("%o",255) which returns 377 
 
This example returns the concatenated string values of "foo" and "bar". 
 
%s 
 
%z 
 
String 
 
printf("%s%z", "foo", "bar") which returns foobar 
 

%u 
 
Unsigned, or non-negative, decimal 
integer 
 
This example returns the integer value of the number in the argument. 
printf("%u,",99) which returns 99 
 



%x or %X 
 



%p 
 


Unsigned hexadecimal number 
(lowercase or uppercase) 
 
This example returns the hexadecimal values that are equivalent to the 
numbers in the arguments. This example shows both upper and 
lowercase results when using this specifier. 
 

printf("%x,%X,%p",10,10,10) which returns a,A,A 
 
This example returns the string value with a percent sign. 
 
%% 
 
Percent sign 
 
printf("100%%") which returns 100% 
 


57 
 
Flag characters 
 

The following table describes the supported flag characters. 
 

	Flag 
characters 
 


Description 
 


Examples 
 
single quote or 
apostrophe ( ' ) 
 

Adds commas as the thousands separator. 
 
printf("%'d",12345) which 
returns 12,345 
 
dash or minus ( 
- ) 
 

Left justify. If this flag is not specified, the is right-justified. 
 
printf("%-4d",1) which 
returns 1   
 




zero ( 0 ) 
 




Zero pad 
 
This example returns the value 
in the argument with leading 
zeros such that the number has 
4 digits. 
 

printf("%04d",1) which 
returns 0001 
 

plus ( + ) 
 
Always include the sign ( + or - ). If this flag is not specified, the conversion displays a sign 
only for negative values. 
 
printf("%+4d",1) which 
returns   +1 
 

<space> 
 
Reserve space for the sign. If the first character of a signed conversion is not a sign or if a 
signed conversion results in no characters, a <space> is added as a prefixed to the result. 
If both the <space> and + flags are specified, the <space> flag is ignored. 
 

printf("% -4d",1) which 
returns    1 
 



hash, number,�h1h2h3}�h5Kuh�(h3h/�h}�ub�$31b96cdc-3615-4e20-817b-e7079340781e�h+)�}�(h}�(h/X�If both the <space> and + flags are specified, the <space> flag is ignored. 
 

printf("% -4d",1) which 
returns    1 
 



hash, number, 
or pound ( # ) 
 
Use an alternate form. For the %o conversion specifier, the # flag increases the precision to 
force the first digit of the result to be zero. For %x or %X conversion specifiers, a non-zero 
result has 0x (or 0X) prefixed to it. For %a, %A, %e, %E, %f, %F, %%g , and G conversion 
specifiers, the result always contains a radix character, even if no digits follow the radix 
character. Without this flag, a radix character appears in the result of these conversions 
 



printf("%#x", 1) which 
returns 0x1 
 
removed from the result as they normally are. For other conversion specifiers, the behavior 
is undefined. 
 
Specifying field width 
 

You can use an asterisk ( * ) with the printf function to return the field width or precision from an argument. 
 

Examples 
 



printf("%*d", 5, 123) which returns  123 
 

The following example returns the floating point number with 1 decimal point. 
 


printf("%.*f", 1, 1.23) which returns 1.2 
 

The following example returns the value of pi() in exponential format with 2 decimal points. 
 


printf("%*.*e", 9, 2, pi()) which returns 3.14e+00 
 


58 
 
The field width can be expressed using a number or an argument denoted with an asterisk ( * ) character. 
 

Field width 
	specifier 
 


Description 
 


Examples 
 

number 
 
The minimum number of characters to print. If the value to print is shorter than this number, the result is 
padded with blank spaces. The value is not truncated even if the result is larger. 
 

* (asterisk) 
 
The width is not specified in the format string, but as an additional integer value argument preceding the 
argument that has to be formatted. 
 
Specifying precision 
 

Precision 
 

Description 
 

%d, %i, %o, %u, %x or %X 
 
Precision specifies the minimum number of digits to be return. If the value to be return is shorter than this�h1h2h3}�h5Kuh�(h3h/�h}�ub�$21ef8de7-489c-425a-a10c-1b0b796e269b�h+)�}�(h}�(h/X�Specifying precision 
 

Precision 
 

Description 
 

%d, %i, %o, %u, %x or %X 
 
Precision specifies the minimum number of digits to be return. If the value to be return is shorter than this 
number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A 
precision of 0 means that no character is returned for the value 0. 
 
%a or %A, %e or %E, %f or %F 
 
This is the number of digits to be returned after the decimal point. The default is 6 . 
 
%g or %G 
 
This is the maximum number of significant digits to be returned. 
 

%s 
 
This is the maximum number of characters to be returned. By default all characters are printed until the 
ending null character is encountered. 
 
Specifying the period without a 
precision value 
 

If the period is specified without an explicit value for precision, 0 is assumed. 
 
Specifying an asterisk for the 
precision value, for example .* 
 
The precision is not specified in the format string, but as an additional integer value argument preceding 
the argument that has to be formatted. 
 
Unsupported conversion specifiers 
 

There are a few conversion specifiers from the C sprintf() function that are not supported, including: 
 

•  %C, however %c is supported 
•  %n 
 

• %<num>$ specifier for picking which argument to use 
 

Basic examples 
 

This example creates a new field called new_field and creates string values based on the values in field_one and 
field_two. The values are formatted with 4 digits before the decimal and 4 digits after the decimal. The  - specifies to left 
 


...| eval new_field=printf("%04.4f %-30s",field_one,field_two) 
 



tojson(<internal_fields>) 
 

Returns a JSON object representation of events or search results. 
 





59 
 
Usage 
 

You can use this function with the eval and  where commands, in clauses of the from command that can take an 
expression, and as part of evaluation expressions with other commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$520fd84d-4a1e-4eca-8aa6-0a26b8bb385b�h+)�}�(h}�(h/XZ59 
 
Usage 
 

You can use this function with the eval and  where commands, in clauses of the from command that can take an 
expression, and as part of evaluation expressions with other commands. 
 

The <internal_fields> parameter is optional and used to specify whether fields that start with an underscore ( _ ) character, 
typically internal fields, are included in the JSON object. By default, <internal_fields> is set to "true". 
 



Examples 
 

1. Create a JSON object from a set of search results 
 

Consider the following search: 
 

FROM sample_data_index WHERE status=200 AND action="purchase" AND productId!="" | stats count() AS 'Total 
Purchased' , values(productId) AS 'Product IDs' BY clientip | rename clientip AS 'IP Addresses' 
 

This search returns results that look like this: 
 


IP Addresses 
 

	Total 
Purchased 
 


Product IDs 
 
107.3.146.207 
 
66 
 
BS-AG-G09,DC-SG-G02,MB-AG-T01,PZ-SG-G05,SC-MG-G10,WC-SH-A02,WC-SH-G04 
 
108.65.113.83 
 
30 
 
MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-A01,WC-SH-A02 
 
109.169.32.135 
 
24 
 
MB-AG-T01,SC-MG-G10,WC-SH-A01,WC-SH-T02 
 
110.138.30.229 
 
12 
 
SC-MG-G10,WC-SH-T02 
 
110.159.208.78 
 
54 
 
DB-SG-G01,DC-SG-G02,FI-AG-G08,MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-G04,WC-SH-T02 
 
To create a JSON object for each row in the search results, add the tojson function to the search: 
 

from sample_data_index where status=200 AND action="purchase" AND productId!="" | stats count() AS 'Total 
Purchased' , values(productId) AS 'Product IDs' BY clientip | rename clientip AS 'IP Addresses' | eval 
jsonObject = tojson() 
 


The JSON objects are placed into a new field called "jsonObject". The results look like this; 
 

	IP 
Addresses 
 

	Total 
Purchased 
 


Product IDs 
 

107.3.146.207 
 

66 
 

BS-AG-G09,DC-SG-G02,MB-AG-T01,PZ-SG-G05,SC-MG-G10,WC-SH-A02,WC-SH-G04 
 


108.65.113.83 
 

30 
 


MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-A01,WC-SH-A02 
 

109.169.32.135 
 

24 
 

MB-AG-T01,SC-MG-G10,WC-SH-A01,WC-SH-T02 
 

110.138.30.229 
 

12 
 

SC-MG-G10,WC-SH-T02 
 


60 
 
	IP 
Addresses 
 
	Total 
Purchased 
 
Product IDs 
 


110.159.208.78 
 


54�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b0a4a556-603e-46db-a00c-ad76da1488c0�h+)�}�(h}�(h/X�109.169.32.135 
 

24 
 

MB-AG-T01,SC-MG-G10,WC-SH-A01,WC-SH-T02 
 

110.138.30.229 
 

12 
 

SC-MG-G10,WC-SH-T02 
 


60 
 
	IP 
Addresses 
 
	Total 
Purchased 
 
Product IDs 
 


110.159.208.78 
 


54 
 


DB-SG-G01,DC-SG-G02,FI-AG-G08,MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-G04,WC-SH-T02 
 

2. Create a JSON object from dataset literal 
 

Here's another example. Consider this search, which uses a dataset literal to create an event: 
 

FROM [{code: 200}, {code: 401, error_type: "auth"}] | eval _time = now() 
 

This search returns results that look like this: 
 

_time 
 

code 
 

error_type 
 
4:02:17 PM, 11 Apr 2022 
 
200 
 
NULL 
 
4:02:17 PM, 11 Apr 2022 
 
401 
 
auth 
 
You can use the tojson function to place all of fields in the event into a JSON object in the _raw field: 
 

FROM [{code: 200}, {code: 401, error_type: "auth"}] | eval _time = now() | eval _raw = tojson() 
 

This search returns results that look like this: 
 

_time 
 

_raw 
 

code 
 

error_type 
 
4:02:17 PM, 11 Apr 2022 
 
{"_time":1649718137,"code":200} 
 
200 
 
NULL 
 
4:02:17 PM, 11 Apr 2022 
 
{"_time":1649718137,"code":401,"error_type":"auth"} 
 
401 
 
auth 
 
tonumber(<str>, <base>) 
 

This function converts a string to a number. The base is optional. If not specified, base 10 is used. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The <str> can be a field name or a value. 
 

The <base> is used to define the base of the number in <str>. The <base> can be 2 to 36. The default is 10, which 
corresponds to the decimal system. 
 

If the tonumber function cannot parse a field value to a number, for example if the value contains a leading and trailing 
space, the function returns NULL. Use the trim function to remove leading or trailing spaces. 
 

If the tonumber function cannot parse a literal string to a number, the function returns an error. 
 

Basic examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$72b94e28-22a3-493e-92fa-64668b6fa2f0�h+)�}�(h}�(h/X�If the tonumber function cannot parse a literal string to a number, the function returns an error. 
 

Basic examples 
 

The following example converts the string values for the store_sales field to numbers. This example uses the default 
<base>. 
 

61 
 
... | eval n=tonumber(store_sales) 
 


The following example takes the hexadecimal number and uses a <base> of 16 to return the number "164". 
 

... | eval n=tonumber("0A4",16) 
 


The following example trims any leading or trailing spaces from the values in the celsius field before converting it to a 
number. 
 

... | eval temperature=tonumber(trim(celsius)) 
 

tostring(<value>, <format>) 
 

This function converts a value to a string using the specified format. 
 

If the input value is a number, it reformats it as a string. If the input value is a Boolean value, it returns the corresponding 
string value, "True" or "False". 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

When used with the eval command, the values might not sort as expected because the values are converted to ASCII. 
Use the fieldformat command with the tostring function to format the displayed values. The underlying values are not 
changed with the fieldformat command. 
 

If <value> is a number, the second argument <format> is optional and can be "hex", "commas", or "duration". 
 

Examples 
 

Description 
 
tostring(<value>,"hex") 
 
Converts <value> to hexadecimal. 
 

tostring(<value>,"commas") 
 
Formats <value> with commas. If the number includes decimals, the function rounds to nearest two 
decimal places. 
 
tostring(<value>,"duration") Converts a <value> that is in seconds to the readable time format HH:MM:SS. 
 
Basic examples 
 

The following example returns period=615 and period_time=00:10:15. The 615 seconds is converted into minutes and 
seconds. 
 

... | eval period=615 | eval period_time = tostring(period, "duration")�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a4af6c9f-7b8b-488f-89c4-3d4c8a08c063�h+)�}�(h}�(h/X�The following example returns period=615 and period_time=00:10:15. The 615 seconds is converted into minutes and 
seconds. 
 

... | eval period=615 | eval period_time = tostring(period, "duration") 
 


The following example returns "True 0xF 12,345.68". 
 

... | eval n=tostring(1==1) + " " + tostring(15, "hex") + " " + tostring(12345.6789, "commas") 
 





62 
 
See also 
 

Function information 
 

Overview of SPL2 eval functions 
 


Specific functions 
	mv_to_json_array 
	strptime 
 


Cryptographic functions 
 
The following list contains the functions that you can use to compute the secure hash of string values. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

md5(<str>) 
 

This function computes and returns the MD5 hash of a string value. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns a new field n with a message-digest (MD5) 128-bit hash value for the phrase "Hello World". 
 

... | eval n=md5("Hello World") 
 


The following example uses the md5 function, along with several other functions, to create a large random string. 
 

| makeresults count=32768 | eval message=md5("". random()) | stats values(message) as message | eval message 
= mvjoin(message, "") 
 

• The makeresults command creates 32768 results with timestamps. 
• The eval command creates a new field called message: 
 

	the numeric number generated by the random function into a string value. 
♦ The md5 function creates a 128-bit hash value from the string value. 
 

• The stats command with the values function is used to convert the individual random values into one multivalue 
	result. 
 





63 
 
sha1(<str>) 
 

This function computes and returns the secure hash of a string value, based on the FIPS compliant SHA-1 hash function. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c007ae44-4559-4761-bd61-3a646916918d�h+)�}�(h}�(h/X�result. 
 





63 
 
sha1(<str>) 
 

This function computes and returns the secure hash of a string value, based on the FIPS compliant SHA-1 hash function. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns the secure hash for the string, using the Secure Hash Algorithm 1 (SHA1). 
 

... | eval n=sha1("Turn Data Into Doing") 
 

sha256(<str>) 
 

This function computes and returns the secure hash of a string value, based on the FIPS compliant SHA-256 (SHA-2 
family) hash function. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns the secure hash for the string, using the Secure Hash Algorithm 256 (SHA256). 
 

... | eval n=sha256("Put that in your | and Splunk it") 
 

sha512(<str>) 
 

This function computes and returns the secure hash of a string value, based on the FIPS compliant SHA-512 (SHA-2 
family) hash function. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns the secure hash for the string, using the Secure Hash Algorithm 512 (SHA512). 
 

... | eval n=sha512("You bet your sweet SaaS.") 
 

See also 
 

Function information 
 



64 
 
Overview of SPL2 eval functions 
 



Date and Time functions 
 
The following list contains the functions that you can use to calculate dates and time. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

now() 
 

This function takes no arguments and returns the time that the search was started. 
 

Usage 
 

The now() function is often used with other data and time functions.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7ab013ee-6c8e-4102-8806-8b6dcf37acb3�h+)�}�(h}�(h/Xfunctions. 
 

now() 
 

This function takes no arguments and returns the time that the search was started. 
 

Usage 
 

The now() function is often used with other data and time functions. 
 

The time returned by the now() function is represented in UNIX time, or in seconds since Epoch time. 
 

When used in a search, this function returns the UNIX time when the search is run. If you want to return the UNIX time 
when each result is returned, use the time() function instead. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example determines the UNIX time value of the start of yesterday, based on the value of now(). 
 

... | eval n=relative_time(now(), "-1d@d") 
 

Extended example 
 

If you are looking for events that occurred within the last 30 minutes you need to calculate the event hour, event minute, 
the current hour, and the current minute. You use the now() function to calculate the current hour (curHour) and current 
minute (curMin). The event timestamp, in the _time field, is used to calculate the event hour (eventHour) and event minute 
 


... earliest=-30d | eval eventHour=strftime(_time,"%H") | eval eventMin=strftime(_time,"%M") | eval 
curHour=strftime(now(),"%H") | eval curMin=strftime(now(),"%M") | where (eventHour=curHour and eventMin > 
curMin - 30) or (curMin < 30 and eventHour=curHour-1 and eventMin>curMin+30) | bin _time span=1d | timechart 
count() by _time 
 

relative_time(<time>,<specifier>) 
 

This function takes a UNIX time and a relative time specifier and returns the UNIX time value of the specifier applied to 
the time. 
 




65 
 
Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example determines the UNIX time value of the start of yesterday, based on the value of now().�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4196d733-1104-4d3f-8e61-05a2ccf32e07�h+)�}�(h}�(h/Xof evaluation expressions with other commands. 
 

Basic examples 
 

The following example determines the UNIX time value of the start of yesterday, based on the value of now(). 
 

... | eval n=relative_time(now(), "-1d@d") 
 

The following example specifies an earliest time of 2 hours ago snapped to the hour and a latest time of 1 hour ago 
snapped to the hour: 
 

... | where _time>relative_time(now(), "-2h@h") AND _time<relative_time(now(), "-1h@h") 
 

strftime(<time>,<format>) 
 

This function takes a UNIX time value and renders the time as a string using the format specified. The UNIX time must be 
in seconds. Use the first 10 digits of a UNIX time to use the time in seconds. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Converting time into seconds 
 

If the time is in milliseconds, microseconds, or nanoseconds you must convert the time into seconds. You can use the pow 
function to convert the number. 
 

• To convert from milliseconds to seconds, divide the number by 1000 or 10^3. 
• To convert from microseconds to seconds, divide the number by 10^6. 
 


The following search uses the pow function to convert from nanoseconds to seconds: 
 

| from [{ }] | eval StartTimestamp="1566554581000" | eval 
starttime=strftime(StartTimestamp/pow(10,9),"%Y-%m-%dT%H:%M:%S.%Q") 
 


The results look like this: 
 

StartTimeStamp 
 

_time 
 

starttime 
 
1566554581000 
 
2019-08-23 10:03:01 
 
2019-08-23T03:03:01.000 
 
In these results the _time value is the date and time when the search was run. 
 


For a complete list and descriptions of the format options you can use, see Using time variables in the SPL2 Search 
Manual. 
 



66 
 
Basic example 
 

The following example returns the hour and minute from the _time field. 
 

...| eval hour_min=strftime(_time, "%H:%M") 
 

If the _time field value is 2022-08-10 11:48:23, the value returned in the hour_min field is 11:48. 
 

Extended example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f0a4e043-d6e0-4724-a71a-0a3e26d43936�h+)�}�(h}�(h/X�...| eval hour_min=strftime(_time, "%H:%M") 
 

If the _time field value is 2022-08-10 11:48:23, the value returned in the hour_min field is 11:48. 
 

Extended example 
 

The following example creates a single result using the from command. 
 

| from [{ }] 
 

For example: 
 

_time 
 
2022-08-22 14:00:15 
 
The _time field is stored in UNIX time, even though it displays in a human readable format. To convert the UNIX time to 
some other format, you use the strftime function with the date and time format variables. The variables must be in 
quotations marks. 
 

For example, to return the week of the year that an event occurred in, use the %V variable. 
 

| from [{ }] | eval week=strftime(_time,"%V") 
 

The results are show the value 34 for week. 
 

_time 
 

week 
 
2022-08-22 14:00:15 
 
34 
 
To return the date and time with subseconds and the time designator (the letter T) that precedes the time components of 
the format, use the %Y-%m-%dT%H:%M:%S.%Q variables. For example: 
 

| from [{ }] | eval mytime=strftime(_time,"%Y-%m-%dT%H:%M:%S.%Q") 
 

The results are: 
 

_time 
 

mytime 
 
2022-08-22 14:00:15 
 
2022-08-22T14:00:15.000 
 
strptime(<str>, <format>) 
 

Takes a human readable time, represented by a string, and parses the time into a UNIX timestamp using the format you 
specify. You use date and time variables to specify the format that matches string. The strptime function doesn't work 
with timestamps that consist of only a month and year. The timestamps must include a day. 
 

For example, if the string is 2022-08-22 17:19:01, the format must be %Y-%m-%d %H:%M:%S . The string date must be 
January 1, 1971 or later. The strptime function takes any date from January 1, 1971 or later, and calculates the UNIX 
 




67 
 
The _time field is in UNIX time. In Splunk Web, the _time field appears in a human readable format in the UI but is 
stored in UNIX time. If you attempt to use the strptime function on the _time field, no action is performed on the values 
in the field. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6c212eb0-447b-417c-ac96-8ee395756c98�h+)�}�(h}�(h/X.stored in UNIX time. If you attempt to use the strptime function on the _time field, no action is performed on the values 
in the field. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

With the strptime function, you must specify the time format of the string so that the function can convert the string time 
into the correct UNIX time. The following table shows some examples: 
 

String time 
 

Matching time format variables 
 
Mon August 22 2022 17:19:01.89  %a %B %d %Y %H:%M:%S.%N 
 
Mon 8/22/2022 17:19:01.89 
 
%a %m/%d/%Y %H:%M:%S.%N 
 
2022/08/22 17:19:01.89 
 
%Y/%m/%d %H:%M:%S.%N 
 
2022-08-22T17:19:01.89 
 
%Y-%m-%dT%H:%M:%S.%N 
 

For a complete list and descriptions of the format options you can use, see Using time variables in the SPL2 Search 
Manual. 
 

Basic example 
 

If the values in the timeStr field are hours and minutes, such as 11:59, the following example returns the time as a 
timestamp: 
 

... | eval n=strptime(timeStr, "%H:%M") 
 

Extended example 
 

This example shows the results of using the strptime function. 
 

Let's say you have a series of start and end times such as these: 
 

starttime 
 

endtime 
 
Mon Aug 12 00:00:00 2019 
 
Mon Aug 12 05:59:59 2019 
 
Mon Aug 12 06:00:00 2019 
 
Mon Aug 12 11:59:59 2019 
 
Mon Aug 12 12:00:00 2019 
 
Mon Aug 12 17:59:59 2019 
 
Mon Aug 12 18:00:00 2019 
 
Mon Aug 12 23:59:59 2019 
 
Tue Aug 13 00:00:00 2019 
 
Tue Aug 13 05:59:59 2019 
 
Tue Aug 13 06:00:00 2019 
 
Tue Aug 13 11:59:59 2019 
 
Tue Aug 13 12:00:00 2019 
 
Tue Aug 13 17:59:59 2019 
 
Tue Aug 13 18:00:00 2019 
 
Tue Aug 13 23:59:59 2019 
 

68 
 
starttime 
 
endtime 
 

When you run the following search, the eval command takes the string time values in the starttime field and returns the 
UNIX time that corresponds to the string time values. 
 

...| eval startunix=strptime(starttime,"%a %B %d %H:%M:%S.%N %Y") 
 

The results look something like this: 
 

starttime 
 

endtime 
 

startunix�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aaef299a-5500-44a2-bbd2-cfb9b9f22a18�h+)�}�(h}�(h/XUNIX time that corresponds to the string time values. 
 

...| eval startunix=strptime(starttime,"%a %B %d %H:%M:%S.%N %Y") 
 

The results look something like this: 
 

starttime 
 

endtime 
 

startunix 
 
Mon Aug 23 00:00:00 2019 
 
Mon Aug 23 05:59:59 2019 
 
534143600.000000 
 
Mon Aug 12 06:00:00 2019 
 
Mon Aug 12 11:59:59 2019 
 
1534165200.000000 
 
Mon Aug 12 12:00:00 2019 
 
Mon Aug 12 17:59:59 2019 
 
534186800.000000 
 
Mon Aug 12 18:00:00 2019 
 
Mon Aug 12 23:59:59 2019 
 
1534208400.000000 
 
Tue Aug 13 00:00:00 2019 
 
Tue Aug 13 05:59:59 2019 
 
1534230000.000000 
 
Tue Aug 13 06:00:00 2019 
 
Tue Aug 13 11:59:59 2019 
 
1534251600.000000 
 
Tue Aug 13 12:00:00 2019 
 
Tue Aug 13 17:59:59 2019 
 
1534273200.000000 
 
Tue Aug 13 18:00:00 2019 
 
Tue Aug 13 23:59:59 2019 
 
1534294800.000000 
 
time() 
 

This function returns the wall-clock time, in the UNIX time format, with microsecond resolution. 
 

Usage 
 

The value of the time() function will be different for each event, based on when the event is processed. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example shows the results of using the time() function. 
 

Let's consider the following times: 
 

starttime 
 

starthuman 
 
1534143600 
 
Mon Aug 13 00:00:00 2018 
 
1534165200 
 
Mon Aug 13 06:00:00 2018 
 
1534186800 
 
Mon Aug 13 12:00:00 2018 
 
1534208400 
 
Mon Aug 13 18:00:00 2018 
 
1534230000 
 
Tue Aug 14 00:00:00 2018 
 
1534251600 
 
Tue Aug 14 06:00:00 2018 
 


69 
 
starttime 
 
starthuman 
 
1534273200 
 
Tue Aug 14 12:00:00 2018 
 
1534294800 
 
Tue Aug 14 18:00:00 2018 
 
To return the UNIX time when a result is processed, you first need to convert the startime values to include 
microseconds. 
 

... | eval epoch_time=strptime(starttime,"%s") | eval testtime=time() 
 

• The first eval command takes the numbers in the startime field and returns them with microseconds included.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$092deba2-61c5-4464-b8cf-d53df1a06a41�h+)�}�(h}�(h/X�microseconds. 
 

... | eval epoch_time=strptime(starttime,"%s") | eval testtime=time() 
 

• The first eval command takes the numbers in the startime field and returns them with microseconds included. 
• The second eval command creates the testtime field and returns the UNIX time at the instant the result was 
 



The results look something like this: 
 

starttime 
 

starthuman 
 

epoch_time 
 

testtime 
 
1534143600 
 
Mon Aug 13 00:00:00 2018 
 
1534143600.000000 
 
1534376565.299298 
 
1534165200 
 
Mon Aug 13 06:00:00 2018 
 
1534165200.000000 
 
1534376565.299300 
 
1534186800 
 
Mon Aug 13 12:00:00 2018 
 
1534186800.000000 
 
1534376565.299302 
 
1534208400 
 
Mon Aug 13 18:00:00 2018 
 
1534208400.000000 
 
1534376565.299304 
 
1534230000 
 
Tue Aug 14 00:00:00 2018 
 
1534230000.000000 
 
1534376565.299305 
 
1534251600 
 
Tue Aug 14 06:00:00 2018 
 
1534251600.000000 
 
1534376565.299306 
 
1534273200 
 
Tue Aug 14 12:00:00 2018 
 
1534273200.000000 
 
1534376565.299308 
 
1534294800 
 
Tue Aug 14 18:00:00 2018 
 
1534294800.000000 
 
1534376565.299309 
 
Notice the difference in the microseconds between the values in the epoch_time and test_time fields. You can see that 
the test_time values increase with each result. 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 



Informational functions 
 
The following list contains the functions that you can use to return information about a value. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 







70 
 
cluster(<field>,<threshold>,<match>,<delims>) 
 

This function generates a cluster label, in the form of a number, for each event based on how similar the events are to 
each other. The cluster label represents which cluster the event belongs to. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d9b1615c-56b3-4b81-96ea-a0d8a4b99c89�h+)�}�(h}�(h/XUsage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The cluster label is generated by using a clustering algorithm. The similarity of the events is determined by comparing the 
values in a specific field. 
 

The following table defines the parameters you can use with the cluster function: 
 

Parameter 
 

Description 
 
field 
 
Required. The field that you want to analyze and cluster on. 
 



threshold 
 
Optional. The threshold parameter controls the sensitivity of the clustering. Must be a float number greater than 0.0 and less 
than 1.0, such as threshold:0.5F. The closer the threshold is to 1.0, the more similar events must be to be considered in the 
same cluster. 
 

The default threshold is 0.8F. 
 
Optional. The match parameter selects the method used to determine the similarity between events. There are three match 
methods: 
 


match 
 
• termlist method breaks down the field into words and requires the exact same ordering of terms. 
• termset method breaks down the field into words and allows for an unordered set of terms. 
 
processing on large field values and is most useful for short non-textual fields, like the punct field. 
 

The default method is termlist. 
 
Optional. The delims parameter uses a delimiter to tokenize the content of field, 
 

delims 
 

such as a comma ( , ) or a pipe ( | ). 
 

There is no default delimiter. The field value is processed as a single string. 
 
You can use this function with the eval and  where commands, in the WHERE and SELECT clauses of the from 
command, and as part of evaluation expressions with other commands. 
 

Examples 
 

The following example clusters the events by the values in the _raw field. The events are then sorted by the cluster 
number. 
 

... | eval cluster_number = cluster(_raw) | sort - cluster_number 
 


This example is similar to the previous example, but uses the cluster function in the SELECT clause of the from 
command: 
 


71�h1h2h3}�h5Kuh�(h3h/�h}�ub�$535a42ae-650c-457b-8d74-ad01db530162�h+)�}�(h}�(h/X... | eval cluster_number = cluster(_raw) | sort - cluster_number 
 


This example is similar to the previous example, but uses the cluster function in the SELECT clause of the from 
command: 
 


71 
 
from main select _raw, cluster(_raw) orderby cluster_number 
 


The following example clusters the events by the values in the _raw field using a threshold of 0.9F . The events are then 
sorted by the cluster_label field. 
 

... | eval cluster_label = cluster(_raw, cluster_threshold:0.9F) | sort cluster_label 
 

Consider this set of events: 
 

_time 
 

_raw 
 

2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD5SL6FF7ADFF53001","_raw":"12.130.60.5 - - [20/Jul/2021:17:57:58] \"POST 
/cart/error.do?msg=CreditDoesNotMatch&JSESSIONID=SD5SL6FF7ADFF53001 HTTP 1.1\" 200 ... } 
 

2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD10SL4FF2ADFF48107","_raw":"125.17.14.100 - - [20/Jul/2021:00:58:04] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD10SL4FF2ADFF48107 HTTP 1.1\" 200 ... } 
 

2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD6SL8FF9ADFF43007","_raw":"107.3.146.207 - - [19/Jul/2021:06:37:51] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD6SL8FF9ADFF43007 HTTP 1.1\" 200 ... } 
 

2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD6SL8FF9ADFF43007","_raw":"107.3.146.207 - - [18/Jul/2021:06:37:48] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD6SL8FF9ADFF43007 HTTP 1.1\" 200 ... } 
 

2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD1SL8FF9ADFF40501","_raw":"124.160.192.241 - - [18/Jul/2021:22:26:31] \"POST 
/cart/error.do?msg=CreditNotAccepted&JSESSIONID=SD1SL8FF9ADFF40501 HTTP 1.1\" 200 ... } 
 
The results look like this: 
 

_time 
 

_raw 
 

cluster_label 
 


2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD5SL6FF7ADFF53001","_raw":"12.130.60.5 - - 
[20/Jul/2021:17:57:58] \"POST 
/cart/error.do?msg=CreditDoesNotMatch&JSESSIONID=SD5SL6FF7ADFF53001 
HTTP 1.1\" 200 ... } 
 


1 
 


2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD10SL4FF2ADFF48107","_raw":"125.17.14.100 - - 
[20/Jul/2021:00:58:04] \"POST�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2bf736c2-a5b4-4f27-a549-dd56608d086f�h+)�}�(h}�(h/XHTTP 1.1\" 200 ... } 
 


1 
 


2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD10SL4FF2ADFF48107","_raw":"125.17.14.100 - - 
[20/Jul/2021:00:58:04] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD10SL4FF2ADFF48107 
HTTP 1.1\" 200 ... } 
 


1 
 


2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD6SL8FF9ADFF43007","_raw":"107.3.146.207 - - 
[19/Jul/2021:06:37:51] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD6SL8FF9ADFF43007 
 


2 
 



2021-07-21T00:57:58.000+00:00 
 

{"JSESSIONID":"SD6SL8FF9ADFF43007","_raw":"107.3.146.207 - - 
[18/Jul/2021:06:37:48] \"POST 
/cart/error.do?msg=CanNotGetCart&JSESSIONID=SD6SL8FF9ADFF43007 
HTTP 1.1\" 200 ... } 
 



3 
 


2021-07-21T00:57:58.000+00:00 
 
{"JSESSIONID":"SD1SL8FF9ADFF40501","_raw":"124.160.192.241 - - 
[18/Jul/2021:22:26:31] \"POST 
/cart/error.do?msg=CreditNotAccepted&JSESSIONID=SD1SL8FF9ADFF40501 
HTTP 1.1\" 200 ... } 
 


3 
 




72 
 
getfields(<filter>) 
 

Returns a JSON array populated with JSON objects, where each object represents a field and its value. 
 

The array that's returned is structured like this [{name:<field_name>, value: <field_value>}]. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The filter parameter is optional. When specified, the filter populates the array with only the field names that match the 
filter. The filter can contain up to 3 wildcards. When wildcards are specified, a segment array is added to the JSON object 
the represent the field name segments which match each wildcard. See Examples. 
 

Examples 
 

The following example shows the results when the getfields function is used on a set of columns. Consider this set of 
events: 
 

code 
 

error_type 
 
200 
 
401 
 
auth 
 
The following search uses the getfields function without a filter: 
 

... | eval rowData = getfields() 
 

The results look like this: 
 

code 
 

error_type 
 

rowData 
 
200 
 
[{"name":"code","value":200}] 
 
401 
 
auth�h1h2h3}�h5Kuh�(h3h/�h}�ub�$546a1dce-efad-49e7-94b5-ebfcf970bb14�h+)�}�(h}�(h/Xj... | eval rowData = getfields() 
 

The results look like this: 
 

code 
 

error_type 
 

rowData 
 
200 
 
[{"name":"code","value":200}] 
 
401 
 
auth 
 
[{"name":"code","value":401},{"name":"error_type","value":"auth"}] 
 

The following example shows how to use a filter with the getfields function. Consider this set of events which contain 
information about the status of various servers: 
 

_time 
 

status_www1_east1 
 

status_www1_south1 
 

status_www2_west1 
 
7 Nov 2022 9:00 PM 
 
200 
 
404 
 
200 
 
7 Nov 2022 8:00 PM 
 
404 
 
200 
 
200 
 
The field names consist of three parts: 
 

• The word status 
 

• The location of the server, such as east1 
 

You can use a filter with wildcards to return information only from these fields and collect the statuses of all of your 
servers. For example: 
 

73 
 
... | eval serverData = getfields('status_*_*') 
 

The results look like this: 
 

_time 
 

serverData 
 

status_www1_east1 
 
7 Nov 
2022 
9:00 
PM 
 


[] 
 


NULL 
 


NULL 
 
[{"name":"status_www1_east1","value":200,"segments":["www1","east1"]}] 
 
200 
 
NULL 
 
[{"name":"status_www1_east1","value":404,"segments":["www1","south1"]}] 
 
NULL 
 
404 
 
[{"name":"status_www1_east1","value":200,"segments":["www2","west1"]}] 
 
NULL 
 
NULL 
 
7 Nov 
2022 
8:00 
PM 
 


[] 
 


NULL 
 


NULL 
 
[{"name":"status_www1_east1","value":404,"segments":["www1","east1"]}] 
 
404 
 
NULL 
 
[{"name":"status_www1_east1","value":200,"segments":["www1","south1"]}] 
 
NULL 
 
200 
 
[{"name":"status_www1_east1","value":200,"segments":["www2","west1"]}] 
 
NULL 
 
NULL 
 
isbool(<value>) 
 

This function returns TRUE if the value is Boolean. 
 

Usage 
 

Use this function with other functions that return Boolean data types, such as cidrmatch and mvfind. 
 

This function cannot be used to determine if field values are "true" or "false" because field values are either string or 
number data types. Instead, use syntax such as <fieldname>=true OR <fieldname>=false to determine field values. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4c9edeb9-6789-4667-b560-c3b90bf321f7�h+)�}�(h}�(h/XYou can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

The following example shows how to uses the where command to determine if the values in the encrypted field are 
Boolean values. 
 

... | where isbool(encrypted) 
 

isint(<value>) 
 

This function returns TRUE if the value is an integer. 
 






74 
 
Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example uses the isint function with the if function. A field, "n", is added to each result with a value of "int" 
or "not int", depending on the result of the isint function. If the value of "field" is a number, the isint function returns 
TRUE and the value adds the value "int" to the "n" field. 
 

... | eval n=if(isint(field),"int", "not int") 
 

The following example shows how to use the isint function with the where command. 
 

... | where isint(field) 
 



isnotnull(<value>) 
 

This function returns TRUE if the value is not NULL. 
 

Usage 
 

This function is useful for checking for whether or not a field contains a value. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example uses the isnotnull function with the if function. A field, "n", is added to each result with a value of 
"yes" or "no", depending on the result of the isnotnull function. If the value of "field" is a number, the isnotnull function 
returns TRUE and the value adds the value "yes" to the "n" field. 
 

... | eval n=if(isnotnull(field),"yes","no") 
 


The following example shows how to use the isnotnull function with the where command. 
 

... | where isnotnull(field) 
 



isnull(<value>) 
 

This function returns TRUE if the value is NULL. 
 






75 
 
Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c6af1322-bc2f-4ee1-8c32-16869a74349b�h+)�}�(h}�(h/X�The following example shows how to use the isnotnull function with the where command. 
 

... | where isnotnull(field) 
 



isnull(<value>) 
 

This function returns TRUE if the value is NULL. 
 






75 
 
Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example uses the isnull function with the if function. A field, "n", is added to each result with a value of 
"yes" or "no", depending on the result of the isnull function. If there is no value for "field" in a result, the isnull function 
returns TRUE and adds the value "yes" to the "n" field. 
 

... | eval n=if(isnull(field),"yes","no") 
 


The following example shows how to use the isnull function with the where command. 
 

... | where isnull(field) 
 

isnum(<value>) 
 

This function returns TRUE if the value is a number. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example uses the isnum function with the if function. A field, "n", is added to each result with a value of 
"yes" or "no", depending on the result of the isnum function. If the value of "field" is a number, the isnum function returns 
TRUE and the value adds the value "yes" to the "n" field. 
 

... | eval n=if(isnum(field),"yes","no") 
 


The following example shows how to use the isnum function with the where command. 
 

... | where isnum(field) 
 



isstr(<value>) 
 

This function returns TRUE if the value is a string. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 



76 
 
Examples 
 

The following example uses the isstr function with the if function. A field, "n", is added to each result with a value of�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aa5f6aea-b2f0-458c-8fed-03b157a864c7�h+)�}�(h}�(h/Xof evaluation expressions with other commands. 
 



76 
 
Examples 
 

The following example uses the isstr function with the if function. A field, "n", is added to each result with a value of 
"yes" or "no", depending on the result of the isstr function. If the value of "field" is a string, the isstr function returns 
TRUE and the value adds the value "yes" to the "n" field. 
 

... | eval n=if(isstr(field),"yes","no") 
 


The following example shows how to use the isstr function with the where command. 
 

... | where isstr(field) 
 



typeof(<value>) 
 

This function returns the data type of the value. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

The following example takes one argument and returns a string representation of its type. This example returns 
"NumberStringBoolInvalid" 
 

... | eval n=typeof(12) + typeof("string") + typeof(1==2) + typeof(badfield) 
 


The following example creates a single result using an empty dataset literal. 
 

from [{ }] 
 

For example: 
 

_time 
 
2019-08-23T10:03:01.000-0700 
 
To determine the data type of the _time field, use the eval command with the typeof function. For example: 
 

| from [{ }] | eval t=typeof(_time) 
 

The results are: 
 

_time 
 

t 
 
2019-08-23T10:03:01.000-0700 
 
Number 
 




77 
 
See also 
 

Function information 
 

Overview of SPL2 eval functions 
 


Related information 
 



JSON functions 
 
The following table describes the functions that are available for you to use to create or manipulate JSON objects: 
 

Description 
 

JSON function 
 
Creates a new JSON object from key-value pairs. 
 
json_object 
 
Appends elements to the contents of a valid JSON object. 
 
json_append 
 
Creates a JSON array using a list of values. 
 
json_array 
 
Maps the elements of a JSON array to a multivalued field. 
 
json_array_to_mv 
 
Extends the contents of a valid JSON object with the values of an array. 
 
json_extend�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4531f1d4-d987-4e4b-ba7f-5a4a7b969a2c�h+)�}�(h}�(h/X�json_array 
 
Maps the elements of a JSON array to a multivalued field. 
 
json_array_to_mv 
 
Extends the contents of a valid JSON object with the values of an array. 
 
json_extend 
 
Returns either a JSON array or a Splunk software native type value from a field and zero or more paths. 
 
json_extract 
 
Returns Splunk software native type values from a piece of JSON by matching literal strings in the event and extracting the 
strings as keys. 
 

json_extract_exact 
 
Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array. 
 
json_keys 
 
Inserts or overwrites values for a JSON node with the values provided and return an updated JSON object. 
 
json_set 
 
Generates or overwrites a JSON object using the key-value pairs specified. 
 
json_set_exact 
 
Evaluates whether a JSON object uses valid JSON syntax and returns either TRUE or FALSE. 
 
json_valid 
 
In addition, there are multivalue and conversion functions that create JSON arrays or objects: mv_to_json_array and 
tojson 
 

json_object(<members>) 
 

Creates a new JSON object from members of key-value pairs. 
 

Usage 
 

If you specify a string for a <key> or <value>, you must enclose the string in double quotation marks. A <key> must be a 
string. A <value> can be a string, number, Boolean, null, multivalue field, array, or another JSON object. 
 

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of 
evaluation expressions with other commands. See the eval, where, and from commands. 
 





78 
 
Examples 
 

These examples show different ways to use the json_object function to create JSON objects in your events. 
 

1. Create a basic JSON object 
 

The following example creates a basic JSON object { "name": "maria" }. 
 

... | eval name = json_object("name", "maria") 
 

2. Create a JSON object using a multivalue field 
 

The following example creates a multivalue field called firstnames that uses the key name and contains the values�h1h2h3}�h5Kuh�(h3h/�h}�ub�$bb4f3e9f-4260-4f5e-ae79-2c5874af1731�h+)�}�(h}�(h/X�2. Create a JSON object using a multivalue field 
 

The following example creates a multivalue field called firstnames that uses the key name and contains the values 
"maria" and "arun". The JSON object created is { "name": ["maria", "arun"] } . 
 

... | eval firstnames = json_object("name", mvappend("maria", "arun")) 
 

3. Create a JSON object using a JSON array 
 

The following example creates a JSON object that uses a JSON array for the values. 
 

... | eval locations = json_object("cities", json_array("London", "Sydney", "Berlin", "Santiago")) 
 

The result is the JSON object { "cities": ["London", "Sydney", "Berlin", "Santiago"] }. 
 

4. Create a nested JSON object 
 

The following example creates a nested JSON object that uses other JSON objects and a multivalue or JSON 
array field called gamelist. 
 

...| eval games = json_object("category", json_object("boardgames", json_object("cooperative", 
gamelist))) 
 

The result is this JSON object: 
 


{ 
 

    "category": { 
 

        "cooperative": [ "Pandemic", "Forbidden Island", "Castle Panic" ] 
 

    } 
 

} 
 


json_append(<json>, <path_value_pairs>) 
 

This function appends values to the ends of indicated arrays within a JSON document. This function provides a JSON 
eval function equivalent to the multivalue mvappend function. 
 






79 
 
Usage 
 

The json_append function always has at least three function inputs: <json> (the name of a valid JSON document such as 
a JSON object), and at least one <path> and <value> pair. 
 

If <json> does not reference a valid JSON document, such as a JSON object, the function outputs nothing. 
 

The json_append function evaluates <path_value_pairs> from left to right. When a path-value pair is evaluated, the 
function updates the <json> document. The function then evaluates the next path-value pair against the updated 
document. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$70e9126b-2a2d-4cd3-a3e5-cd27cb8ad6f5�h+)�}�(h}�(h/X�document. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Use <path> to designate a JSON document value 
 

Each <path> designates an array or value within the <json> document. The json_append function adds the corresponding 
<value> to the end of the value designated by the <path>. The following table explains what json_append does depending 
 


If <path> specifies... 
 


...This is what json_append does with the corresponding <value> 
 
An array with one or more 
values. 
 

json_append adds the corresponding <value> to the end of that array. 
 
An empty array 
 
json_append adds the corresponding <value> to that array, creating an array with a single value. 
 

A scalar or object value 
 
json_append autowraps the scalar or object value within an array and adds the corresponding <value> to 
the end of that array. 
 
The json_append function ignores path-value pairs for which the <path> does not identify any valid value in the JSON 
document. 
 

Append arrays as single elements 
 

When the new <value> is an array, json_append appends the array as a single element. For example, if a json_array 
<path> leads to the array ["a", "b", "c"] and its <value> is the array ["d", "e", "f"], the result is ["a", "b", "c", 
["d", "e", "f"]]. 
 

Appending arrays as single elements separates json_append from json_extend, a similar function that flattens arrays and 
objects into separate elements as it appends them. When json_extend takes the example in the preceding paragraph, it 
returns ["a", "b", "c", "d", "e", "f"]. 
 

Examples 
 

The following examples show how you can use json_append to append values to arrays within a JSON document. 
 

Add a string to an array 
 

Say you have an object named ponies that contains an array named ponylist:["Minty", "Rarity", 
"Buttercup"]. This is the search you would run to append "Fluttershy" to ponylist.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e51a58f9-a17c-4497-9585-4525eeb8bb17�h+)�}�(h}�(h/XSay you have an object named ponies that contains an array named ponylist:["Minty", "Rarity", 
"Buttercup"]. This is the search you would run to append "Fluttershy" to ponylist. 
 

... | eval ponies = json_object("ponylist", json_array("Minty", "Rarity", "Buttercup")), 
updatePonies = json_append(ponies, "ponylist", "Fluttershy") 
 


80 
 
The output of that eval statement is {"ponylist": ["Minty", "Rarity", "Buttercup", "Fluttershy"]}. 
 

Append a string to a nested object 
 

This example has a <path> with the value Fluttershy.ponySkills. Fluttershy.ponySkills references an array of 
an object that is nested within ponyDetails, the source object. The query uses json_append to add a string to the 
nested object array. 
 

... | eval ponyDetails = json_object("Fluttershy", json_object("ponySkills", json_array("running", 
"jumping"))), ponyDetailsUpdated = json_append(ponyDetails, "Fluttershy.ponySkills", "codebreaking") 
 

The output of this eval statement is ponyDetailsUpdated = 
 
{"Fluttershy":{"ponySkills":["running","jumping","codebreaking"]}} 
 

json_array(<values>) 
 

Creates a JSON array using a list of values. 
 

Usage 
 

A <value> can be any kind of value such as string, number, or Boolean. You can also use the json_object function to 
specify values. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

These examples show different ways to use the json_array function to create JSON arrays in your events. 
 

Create a basic JSON array 
 

The following example creates a simple array ["buttercup", "fluttershy", "rarity"] . 
 

... | eval ponies = json_array("buttercup", "fluttershy", "rarity") 
 

Create an JSON array from a string and a JSON object 
 

The following example uses a string dubois and the json_object function for the array values. 
 

... | eval surname = json_array("dubois", json_object("name", "patel")) 
 

The result is the JSON array  [ "dubois", {"name": "patel}" ].�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f218c8a1-5fea-48e0-a1e3-150cec0baa58�h+)�}�(h}�(h/X�... | eval surname = json_array("dubois", json_object("name", "patel")) 
 

The result is the JSON array  [ "dubois", {"name": "patel}" ]. 
 

json_array_to_mv(<json_array>, <boolean>) 
 

This function maps the elements of a proper JSON array into a multivalue field. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 


81 
 
If the <json array> input to the function is not a valid JSON array, the function outputs nothing. 
 

Use the <Boolean> input to specify that the json_array_to_mv function should preserve bracketing quotes on 
JSON-formatted strings. The <Boolean> input defaults to false(). 
 

Syntax 
 

Description 
 
json_array_to_mv(<json_array>, 
false()) or 
json_array_to_mv(<json_array>) 
 
By default (or when you explicitly set it to false()), the json_array_to_mv function 
removes bracketing quotes from JSON string data types when it converts an array into a 
multivalue field. 
 
json_array_to_mv(<json_array>, 
true()) 
 
When set to true(), the json_array_to_mv function preserves bracketing quotes on JSON 
string data types when it converts an array into a multivalue field. 
 
There is also a function that maps multivalue fields to JSON arrays. See mv_to_json_array. 
 

Example 
 

This example demonstrates usage of the json_array_to_mv function to create multivalue fields out of JSON data. 
 

Create a simple multivalue field 
 

The following example creates a simple array: ["Buttercup", "Fluttershy", "Rarity"]. Then it maps that array 
into a multivalue field named my_little_ponies with the values Buttercup, Fluttershy, and Rarity. The function 
removes the quote characters when it converts the array elements into field values. 
 

... | eval ponies = json_array("Buttercup", "Fluttershy", "Rarity"), my_sweet_ponies = 
json_array_to_mv(ponies) 
 

If you change this search so it has my_sweet_ponies = json_array_to_mv(ponies,true()), you get an array with�
h1h2h3}�h5Kuh�(h3h/�h}�ub�$9f17b824-f5ca-476d-875c-1032f105663b�h+)�}�(h}�(h/X�json_array_to_mv(ponies) 
 

If you change this search so it has my_sweet_ponies = json_array_to_mv(ponies,true()), you get an array with 
the values "Buttercup", "Fluttershy", and "Rarity". Setting the function to true causes the function to preserve 
the quote characters when it converts the array elements into field values. 
 

json_extend(<json>, <path_value_pairs>) 
 

Use json_extend when you want to append multiple values at once to an array. json_extend flattens arrays into their 
component values and appends those values to the ends of indicated arrays within a valid JSON document. 
 

Usage 
 

The json_extend function always has at least three function inputs: <json> (the name of a valid JSON document such as 
a JSON object), and at least one <path> and <value> pair. The <value> must be an array. When given valid inputs, 
 


If <json> does not reference a valid JSON document, such as a JSON object, the function outputs nothing. 
 

The json_extend function evaluates <path_value_pairs> from left to right. When json_extend evaluates a path-value pair, 
it updates the <json> document. json_extend then evaluates the next path-value pair against the updated document. 
 

You can use json_extend with the eval and  where commands, and as part of evaluation expressions with other 
commands. 
 





82 
 
Use <path> to designate a JSON document value 
 

Each <path> designates an array or value within the <json> document. The json_extend function adds the values of the 
corresponding <array> after the last value of the array designated by the <path>. The following table explains what 
json_extend does depending on what the <path> specifies. 
 

If <path> specifies... 
 

...This is what json_extend does with the corresponding array values 
 
An array with one or more 
values. 
 

json_extend adds the corresponding array values to the end of that array. 
 
An empty array 
 
json_extend adds the corresponding array values to that array. 
 

A scalar or object value�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c2dc5c2b-1ef0-4156-98fe-f1f1b2405744�h+)�}�(h}�(h/X�values. 
 

json_extend adds the corresponding array values to the end of that array. 
 
An empty array 
 
json_extend adds the corresponding array values to that array. 
 

A scalar or object value 
 
json_extend autowraps the scalar or object value within an array and adds the corresponding array values to 
the end of that array. 
 
json_extend ignores path-value pairs for which the <path> does not identify any valid value in the JSON document. 
 

How json_extend flattens arrays before it appends them 
 

The json_extend function flattens arrays as it appends them to the specified value. "Flattening" refers to the act of 
breaking the array down into its component values. For example, if a json_extend <path> leads to the array ["a", "b", 
"c"] and its <value> is the array ["d", "e", "f"], the result is ["a", "b", "c", "d", "e", "f"]. 
 

Appending arrays as individual values separates json_extend from json_append, a similar function that appends the 
<value> as a single element. When json_append takes the example in the preceding paragraph, it returns ["a", "b", 
"c", ["d", "e", "f"]]. 
 

Examples 
 

The following examples show how you can use json_extend to append multiple values at once to arrays within a JSON 
document. 
 

Extend an array with a set of string values 
 

You start with an object named fakeBandsInMovies that contains an array named fakeMovieBandList: ["The 
Blues Brothers", "Spinal Tap", "Wyld Stallyns"]. This is the search you would run to extend that list with 
three more names of fake bands from movies. 
 

... | eval fakeBandsInMovies = json_object("fakeMovieBandList", json_array("The Blues Brothers", 
"Spinal Tap", "Wyld Stallyns")), updateBandList = json_extend(fakeBandsInMovies, 
"fakeMovieBandList", json_array("The Soggy Bottom Boys", "The Weird Sisters", "The Barden Bellas")) 
 

The output of this eval statement is {"fakeMovieBandList": ["The Blues Brothers", "Spinal Tap", "Wyld 
 
Stallyns", "The Soggy Bottom Boys", "The Weird Sisters", "The Barden Bellas"]}�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ab98c829-3391-4061-b97a-2d5ee54abde1�h+)�}�(h}�(h/X�The output of this eval statement is {"fakeMovieBandList": ["The Blues Brothers", "Spinal Tap", "Wyld 
 
Stallyns", "The Soggy Bottom Boys", "The Weird Sisters", "The Barden Bellas"]} 
 

Extend an array with an object 
 

This example has an object named dndChars that contains an array named characterClasses. You want to 
update this array with an object from a secondary array. Here is a search you could run to achieve that goal. 
 

... | eval dndChars = json_object("characterClasses", json_array("wizard", "rogue", "barbarian")), 
array2 = json_array(json_object("artifact", "deck of many things")), updatedParty = 
json_extend(dndChars, "characterClasses", array2) 
 




83 
 
The output of this eval statement is {updatedParty = ["wizard", "rogue", "barbarian", {"artifact":"deck 
 

the output would be {updatedParty = ["wizard", "rogue", "barbarian", [{"artifact":"deck of many 
things"}]]}. 
 

json_extract(<json>, <paths>) 
 

This function returns a value from a piece JSON and zero or more paths. The value is returned in either a JSON array, or 
a Splunk software native type value. 
 

Usage 
 

What is converted or extracted depends on whether you specify piece of JSON, or JSON and one or more paths. 
 

Syntax 
 

Description 
 
Converts a JSON field to the Splunk software native type. For example: 
 

json_extract(<json>) 
 
• Converts a JSON string to a string 
 
• Converts a JSON null to a null 
 

json_extract(<json>, <path>) 
 
Extracts the value specified by <path> from <json>, and converts the value to the native type. 
This can be a JSON array if the path leads to an array. 
 
json_extract(<json>, <path>, 
<path>, ...) 
 

Extracts all of the paths from <json> and returns it as a JSON array. 
 
You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

These examples use this JSON object, which is in a field called cities in an event: 
 


[{ 
 

    { 
 

      "Bridges": [�h1h2h3}�h5Kuh�(h3h/�h}�ub�$044d75bf-cdef-44a9-9a43-7340aacbd2b4�h+)�}�(h}�(h/X'of evaluation expressions with other commands. 
 

Examples 
 

These examples use this JSON object, which is in a field called cities in an event: 
 


[{ 
 

    { 
 

      "Bridges": [ 
 

        { "name": "Millennium Bridge", "length": 1066 } 
 

    }, 
 

      "name": "Venice", 
 

        { "name": "Rialto Bridge", "length": 157 }, 
 

        { "name": "Ponte della Paglia" } 
 

    }, 
 

      "name": "San Francisco", 
 

        { "name": "Golden Gate Bridge", "length": 8981 }, 
 

       ] 
 

84 
 
     } 
 

 } 
] 
 



1. Extract the entire JSON object in a field 
 

The following example returns the entire JSON object from the cities field. The cities field contains only one 
object. The key is the entire object. This extraction can return any type of value. 
 

... | eval extract_cities = json_extract(cities, "{}") 
 

Field 
 

Results 
 


extract_cities 
 
[{"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium 
Bridge","length":1066}]},{"name":"Venice","Bridges":[{"name":"Rialto Bridge","length":157},{"name":"Bridge of 
Sighs","length":36},{"name":"Ponte della Paglia"}]},{"name":"San Francisco","Bridges":[{"name":"Golden Gate 
 


2. Extract the first nested JSON object in a field 
 

The following example extracts the information about the city of London from the JSON object. This extraction can 
return any type of value. 
 

... | eval London=json_extract(cities,"{0}") 
 

Field 
 

Results 
 
London 
 
{"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066}]} 
 

3. Extract the third nested JSON object in a field 
 

The following example extracts the information about the city of San Francisco from the JSON object. This 
extraction can return any type of value. 
 

... | eval San_Francisco=json_extract(cities,"{2}") 
 

Field 
 

Results 
 

San_Francisco 
 
{"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay 
Bridge","length":23556}]} 
 

4. Extract a specific key from each nested JSON object in a field�h1h2h3}�h5Kuh�(h3h/�h}�ub�$68d5aabc-2d70-4aa8-a7e5-55f91fae596a�h+)�}�(h}�(h/X�{"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay 
Bridge","length":23556}]} 
 

4. Extract a specific key from each nested JSON object in a field 
 

The following example extracts the names of the cities from the JSON object. This extraction can return any type 
of value. 
 

... | eval my_cities=json_extract(cities,"{}.name") 
 

Field 
 

Results 
 
my_cities 
 
["London","Venice","San Francisco"] 
 


85 
 
Field 
 
Results 
 


5. Extract a specific set of key-value pairs from each nested JSON object in a field 
 

The following example extracts the information about each bridge from every city from the JSON object. This 
extraction can return any type of value. 
 

... | eval Bridges=json_extract(cities,"{}.Bridges{}") 
 

Field 
 

Results 
 

Bridges 
 
[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066},{"name":"Rialto 
Bridge","length":157},{"name":"Bridge of Sighs","length":36},{"name":"Ponte della Paglia"},{"name":"Golden Gate 
Bridge","length":8981},{"name":"Bay Bridge","length":23556}] 
 

6. Extract a specific value from each nested JSON object in a field 
 

The following example extracts the names of the bridges from all of the cities from the JSON object. This 
extraction can return any type of value. 
 

... | eval Bridge_names=json_extract(cities,"{}.Bridges{}.name") 
 

Field 
 

Results 
 

Bridge_names 
 
["Tower Bridge","Millennium Bridge","Rialto Bridge","Bridge of Sighs","Ponte della Paglia","Golden Gate Bridge","Bay 
Bridge"] 
 

7. Extract a specific key-value pair from a specific nested JSON object in a field 
 

The following example extracts the name and length of the first bridge from the third city from the JSON object. 
This extraction can return any type of value. 
 

... | eval GG_Bridge=json_extract(cities,"{2}.Bridges{0}") 
 

Field 
 

Results 
 
GG_Bridge 
 
{"name":"Golden Gate Bridge","length":8981} 
 

8. Extract a specific value from a specific nested JSON object in a field�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cb7ec417-5504-4474-a595-50ce0df98808�h+)�}�(h}�(h/X�Field 
 

Results 
 
GG_Bridge 
 
{"name":"Golden Gate Bridge","length":8981} 
 

8. Extract a specific value from a specific nested JSON object in a field 
 

The following example extracts the length of the first bridge from the third city from the JSON object. This 
extraction can return any type of value. 
 

... | eval GG_Bridge_length=json_extract(cities,"{2}.Bridges{0}.length") 
 

Field 
 

Results 
 
GG_Bridge_length 
 
8981 
 






86 
 
json_extract_exact(<json>, <keys>) 
 

Like the json_extract function, this function returns a Splunk software native type value from a piece of JSON. The main 
difference between these functions is that the json_extract_exact function does not use paths to locate and extract 
values, but instead matches literal strings in the event and extracts those strings as keys. 
 

See json_extract. 
 

Usage 
 

The json_extract_exact function treats strings for key extraction literally. This means that the function does not support 
explicitly nested paths. You can set paths with nested json_array/json_object function calls. 
 

Syntax 
 

Description 
 
Converts a JSON field to the Splunk software native type. For example: 
 

json_extract_exact(<json>) 
 
• Converts a JSON string to a string 
 
• Converts a JSON null to a null 
 

json_extract_exact(<json>, <string>) 
 
Extracts the key specified by <string> from <json>, and converts the key to the Splunk 
software native type. This can be a JSON array if the path leads to an array. 
 
json_extract_exact(<json>, <string>, 
<string>, ...) 
 

Extracts all of the strings from <json> and returns them as a JSON array of keys. 
 
You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

Suppose you have a JSON event that looks like this: {"system.splunk.path":"/opt/splunk/"} 
 

If you want to extract system.splunk.path from that event, you can't use the json_extract function because of the period�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7088016e-0f1e-4e20-9f79-f1c26c4fbb74�h+)�}�(h}�(h/X%If you want to extract system.splunk.path from that event, you can't use the json_extract function because of the period 
characters. Instead, you would use json_extract_exact, as shown in the following search: 
 

... | eval extracted_path=json_extract_exact(splunk_path, "system.splunk.path") 
 

json_keys(<json>) 
 

Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The json_keys function cannot be used on JSON arrays. 
 

Examples 
 





87 
 
Return a list of keys from a JSON object 
 

Consider the following JSON object, which is in the bridges field: 
 

bridges 
 
{"name": "Clifton Suspension Bridge", "length": 1352, "city": "Bristol", "country": "England"} 
 

This example extracts the keys from the JSON object in the bridges field: 
 
... | eval bridge_keys = json_keys(bridges) 
 

Here are the results of the search: 
 

bridge_keys 
 
["name", "length", "city", "country"] 
 

Return a list of keys from multiple JSON objects 
 

Consider the following JSON objects, which are in separate rows in the bridges field: 
 

bridges 
 
{"name": "Clifton Suspension Bridge", "length": 1352, "city": "Bristol", "country": "England"} 
 
{"name":"Rialto Bridge","length":157, "city": "Venice", "region": "Veneto", "country": "Italy"} 
 
{"name": "Helix Bridge", "length": 918, "city": "Singapore", "country": "Singapore"} 
 
{"name": "Tilikum Crossing", "length": 1700, "city": "Portland", "state": "Oregon", "country": "United States"} 
 

This example extracts the keys from the JSON objects in the bridges field: 
 
... | eval bridge_keys = json_keys(bridges) 
 

Here are the results of the search: 
 

bridge_keys 
 
["name", "length", "city", "country"] 
 
["name", "length", "city", "region", "country"] 
 
["name", "length", "city", "country"] 
 
["name", "length", "city", "state", "country"] 
 

json_set(<json>, <path_value_pairs>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c45c2019-8f40-45ea-9cd8-fc1f6699befc�h+)�}�(h}�(h/X["name", "length", "city", "region", "country"] 
 
["name", "length", "city", "country"] 
 
["name", "length", "city", "state", "country"] 
 

json_set(<json>, <path_value_pairs>) 
 

Inserts or overwrites values for a JSON node with the values provided and returns an updated JSON object. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 



88 
 
• If the path contains a list of keys, all of the keys in the chain are created if the keys don't exist. 
 

For example, for object {"a": "b"}, json_set(.., "a.c", "d") produces no results since "a" has a string value and "a.c" 
implies a nested object. 
 

default. A value type match isn't enforced. For example, you can overwrite a number with a string, Boolean, null, 
and so on. 
 

Examples 
 

These examples use this JSON object, which is in a field called games in an event: 
 


{ 
 

    "boardgames": { 
 

        { 
 

        }, 
 

          "name": "Forbidden Island" 
 

        { 
 

        } 
 

    } 
 

} 
 
1. Overwrite a value in an existing JSON array 
 

The following example overwrites the value "Castle Panic" in the path [category.boardgames.cooperative] in 
the JSON object. The value is replaced with "name":"Sherlock Holmes: Consulting Detective". The results are 
placed into a new field called my_games. 
 

The position count starts with 0. The third position is 2, which is why the example specifies {2} in the path. 
 

... | eval my_games = json_set(games,"category.boardgames.cooperative{2}", {"name":"Sherlock Holmes: 
Consulting Detective"}) 
 

Here are the results of the search: 
 

Field 
 

Results 
 

my_games 
 
{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: 
Consulting Detective"]}}} 
 

2. Insert a list of values in an existing JSON object 
 

The following example inserts a list of popular games ["name":"Settlers of Catan", "name":"Terraforming�h1h2h3}�h5Kuh�(h3h/�h}�ub�$90834151-a41d-484d-8f73-20469b8fb3fe�h+)�}�(h}�(h/X7Consulting Detective"]}}} 
 

2. Insert a list of values in an existing JSON object 
 

The following example inserts a list of popular games ["name":"Settlers of Catan", "name":"Terraforming 
Mars", "name":"Ticket to Ride"] into the path [category.boardgames.competitive] in the JSON object. 
 

Because the key competitive doesn't exist in the path, the key is created. The json_array function is used to 
append the value list to the boardgames JSON object. 
 


89 
 
...| eval my_games = json_set(games,"category.boardgames.competitive", json_array("name":"Settlers 
of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride")) 
 

Here are the results of the search: 
 

Field 
 

Results 
 

my_games 
 
{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: 
Consulting Detective"],"competitive": ["name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"]}}} 
 

The JSON object now looks like this: 
 


{ 
 

    "boardgames": { 
 

        { 
 

        }, 
 

          "name": "Forbidden Island" 
 

        { 
 

        } 
 

    }, 
 

      { 
 

      }, 
 

        "name": "Terraforming Mars" 
 

      { 
 

      } 
 

  } 
} 
 


3. Insert a set of key-value pairs in an existing JSON object 
 

The following example inserts a set of key-value pairs that specify if the game is available using a Boolean value. 
These pairs are inserted into the path [category.boardgames.competitive] in the JSON object. The json_array 
function is used to append the key-value pairs list to the boardgames JSON object. 
 

...| eval my_games = json_set(games,"category.boardgames.competitive{}.available", true()) 
 

Here are the results of the search: 
 

Field 
 

Results 
 
my_games 
 
{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: 
Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":true, "name":"Terraforming Mars", 
"available":true, "name":"Ticket to Ride", "available":true]}}} 
 

90 
 
Field 
 
Results�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a0670019-93cf-41e7-b745-b61519ce10db�h+)�}�(h}�(h/XfConsulting Detective"],"competitive": ["name":"Settlers of Catan", "available":true, "name":"Terraforming Mars", 
"available":true, "name":"Ticket to Ride", "available":true]}}} 
 

90 
 
Field 
 
Results 
 


The JSON object now looks like this: 
 


{ 
 

    "boardgames": { 
 

        { 
 

        }, 
 

          "name": "Forbidden Island" 
 

        { 
 

        } 
 

    }, 
 

      { 
 

        "available": true 
 

      { 
 

        "available": true 
 

      { 
 

        "available": true 
 

    ] 
 

} 
 

If the Settlers of Catan game is out of stock, you can overwrite the value for the available key with the value 
false(). 
 

For example: 
 

... | eval my_games = json_set(games,"category.boardgames.competitive{0}.available", false()) 
 

Here are the results of the search: 
 

Field 
 

Results 
 

my_games 
 
{"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: 
Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":false, "name":"Terraforming Mars", 
"available":true, "name":"Ticket to Ride", "available":true]}}} 
 

The JSON object now looks like this: 
 


{ 
 


91 
 
    "boardgames": { 
 

        { 
 

        }, 
 

          "name": "Forbidden Island" 
 

        { 
 

        } 
 

    }, 
 

      { 
 

        "available": false 
 

      { 
 

        "available": true 
 

      { 
 

        "available": true 
 

    ] 
 

} 
 
json_set_exact(<json>, <key_value_pairs>) 
 

Generates or overwrites a JSON object using the key-value pairs that you specify 
 

Similar to the json_set function. See json_set 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

• The json_set_exact function interprets the keys as literal strings, including special characters. This function does 
	not interpret strings separated by period characters as keys for nested objects. 
 

• The json_set_exact function does not support or expect paths. You can set paths with nested json_array or�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b51c408b-f325-4fd5-9ea3-6336cae1e8a5�h+)�}�(h}�(h/Xnot interpret strings separated by period characters as keys for nested objects. 
 

• The json_set_exact function does not support or expect paths. You can set paths with nested json_array or 
	json_object function calls. 
 

Example 
 

Suppose you want to have a JSON object that looks like this: 
 


{"system.splunk.path":"/opt/splunk"} 
 
To generate this object, you can use an empty dataset literal in the from command and the json_set_exact function as 
shown in the following search: 
 

from [{}] | eval my_object=json_object(), splunk_path=json_set_exact(my_object, "system.splunk.path", 
"/opt/splunk") 
 

92 
 
You use the json_set_exact function instead of the json_set function because the json_set function interprets the period 
characters in {"system.splunk.path"} as nested objects. If you use json_set in the preceding search you get this JSON 
object: 
 


{"system":{"splunk":{"path":"/opt/splunk"}}} 
 
Instead of this object: 
 


{"system.splunk.path":"/opt/splunk"} 
 
json_valid(<json>) 
 

Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

Validate a JSON object 
 

The following example validates a JSON object { "names": ["maria", "arun"] } in the firstnames field. 
 
... | eval name = json_valid(firstnames) 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 


Related functions 
	mv_to_json_array 
	tojson 
 


Mathematical functions 
 
The following list contains the functions that you can use to perform mathematical calculations. 
 

• For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 
	eval functions. 
 

command usage. 
 

abs(<num>) 
 

This function returns the absolute value of a number. 
 



93 
 
Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5b2a9bee-aa4b-457e-adf8-0cde7dad0adf�h+)�}�(h}�(h/Xeval functions. 
 

command usage. 
 

abs(<num>) 
 

This function returns the absolute value of a number. 
 



93 
 
Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example creates a field called absnum, whose values are the absolute values of the numeric field number. 
 

... | eval absnum=abs(number) 
 

The following example uses the abs function in a WHERE clause. In this example, the values in the mydata field are 
greater than the absolute value of the numeric literal -10.95. 
 

... WHERE mydata>abs(-10.95) 
 

ceiling(<num>) or ceil(<num>) 
 

This function rounds a number up to the next highest integer. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

You can use the abbreviation ceil(<num>) instead of the full name of the function. 
 

Basic example 
 

The following example returns n=2. 
 

... | eval n=ceil(1.9) 
 



exact(<expression>) 
 

This function returns the result of a numeric eval calculation with a larger amount of precision in the formatted output. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

Calculates the circumference of a set of circles by multiplying pi by the values in the diameter field. 
 


94 
 
... | eval n=exact(3.14 * diameter) 
 

exp(<num>) 
 

This function returns the exponential function e  of a number. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7de67501-3710-4182-8590-aeb00b43594b�h+)�}�(h}�(h/X�Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns y=e . 
 

... | eval y=exp(3) 
 



floor(<num>) 
 

This function rounds a number down to the nearest whole integer. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns 1. 
 

... | eval n=floor(1.9) 
 



ln(<num>) 
 

This function returns the natural logarithm of a number. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 



95 
 
Basic example 
 

The following example returns the natural logarithm of the values in the bytes field. 
 

... | eval lnBytes=ln(bytes) 
 



log(<num>,<base>) 
 

This function returns the logarithm of a number using a base. The base is optional, and if omitted the log function uses 
base 10. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns the logarithm of the values of the number field, using base 2. 
 

... | eval num=log(number,2) 
 

The following example returns the logarithm of the numeric literal 100000, using base 10. 
 

... | eval num=log(100000,10) 
 

pi() 
 

This function takes no arguments and returns the constant 'pi to 11 digits of precision. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7c48fdfc-309d-4124-a876-c18e49bc6bbc�h+)�}�(h}�(h/X2... | eval num=log(100000,10) 
 

pi() 
 

This function takes no arguments and returns the constant 'pi to 11 digits of precision. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example calculates the area of a circle, which is pi() multiplied by the radius to the power of 2. 
 

... | eval area_circle=pi()*pow(radius,2) 
 



pow(<num>, <exp>) 
 

This function returns a number to the power of the exponent. 
 



96 
 
Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example calculates the area of a circle, which is pi() multiplied by the radius to the power of 2. 
 

... | eval area_circle=pi()*pow(radius,2) 
 



round(<num>, <precision>) 
 

This function returns a number rounded to the decimal places specified by the precision. The precision is optional, and if 
omitted the round function rounds to an integer. 
 

You cannot specify a negative number for the precision. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

Specifying a value without precision 
 

The following example returns n=4. Because a <precision> is not specified, the number is rounded to the integer. 
 

... | eval n=round(3.5) 
 

This search returns n=3. 
 

Specifying a value and a precision 
 

The following example returns n=2.56. 
 

... | eval n=round(2.555, 2) 
 



sigfig(<num>) 
 

This function rounds a number to the appropriate number of significant figures. 
 




97 
 
Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$03a5cd68-6490-47cd-b991-76729a0f5cc8�h+)�}�(h}�(h/X�sigfig(<num>) 
 

This function rounds a number to the appropriate number of significant figures. 
 




97 
 
Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

How sigfig is computed 
 

The computation for sigfig is based on the type of calculation that generates the number. 
 

• For multiplication and division, the result should have the minimum number of significant figures of all of the 
	operands. 
 

number of all of the operands. 
 

For example, the numbers 123.0 and 4.567 contain different precision with the decimal places. The first number is less 
precise because it has 1 decimal place. The second number is more precise because it has 3 decimal places. 
 

If the calculation is 123.0 + 4.567 = 127.567, then the sigfig function returns the fewest number of decimal places. In this 
example only one decimal place is returned. Because the number to the right of the last significant figure is greater than 5, 
the result returned is 127.6 
 

Examples 
 

Example 1: The following example shows how the sigfig function works. The calculation 1.00*1111 returns the value 
n=1111, but the following search using the sigfig function returns n=1110. 
 

... | eval n=sigfig(1.00*1111) 
 

In this example, 1.00 has 3 significant figures and 1111 has 4 significant figures. In this example, the minimum number of 
significant figures for all operands is 3. Using the sigfig function, the final result is rounded to 3 digits, returning n=1110 
and not 1111. 
 


Example 2: There are situations where the results of a calculation can return a different accuracy to the very far right of 
the decimal point. For example, the following search calculates the average of 100 values: 
 

| makeresults count=100 | eval test=3.99 | stats avg(test) 
 

The result of this calculation is: 
 

avg(test) 
 
3.9900000000000055�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6e64e21c-1d28-42fe-89cb-aa76f197f216�h+)�}�(h}�(h/X| makeresults count=100 | eval test=3.99 | stats avg(test) 
 

The result of this calculation is: 
 

avg(test) 
 
3.9900000000000055 
 
When the count is changed to 10000, the results are different: 
 

| makeresults count=10000 | eval test=3.99 | stats avg(test) 
 

The result of this calculation is: 
 

avg(test) 
 

98 
 
3.990000000000215 
 
This occurs because numbers are treated as double-precision floating-point numbers. 
 

To mitigate this issue, you can use the sigfig function to specify the number of significant figures you want returned. 
 

However, first you need to make a change to the stats command portion of the search. You need to change the name of 
the field avg(test) to remove the parenthesis. For example stats avg(test) AS test. The sigfig function expects either 
a number or a field name for X. The sigfig function cannot accept a field name that looks like another function, in this 
case avg. 
 

To specify the number of decimal places you want returned, you multiply the field name by 1 and use zeros to specify the 
number of decimal places. If you want 4 decimal places returned, you would multiply the field name by 1.0000. To return 2 
decimal places, multiply by 1.00, as shown in the following example: 
 

| makeresults count=10000 | eval test=3.99 | stats avg(test) AS test | eval new_test=sigfig(test*1.00) 
 

The result of this calculation is: 
 

test 
 
3.99 
 


sqrt(<num>) 
 

This function returns the square root of a number. 
 

Usage 
 

The <num> argument can be the name of a numeric field or a numeric literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns 3: 
 

... | eval n=sqrt(9) 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 








99 
 
Multivalue eval functions 
 
The following list contains the functions that you can use on multivalue fields or to return multivalue fields.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1d2b69b1-87ca-48eb-87c6-60719f9ad9eb�h+)�}�(h}�(h/X#Function information 
 

Overview of SPL2 eval functions 
 








99 
 
Multivalue eval functions 
 
The following list contains the functions that you can use on multivalue fields or to return multivalue fields. 
 

You can also use the statistical eval functions, such as max, on multivalue fields. See Statistical eval functions. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

mvappend(<values>) 
 

This function returns a single multivalue result from a list of values. 
 

Usage 
 

The values can be strings, multivalue fields, or single value fields. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

Specifying literals and field names 
 

This example shows how to append the literal value localhost to the values in the srcip field. The results are placed in a 
new multivalue field called ipaddresses: 
 

... | eval ipaddresses=mvappend("localhost", srcip) 
 

Nested mvappend functions 
 

This example shows how to use nested mvappend functions. 
 

• The inner mvappend function contains two values: localhost is a literal string value and srcip is a field name. 
• The outer mvappend function contains three values: the inner mvappend function, destip is a field name, and 
 


... | eval ipaddresses=mvappend(mvappend("localhost", srcip), destip, "192.168.1.1") 
 

The results are placed in a new field called ipaddresses which contains the array  ["localhost", <values_in_srcip>, 
<values_in_destip>, "192.168.1.1"]. 
 

mvcount(<mv>) 
 

This function takes a multivalue field and returns a count of the values in that field. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 



100 
 
If the field contains a single value, this function returns 1. If the field has no values, this function returns NULL.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d080335d-d263-459e-b632-97efc1fe684b�h+)�}�(h}�(h/X
of evaluation expressions with other commands. 
 



100 
 
If the field contains a single value, this function returns 1. If the field has no values, this function returns NULL. 
 

Basic example 
 

... | eval n=mvcount(myfield) 
 

Extended example 
 

In the following example, the mvcount() function returns the number of email addresses in the To, From, and Cc fields and 
saves the addresses in the specified "_count" fields. 
 

eventtype="sendmail" | eval To_count=mvcount(split(To,"@"))-1 | eval From_count=mvcount(From) | eval 
Cc_count= mvcount(split(Cc,"@"))-1 
 

This search takes the values in the To field and uses the split function to separate the email address on the @ symbol. 
The split function is also used on the Cc field for the same purpose. 
 

If only a single email address exists in the From field, as you would expect, mvcount(From) returns 1. If there is no Cc 
address, the Cc field might not exist for the event. In that situation mvcount(cc) returns NULL. 
 

mvdedup(<mv>) 
 

This function takes a multivalue field and returns a multivalue field with the duplicate values removed. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

... | eval s=mvdedup(myfield) 
 



mvfilter(<predicate>) 
 

This function filters a multivalue field based on a predicate expression. The expression can reference only one field. 
 

Usage 
 

This function will return NULL values of the field x as well. If you do not want the NULL values, use one of the following 
expressions: 
 


• mvfilter(isnotnull(x)) 
 
You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 





101 
 
Example 
 

The following example returns all of the values in the email field that end in .net or .org. 
 

... | eval n=mvfilter(match(email, "\.net$") OR match(email, "\.org$")) 
 

mvfind(<mv>, <regex>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$62cf34c0-4e89-4087-b540-20dc103cbfa5�h+)�}�(h}�(h/XMExample 
 

The following example returns all of the values in the email field that end in .net or .org. 
 

... | eval n=mvfilter(match(email, "\.net$") OR match(email, "\.org$")) 
 

mvfind(<mv>, <regex>) 
 

This function returns the index for the first value in a multivalue field that matches a regular expression. The index begins 
with zero. If no values match, NULL is returned. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

... | eval n=mvfind(myfield, "err\d+") 
 

mvindex(<mv>, <start>, <end>) 
 

This function returns a subset of the multivalue field using the start and end index values. 
 

Usage 
 

The <mv> argument must be a multivalue field. The <start> and <end> indexes must be numbers. 
 

The <mv> and <start> arguments are required. The <end> argument is optional. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Specifying the start and end indexes 
 

• Indexes start at zero. If you have 5 values in the multivalue field, the first value has an index of 0. The second 
	value has an index of 1, and so on. 
 

• When the <end> argument is specified, the range of values from <start> to <end> are included in the results. 
 

• If the indexes are out of range or invalid, the result is NULL. 
 

Examples 
 

Consider the following values in a multivalue field called names: 
 

Name 
 

alex 
 

celestino 
 

claudia 
 

david 
 

ikraam 
 

nyah 
 

rutherford 
 

wei 
 
index number 
 
0 
 
1 
 
2 
 
3 
 
4 
 
5 
 
6 
 
7 
 
Because indexes start at zero, the following example returns the value claudia: 
 

... | eval my_names=mvindex(names,2) 
 

102 
 
To return a range of values, specify both a start and end value. For example, the following search returns the first 4 
values in the field. The start value is 0 and the end value is 3. 
 

... | eval my_names=mvindex(names,0,3) 
 

The results look like this:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e11d4b9b-8828-47d8-bed4-31ddb28a6a27�h+)�}�(h}�(h/X4values in the field. The start value is 0 and the end value is 3. 
 

... | eval my_names=mvindex(names,0,3) 
 

The results look like this: 
 

my_names 
 
alex,celestino,claudia,david 
 
Extended examples 
 

Consider the following values in a multivalue field: 
 

ponies 
 
buttercup, dash, flutter, honey, ivory, minty, pinky, rarity 
 
To return a value from the end of the list of values, the index numbers start with -1. The negative symbol indicates that the 
indexing starts from the last value. For example: 
 

Pony name 
 

buttercup 
 

dash 
 

flutter 
 

honey 
 

ivory 
 

minty 
 

pinky 
 

rarity 
 
index number 
 
-8 
 
-7 
 
-6 
 
-5 
 
-4 
 
-3 
 
-2 
 
-1 
 

To return the last value in the list, you specify -1, which indicates to start at the end of the list and return only one value. 
For example: 
 

... | eval my_ponies=mvindex(ponies,-1) 
 

The results look like this: 
 

my_ponies 
 
rarity 
 
To return the 3rd value from the end, you would specify the index number -3. For example: 
 

... | eval my_ponies=mvindex(ponies,-3) 
 

The results look like this: 
 

my_ponies 
 
minty 
 
To return a range of values, specify both a start and end value. For example, the following search returns the last 3 
values in the field. The start value is -3 and the end value is -1. 
 

... | eval my_ponies=mvindex(ponies, -3, -1) 
 

The results look like this: 
 

my_ponies 
 


103 
 
minty,pinky,rarity 
 
mvjoin(<mv>,<delim>) 
 

This function takes two arguments, a multivalue field and a string delimiter. The function concatenates the individual 
values within the multivalue field using the value of the delimiter as a separator. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Examples 
 

You have a multivalue field called "base" that contains the values "1" "2" "3" "4" "5". The values are separated by a space. 
You want to create a single value field instead, with OR as the delimiter. For example "1 OR 2 OR 3 OR 4 OR 5".�h1h2h3}�h5Kuh�(h3h/�h}�ub�$785af5be-77d3-49a9-a9ee-9bef7beda0b5�h+)�}�(h}�(h/X�You want to create a single value field instead, with OR as the delimiter. For example "1 OR 2 OR 3 OR 4 OR 5". 
 

The following search creates the base field with the values. The search then creates the joined field by using the result of 
the mvjoin function. 
 

... | eval base=mvrange(1,6), joined=mvjoin('base'," OR ") 
 

The following example joins together the individual values in the "myfield" field using a semicolon as the delimiter: 
 

... | eval n=mvjoin(myfield, ";") 
 



mvmap(<mv>,<expression>) 
 

Description 
 

This function iterates over the values of a multivalue field and performs an operation on each value. The function returns a 
multivalue field with the list of results. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example multiplies each value in the results field by 10. 
 

... | eval n=mvmap(results, results*10) 
 


The following example multiplies each value in the results field by threshold, where threshold is a single-valued field. 
 

... | eval n=mvmap(results, results*threshold) 
 




104 
 
The following example multiplies the 2nd and 3rd values in the results field by threshold, where threshold is a 
single-valued field. This example uses the mvindex function to identify specific values in the results field. 
 

... | eval n=mvmap(mvindex(results, 1,2), results*threshold) 
 

mvrange(<start>, <end>, <step>) 
 

This function creates a multivalue field based on a range of specified numbers. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The step increment is optional. If the <step> increment is a timespan such as 7d, the starting and ending numbers are 
treated as UNIX time. 
 

The <end> number is not included from the multivalue field that is created. 
 

Examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$93df09e2-554a-4b0d-a51b-e400dc289d35�h+)�}�(h}�(h/X�treated as UNIX time. 
 

The <end> number is not included from the multivalue field that is created. 
 

Examples 
 

The following example returns a multivalue field with the values 1, 3, 5, 7, 9. 
 

... | eval mv=mvrange(1,11,2) 
 


The following example takes the UNIX timestamp for 1/1/2018 as the start date and the UNIX timestamp for 4/19/2018 as 
an end date and uses the increment of 7 days. 
 

| from [{}] | eval mv=mvrange(1514834731,1524134919,"7d") 
 

This example returns a multivalue field with the UNIX timestamps. The results look like this: 
 

Field 
 

Value 
 

mv 
 
1546370743, 1546975543, 1547580343, 1548185143, 1548789943, 1549394743, 1549999543, 1550604343, 
1551209143, 1551813943, 1552418743, 1553023543, 1553628343, 1554233143, 1554837943, 1555442743 
 
mvsort(<mv>) 
 

This function takes a multivalue field and returns a multivalue field with the values sorted lexicographically. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

105 
 
• Uppercase letters are sorted before lowercase letters. 
 

after letters. 
 

See Lexicographical order. 
 

Example 
 

... | eval s=mvsort(myfield) 
 



mvzip(<mv_left>, <mv_right>, <delim>) 
 

This function combines the values in two multivalue fields. The delimiter is used to specify a delimiting character to join 
the two values. 
 

Usage 
 

This is similar to the Python zip command. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9bce9643-7b9e-4173-88b5-be77fa3ef6e3�h+)�}�(h}�(h/X�You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The values are stitched together combining the first value of <mv_left> with the first value of field <mv_right>, then the 
second with the second, and so on. 
 

The delimiter is optional, but when specified must be enclosed in quotation marks. The default delimiter is a comma ( , ). 
 

Basic example 
 

... | eval nserver=mvzip(hosts, ports) 
 

Extended example 
 

You can nest several mvzip functions together to create a single multivalue field. In this example, the field three_fields is 
created from three separate fields. The pipe ( | ) character is used as the separator between the field values. 
 

...| eval three_fields=mvzip(mvzip(field1,field2,"|"),field3,"|") 
 

(Thanks to Splunk user cmerriman for this example.) 
 

mv_to_json_array(<field>, <infer_types>) 
 

This function maps the elements of a multivalue field to a JSON array. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 



106 
 
Because the elements of JSON arrays can have many data types (such as string, numeric, Boolean, and null), the 
mv_to_json_array function lets you specify how it should map the contents of multivalue fields into JSON arrays. You can 
have the field values simply written to arrays as string data types, or you can have the function infer different JSON data 
types. 
 

Use the <infer_types> input to specify that the mv_to_json_array function should attempt to infer JSON data types when 
it converts field values into array elements. The <infer_types> input defaults to false. 
 

Syntax 
 

Description 
 

mv_to_json_array(<field>, 
false()) or 
mv_to_json_array(<field>) 
 
By default, or when you explicitly set it to false(), the mv_to_json_array function maps all values in�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d1ebfae9-5868-4bd9-9c5d-cab800998267�h+)�}�(h}�(h/X�Syntax 
 

Description 
 

mv_to_json_array(<field>, 
false()) or 
mv_to_json_array(<field>) 
 
By default, or when you explicitly set it to false(), the mv_to_json_array function maps all values in 
the multivalued field to the JSON array as string data types, whether they are numeric, strings, Boolean 
values, or any other JSON data type. The mv_to_json_array function effectively splits the multivalue 
field on the comma and writes each quote-enclosed value to the array as an element with the string data 
type. 
 

mv_to_json_array(<field>, 
true()) 
 
When you set the mv_to_json_array function to true(), the function removes one set of bracketing 
quote characters from each value it transfers into the JSON array. If the function does not recognize the 
resulting array element as a proper JSON data type (such as string, numeric, Boolean, or null), the 
 

Example 
 

This example shows you how the mv_to_json_array function can validate JSON as it generates JSON arrays. 
 

This search creates a multivalue field named ponies. 
 

... | eval ponies = mvappend("\"Buttercup\"", "\"Fluttershy\"", "\"Rarity\"", "true", "null"), 
 

The array that is created from these values depends on the <infer_types> input. 
 

Without inferring data types 
 

When <infer_types> is set to false or omitted, the mv_to_json_array function converts the field values into array 
elements without changing the values. 
 

... | eval my_sweet_ponies = mv_to_json_array(ponies, false()) 
 

The resulting array looks like this: 
 

["\"Buttercup\"","\"Fluttershy\"","\"Rarity\"","true","null"] 
 

With inferring data types 
 

When you run this search with infer_values set to true(), the mv_to_json_array function removes the extra 
quote and backslash escape characters from the field values when the values are converted into array elements. 
 

... | eval my_sweet_ponies = mv_to_json_array(ponies, true()) 
 

The resulting array looks like this: 
 

["Buttercup","Fluttershy","Rarity",true,null] 
 





107 
 
split(<str>, <delim>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$16a4319f-d0f9-421d-90b9-37c1050968b2�h+)�}�(h}�(h/X@... | eval my_sweet_ponies = mv_to_json_array(ponies, true()) 
 

The resulting array looks like this: 
 

["Buttercup","Fluttershy","Rarity",true,null] 
 





107 
 
split(<str>, <delim>) 
 

This function splits the string values on the delimiter and returns the string values as a multivalue field. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Example 
 

The following search creates an event with a test field that contains a list of string values separated by semicolon 
characters ( ; ). 
 

from repeat({},1) | eval _time=now() | eval 
test="buttercup;rarity;tenderhoof;dash;mcintosh;fleetfoot;mistmane" 
 

The results look like this: 
 

_time 
 

test 
 
21:39:56PM 
 

20 Sep 2022 
 
buttercup;rarity;tenderhoof;dash;mcintosh;fleetfoot;mistmane 
 
Use the split function to separate the names in the event into a multivalue field, using the semicolon as the delimiter: 
 

from repeat({},1) | eval _time=now() | eval 
test="buttercup;rarity;tenderhoof;dash;mcintosh;fleetfoot;mistmane" | eval ponies=split(test,";") 
 

The ponies field is a multivalue field and the results look like this: 
 

_time 
 

ponies 
 

test 
 
buttercup 
 

21:39:56PM 

20 Sep 2022 
 

rarity 
tenderhoof 
dash 
mcintosh 
 


buttercup;rarity;tenderhoof;dash;mcintosh;fleetfoot;mistmane 
 

mistmane 
 
See also 
 

Function information 
 

Overview of SPL2 eval functions 
 








108 
 
Statistical eval functions 
 
The following list contains the evaluation functions that you can use to calculate statistics. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

In addition to these functions, there is a comprehensive set of Stats and charting functions Quick Reference that you can 
use with the stats, timechart, and related commands. 
 

max(<values>) 
 

This function takes one or more numeric or string values and returns the maximum value. Strings are greater than 
numbers. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dce92367-828c-44b7-bc42-166b0e32a7be�h+)�}�(h}�(h/Xuse with the stats, timechart, and related commands. 
 

max(<values>) 
 

This function takes one or more numeric or string values and returns the maximum value. Strings are greater than 
numbers. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns either "foo" or the value in the name field. Splunk searches use lexicographical order, 
where numbers are sorted before letters. If the value in the name field is "baz", then "foo" is returned. If the value in the 
name field is "zaz", then "zaz" is returned. 
 

... | eval n=max(1, 3, 6, 7, "foo", name) 
 


This example returns the maximum value in a multivalue field. 
 

The following search creates a field called n with a single value, which is a series of numbers. The makemv command is 
used to make the single value into multiple values, each of which appears on it's own row in the results. Another new field 
called maxn is created which takes the values in n and returns the maximum value, 6. 
 

| makeresults | eval n = "1 3 5 6 4 2" | makemv n | eval maxn = max(n) 
 

The results look like this: 
 

_time 
 

maxn 
 

n 
 
1 
 


2021-01-29 10:42:37 
 


6 
 

3 
5 
6 
4 
2 
 






109 
 
min(<values>) 
 

This function one or more numeric or string values and returns the minimum value. Strings are greater than numbers. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns either 3 or the value in the size field. Splunk searches use lexicographical order, where 
numbers are sorted before letters. If the value in the size field is 9, then 3 is returned. If the value in the size field is 1, 
then 1 is returned. 
 

... | eval n=min(3, 6, 7, "maria", size) 
 


The following example returns the minimum value in a multivalue field.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c532c447-9fac-4c47-8568-a54fae3a92a9�h+)�}�(h}�(h/X�then 1 is returned. 
 

... | eval n=min(3, 6, 7, "maria", size) 
 


The following example returns the minimum value in a multivalue field. 
 

This search creates a field called n with a single value, which is a series of numbers. The makemv command is used to 
make the single value into multiple values, each of which appears on it's own row in the results. Another new field called 
minn is created which takes the values in n and returns the minimum value, 2. 
 

| makeresults | eval n = "3 5 6 4 7 2" | makemv n | eval minn = min(n) 
 

The results look like this: 
 

_time 
 

minn 
 

n 
 
3 
 


2021-01-29 10:42:37 
 


2 
 

5 
6 
4 
7 
2 
 
random() 
 

This function returns a pseudo-random integer ranging from 0 to 2  -1. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

The following example returns a random integer, such as 0...2147483647. 
 

... | eval n=random() 
 


110 
 
The following example returns a random number within a specified range. In this example the random number is between 
1 and 100,000. 
 

| eval n=(random() % 100000) + 1 
 


This example takes a random number and uses the modulo mathematical operator ( % ) to divide the random number by 
100000. This ensures that the random number returned is not greater than 100000. The number remaining after the 
division is increased by 1 to ensure that the number is at least greater than or equal to 1. 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 



Text functions 
 
The following list contains the functions that you can use with string values. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 

len(<str>) 
 

This function returns the character length of a string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$593c1b65-8376-47e0-a00e-eac3e536bb5c�h+)�}�(h}�(h/X�functions. 
 

len(<str>) 
 

This function returns the character length of a string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns the character length of the values in the categoryId field for each result. 
 

... | eval n=len(myfield) 
 

lower(<str>) 
 

This function returns a string in lowercase. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 


111 
 
You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns the values in the username field in lowercase. 
 

... | eval username=lower(username) 
 

ltrim(<str>,<trim_chars>) 
 

This function removes characters from the left side of a string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The <trim_chars> argument is optional. If not specified, spaces and tabs are removed from the left side of the string. 
 

Basic example 
 

The following example trims the leading spaces and all of the occurrences of the letter Z from the left side of the string. 
The value returned is abcZZ . 
 

... | eval x=ltrim(" ZZZZabcZZ ", " Z") 
 

replace(<str>,<regex>,<replacement>) 
 

This function substitutes the replacement string for every occurrence of the regular expression in the string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

The <replacement> argument can also reference groups that are matched in the <regex using perl-compatible regular 
expressions (PCRE) syntax.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$bbfe0985-eda7-4775-9d32-f5e47606e995�h+)�}�(h}�(h/X�The <replacement> argument can also reference groups that are matched in the <regex using perl-compatible regular 
expressions (PCRE) syntax. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

To replace a backslash ( \ ) character, you must escape the backslash twice. This is because the replace function occurs 
inside an eval expression. The eval expression performs one level of escaping before passing the regular expression to 
PCRE. Then PCRE performs its own escaping. 
 

The Edge Processor solution supports Regular Expression 2 (RE2) syntax instead of PCRE syntax. In particular RE2 
and PCRE accept different syntax for named capture groups. See Regular expression syntax for Edge Processor 
pipelines in Use Edge Processors. 
 



112 
 
Basic example 
 

The following example returns the values in the date field, with the month and day numbers switched. If the input is 
1/14/2023 the return value would be 14/1/2023. 
 

... | eval n=replace(date, "^(\d{1,2})/(\d{1,2})/", "\2/\1/") 
 

rtrim(<str>,<trim_chars>) 
 

This function removes the trim characters from the right side of the string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The <trim_chars> argument is optional. If not specified, spaces and tabs are removed from the right side of the string. 
 

Basic example 
 

The following example trims the leading spaces and all of the occurrences of the letter Z from the right side of the string. 
The value returned is  ZZZZabc. 
 

... | eval n=rtrim(" ZZZZabcZZ ", " Z") 
 

spath(<value>,<path>) 
 

Use this function to extract information from the structured data formats XML and JSON. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1a1d6ea1-1c63-485d-ace7-6293b1c53d92�h+)�}�(h}�(h/X�The value returned is  ZZZZabc. 
 

... | eval n=rtrim(" ZZZZabcZZ ", " Z") 
 

spath(<value>,<path>) 
 

Use this function to extract information from the structured data formats XML and JSON. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

The <value> is an input source field. 
 

The <path> is an spath expression for the location path to the value that you want to extract from. 
 

• If <path> is a literal string, you need to enclose the string in double quotation marks. 
 

Using a field name for <path> might result in a multivalue field. 
 



Basic example 
 

The following example returns the values of locDesc elements from the _raw field.. 
 


113 
 
... | eval locDesc=spath(_raw, "vendorProductSet.product.desc.locDesc") 
 


The following example returns the hashtags from a twitter event. 
 

index=twitter | eval output=spath(_raw, "entities.hashtags") 
 

substr(<str>,<start>,<length>) 
 

This function returns a substring of a string, beginning at the start index. The length of the substring specifies the number 
of character to return. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

The indexes follow SQLite semantics; they start at 1. Negative indexes can be used to indicate a start from the end of the 
string. 
 

The <length> is optional, and if not specified returns the rest of the string. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example concatenates the first 3 letters in the word splendid with the last 3 letters in the word chunk: 
 

... | eval n=substr("splendid", 1, 3) + substr("chunk", -3) 
 

The result is the word splunk. 
 

trim(<str>,<trim_chars>) 
 

This function removes the trim characters from both sides of the string. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3e8d6439-b743-4f3d-9d44-010aa8182685�h+)�}�(h}�(h/X�... | eval n=substr("splendid", 1, 3) + substr("chunk", -3) 
 

The result is the word splunk. 
 

trim(<str>,<trim_chars>) 
 

This function removes the trim characters from both sides of the string. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

The <trim_chars> argument is optional. If not specified, spaces and tabs are removed from both sides of the string. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example trims the leading spaces and all of the occurrences of the letter Z from the left and right sides of 
the string. The value returned is abc. 
 

... | eval n=trim(" ZZZZabcZZ ", " Z") 
 


114 
 
upper(<str>) 
 

This function returns a string in uppercase. 
 

Usage 
 

The <str> argument can be the name of a string field or a string literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns the values in the username field in uppercase. 
 

... | eval n=upper(username) 
 

urldecode(<url>) 
 

This function takes a URL string and returns the unescaped or decoded URL string. 
 

Usage 
 

The <url> argument can be the name of a string field or a string literal. 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

The following example returns "http://www.splunk.com/download?r=header". 
 

... | eval n=urldecode("http%3A%2F%2Fwww.splunk.com%2Fdownload%3Fr%3Dheader") 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 



Trig and Hyperbolic functions 
 
The following list contains the functions that you can use to calculate trigonometric and hyperbolic values.�@
h1h2h3}�h5Kuh�(h3h/�h}�ub�$cec47f62-3120-49f8-a0c9-9ad3fad7efc0�h+)�}�(h}�(h/X6Function information 
 

Overview of SPL2 eval functions 
 



Trig and Hyperbolic functions 
 
The following list contains the functions that you can use to calculate trigonometric and hyperbolic values. 
 

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval 
functions. 
 





115 
 
acos(x) 
 

This function computes the arc cosine of x, in the interval [0,pi] radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

This example returns 1.5707963267948966. 
 

... | eval n=acos(0) 
 


The following example calculates 180 divided by pi and multiplies the result by the arc cosine of 0. This example returns 
90.0000000003. 
 

... | eval degrees=acos(0)*180/pi() 
 



acosh(x) 
 

This function computes the arc hyperbolic cosine of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 1.3169578969248166. 
 

... | eval n=acosh(2) 
 



asin(x) 
 

This function computes the arc sine of x, in the interval [-pi/2,+pi/2] radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 





116 
 
Basic example 
 

This example returns 1.5707963267948966. 
 

... | eval n=asin(1) 
 

The following example calculates 180 divided by pi and multiplies that by the arc sine of 1. 
 

... | eval degrees=asin(1)*180/pi() 
 



asinh(x) 
 

This function computes the arc hyperbolic sine of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 0.881373587019543. 
 

... | eval n=asinh(1) 
 

atan(x)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$db1246fd-3fe5-4a61-916e-b1213296eef2�h+)�}�(h}�(h/XCof evaluation expressions with other commands. 
 

Basic example 
 

This example returns 0.881373587019543. 
 

... | eval n=asinh(1) 
 

atan(x) 
 

This function computes the arc tangent of x, in the interval [-pi/2,+pi/2] radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 0.46. 
 

... | eval n=atan(0.50) 
 



atan2(y, x) 
 

This function computes the arc tangent of y, x in the interval [-pi,+pi] radians. 
 

• y is a value that represents the proportion of the y-coordinate. 
 


To compute the value, the function takes into account the sign of both arguments to determine the quadrant. 
 

117 
 
Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 0.59. 
 

... | eval n=atan2(0.50, 0.75) 
 



atanh(x) 
 

This function computes the arc hyperbolic tangent of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 0.549. 
 

... | eval n=atanh(0.500) 
 



cos(x) 
 

This function computes the cosine of an angle of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

This example returns 0.5403023058681398. 
 

... | eval n=cos(-1) 
 


The following example calculates the cosine of pi and returns -1.00000000000. 
 

... | eval n=cos(pi()) 
 





118 
 
cosh(x) 
 

This function computes the hyperbolic cosine of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e6116100-433d-4a19-bdd9-ec8bafd40a70�h+)�}�(h}�(h/X<Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 1.5430806348152437. 
 

... | eval n=cosh(1) 
 

hypot(x,y) 
 

This function computes the hypotenuse of a right-angled triangle whose legs are x and y. 
 

The function returns the square root of the sum of the squares of X and Y, as described in the Pythagorean theorem. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

Creates a field called n and returns n=5, which is the hypotenuse of a triangle whose legs are 3 and 4. 
 

... | eval n=hypot(3,4) 
 

sin(x) 
 

This function computes the sine of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

This example returns 0.8414709848078965. 
 

... | eval n=sin(1) 
 


The following search calculates the sine of pi divided by 180 and then multiplied by 90. 
 

... | eval n=sin(90 * pi()/180) 
 


119 
 
sinh(x) 
 

This function computes the hyperbolic sine of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic example 
 

This example returns 1.1752011936438014. 
 

... | eval n=sinh(1) 
 



tan(x) 
 

This function computes the tangent of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 

Basic examples 
 

This example returns 1.5574077246549023. 
 

... | eval n=tan(1) 
 

This example returns -0.08871575677006045. 
 

... | eval n=tan(135) 
 



tanh(x) 
 

This function computes the hyperbolic tangent of x radians. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ebb2b7dc-a507-4b8b-8b90-cfccc91cc0ba�h+)�}�(h}�(h/Xj... | eval n=tan(1) 
 

This example returns -0.08871575677006045. 
 

... | eval n=tan(135) 
 



tanh(x) 
 

This function computes the hyperbolic tangent of x radians. 
 

Usage 
 

You can use this function with the eval and  where commands, in the WHERE clause of the from command, and as part 
of evaluation expressions with other commands. 
 





120 
 
Basic example 
 

This example returns 0.7615941559557649. 
 

... | eval n=tanh(1) 
 

See also 
 

Function information 
 

Overview of SPL2 eval functions 
 


















































121 
 
Statistical and Charting Functions 
 


Overview of SPL2 stats and chart functions 
 
Use statistical and charting functions to generate a calculation, such as an average or percentage, based on the fields in 
your events. 
 

Quick reference 
 

See the SPL2 Stats and Charting Functions Quick Reference for a list of the supported statistical functions, along with a 
brief description and the syntax for each function. 
 

Commands that use stats functions 
 

You can use the statistical and charting functions with the stats, eventstats,  streamstats, and timechart commands. 
 

Using eval expressions in statistical and charting functions 
 

In some of the examples for the statistical and charting functions you might see eval expressions. 
 

Using an eval expression in a statistical or charting function is a shortcut for specifying an eval command that creates a 
field, followed by a stats command that references that field. 
 

For example: 
 

... | stats count(eval(status="404")) AS count_status BY sourcetype 
 

Here's another example: 
 

... | timechart eval(round(avg(cpu_seconds),2)) BY processor 
 

When you use an eval expression with the timechart command, you must also use BY clause. 
 


As a shortcut, you can use an eval <expression> in a statistical or charting function where you would normally use a 
<field>. One example of the eval <expression> syntax is: 
 


... | stats func(eval(<expression>)) 
 
This eval <expression> syntax is equivalent to this command syntax: 
 


... | eval temp_field = <expression> | stats func(temp_field)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c74cf419-2863-4fbc-98c6-8b52b92e6948�h+)�}�(h}�(h/XF... | stats func(eval(<expression>)) 
 
This eval <expression> syntax is equivalent to this command syntax: 
 


... | eval temp_field = <expression> | stats func(temp_field) 
 

This eval <expression> syntax is equivalent to this command syntax: 
 


... | eval temp_field = <expression> | stats func(temp_field) 
 



122 
 
Using functions 
 

• All functions that accept strings can accept either a literal string or a field name. 
 


Some field values are processed as string literals 
 

Most of the statistical and charting functions expect the field values to be numbers. All of the values are processed as 
numbers, and any non-numeric values are ignored. 
 

The following functions process the field values as string literal values, even though the values are numbers. 
 



• count 
 



• estdc 
 


• max 
• min 
 
• earliest 
 
• first 
 
• list 
 
• values 
 
For example, you use the distinct_count function and the field contains values such as "1", "1.0", and "01". Each value is 
considered a distinct string value. 
 

The only exceptions are the max and min functions. These functions process values as numbers if possible. For example, 
the values "1", "1.0", and "01" are processed as the same numeric value. 
 

See also 
 

Functions 
 

Overview of SPL2 dataset_functions 
 



SPL2 Stats and Charting Functions Quick Reference 
 
There are two ways to find information about the supported statistical and charting functions: 
 

• Function list by category 
 


Function list by category 
 

The following table is a quick reference of the supported statistical and charting functions. This table lists the syntax and 
provides a brief description for each of the functions. Use the links in the Type of function column for more details and 
examples. 
 

	Type of 
function 
 


Supported functions and syntax 
 


Description 
 
Aggregate 
functions 
 
avg(<value>) 
count(<value>) 
 
Returns the average of the values in a field. 
Returns the number of occurrences in a field. 
 
distinct _count(<value>) 
 
Returns a count of the distinct values in a field. 
 

123�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dd6c10c8-1730-41fc-8364-0ad25c72fcc7�h+)�}�(h}�(h/Xcount(<value>) 
 
Returns the average of the values in a field. 
Returns the number of occurrences in a field. 
 
distinct _count(<value>) 
 
Returns a count of the distinct values in a field. 
 

123 
 
Supported functions and syntax 
 
Description 
 


estdc(<value>) 
 


Returns an estimated count of the distinct values in a field. 
 

estdc_error(<value>) 
 
Returns the theoretical error of the estimated count of the distinct values in a 
field. 
 
	Type of 
function 
 
max(<value>) 
mean(<value>) 
 
Returns the maximum value in a field. 
Returns the arithmetic mean of the values in a field. 
 
median(<value>) 
 
Returns the middle-most value in a field. 
 
min(<value>) 
 
Returns the minimum value in a field. 
 
mode(<value>) 
 
Returns the most frequent value in a field. 
 

percentile(<value>,<percentile>) 
 
Returns the nth percentile of the values in a numeric field. There are three 
percentile functions: exactperc, percentile, and upperperc(). 
 
range(<value>) 
 
Returns the difference between the maximum and minimum values in a field. 
 
stdev(<value>) 
 
Returns the sample standard deviation of the values in a field. 
 
stdevp(<value>) 
 
Returns the population standard deviation of the values in a field. 
 
sum(<value>) 
 
Returns the sum of the values in a field. 
 
sumsq(<value>) 
 
Returns the sum of the squares of the values in a field. 
 
var(<value>) 
 
Returns the sample variance of the values in a field. 
 
varp(<value>) 
 
Returns the population variance of the values in a field. 
 
Event order 
functions 
 

first(<value>) 
 
Returns the first seen value in a field. The first seen value is the most recent 
instance of this field, based on the order in which the events are seen by the 
stats command. 
 

last(<value>) 
 
Returns the last seen value in a field. The last seen value is the oldest instance 
of this field, based on the order in which the events are seen by the stats 
command. 
 
Multivalue and  dataset() or dataset(<fields>) 
array 
 
Aggregates events into arrays of SPL2 field-value objects.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$663ebcbf-9936-4d1c-936c-b69a13da00c1�h+)�}�(h}�(h/Xof this field, based on the order in which the events are seen by the stats 
command. 
 
Multivalue and  dataset() or dataset(<fields>) 
array 
 
Aggregates events into arrays of SPL2 field-value objects. 
Returns a multivalue entry from the values in a field. The order of the values 
reflects the order of the events. 
 
pivot(<key>,<value>) 
 
Aggregates the values in a field and returns the results as an object. 
 

values(<value>) 
 
Returns a list of the distinct values in a field as a multivalue entry. The order of 
the values is lexicographical. 
 
Time functions  earliest(<value>) 
 
Returns the chronologically earliest seen occurrence of a value in a field. 
 
earliest_time(<value>) 
 
Returns the UNIX time of the earliest occurrence of a value in a field. 
 
latest(<value>) 
 
Returns the chronologically latest seen occurrence of a value in a field. 
 

latest_time(<value>) 
 
Returns the UNIX time of the latest (most recent) occurrence of a value of the 
field. Used in conjunction with earliest, earliest_time, and latest to 
calculate the rate of increase for an accumulating counter. 
 
per_day(<value>) 
 
Returns the values in a field or eval expression for each day. 
 
per_hour(<value>) 
 
Returns the values in a field or eval expression for each hour. 
 



124 
 
Supported functions and syntax 
 
Description 
 
per_minute(<value>) 
 
Returns the values in a field or eval expression for each minute. 
 
per_second(<value>) 
 
Returns the values in a field or eval expression for each second. 
 


rate(<value>) 
 
Returns the per-second rate change of the value of the field. Represents 
(latest - earliest) / (latest_time - earliest_time) Requires 
the earliest and latest values of the field to be numerical, and the 
earliest_time and latest_time values to be different. 
 
Alphabetical list of functions 
 

The following table is a quick reference of the supported statistical and charting functions. This table lists the syntax and 
provides a brief description for each of the functions. Use the links for more details and examples.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a07a7026-e364-4b6f-8da1-f9065094c198�h+)�}�(h}�(h/XNprovides a brief description for each of the functions. Use the links for more details and examples. 
 


Supported functions and syntax 
 


Description 
 

	Type of 
function 
 

avg(<value>) 
 

Returns the average of the values in a field. 
 
Aggregate 
functions 
 

count(<value>) 
 

Returns the number of occurrences in a field. 
 
Aggregate 
functions 
 

dataset() or dataset(<fields>) 
 

Aggregates events into arrays of SPL2 field-value objects. 
 
Multivalue 
and array 
functions 
 

distinct _count(<value>) 
 

Returns a count of the distinct values in a field. 
 
Aggregate 
functions 
 

earliest(<value>) 
 

Returns the chronologically earliest seen occurrence of a value in a field. 
 
Time 
functions 
 

earliest_time(<value>) 
 

Returns the UNIX time of the earliest occurrence of a value of the field. 
 
Time 
functions 
 

estdc(<value>) 
 

Returns an estimated count of the distinct values in a field. 
 
Aggregate 
functions 
 

estdc_error(<value>) 
 

Returns the theoretical error of the estimated count of the distinct values in a field. 
 
Aggregate 
functions 
 

first(<value>) 
 
Returns the first seen value in a field. The first seen value is the most recent 
instance of this field, based on the order in which the events are seen by the 
stats command. 
 

Event order 
functions 
 

last(<value) 
 
Returns the last seen value in a field. The last seen value is the oldest instance of 
this field, based on the order in which the events are seen by the stats 
command. 
 

Event order 
functions 
 

latest(<value>) 
 

Returns the chronologically latest seen occurrence of a value in a field. 
 
Time 
functions 
 

latest_time(<value>) 
 

Returns the UNIX time of the latest occurrence of a value in a field. 
 
Time 
functions 
 

list(<value>) 
 

Returns a multivalue entry from the values in a field. The order of the values 
reflects the order of the events. 
 
Multivalue 
and array 
functions 
 
max(<value>) 
 
Returns the maximum value in a field. 
 
Aggregate 
functions 
 


125 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

mean(<value>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dfa382a3-d8c2-44d1-9374-fb90e0fbb855�h+)�}�(h}�(h/XlMultivalue 
and array 
functions 
 
max(<value>) 
 
Returns the maximum value in a field. 
 
Aggregate 
functions 
 


125 
 
Supported functions and syntax 
 
Description 
 
	Type of 
function 
 

mean(<value>) 
 

Returns the arithmetic mean of the values in a field. 
 

Aggregate 
functions 
 

median(<value>) 
 

Returns the middle-most value in a field. 
 
Aggregate 
functions 
 

min(<value>) 
 

Returns the minimum value in a field. 
 
Aggregate 
functions 
 

mode(<value>) 
 

Returns the most frequent value in a field. 
 
Aggregate 
functions 
 

percentile(<value>,<percentile>) 
 
Returns the nth percentile of the values in a numeric field. There are three 
percentile functions: exactperc, percentile, and upperperc(). 
 
Aggregate 
functions 
 

per_day(<value>) 
 

Returns the values in a field or eval expression for each day. 
 
Time 
functions 
 

per_hour(<value>) 
 

Returns the values in a field or eval expression for each hour. 
 
Time 
functions 
 

per_minute(<value>) 
 

Returns the values in a field or eval expression for each minute. 
 
Time 
functions 
 

per_second(<value>) 
 

Returns the values in a field or eval expression for each second. 
 
Time 
functions 
 

pivot(<key>,<value>) 
 

Aggregates the values in a field and returns the results as an object. 
 
Multivalue 
and array 
functions 
 

range(<value>) 
 

Returns the difference between the maximum and minimum values in a field. 
 
Aggregate 
functions 
 


rate(<value>) 
 
Returns the per-second rate change of the value of the field. Represents 
(latest - earliest) / (latest_time - earliest_time) Requires 
the earliest and latest values of the field to be numerical, and the 
earliest_time and latest_time values to be different. 
 

Time 
functions 
 

stdev(<value>) 
 

Returns the sample standard deviation of the values in a field. 
 
Aggregate 
functions 
 

stdevp(<value>) 
 

Returns the population standard deviation of the values in a field. 
 
Aggregate 
functions 
 

sum(<value>) 
 

Returns the sum of the values in a field. 
 
Aggregate 
functions 
 

sumsq(<value>) 
 

Returns the sum of the squares of the values in a field.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$208e36d1-1e0a-4c45-94bc-898572f7b4b1�h+)�}�(h}�(h/XAggregate 
functions 
 

sum(<value>) 
 

Returns the sum of the values in a field. 
 
Aggregate 
functions 
 

sumsq(<value>) 
 

Returns the sum of the squares of the values in a field. 
 
Aggregate 
functions 
 

var(<value>) 
 

Returns the sample variance of the values in a field. 
 
Aggregate 
functions 
 

varp(<value>) 
 

Returns the population variance of the values in a field. 
 
Aggregate 
functions 
 

values(<value>) 
 

Returns a list of the distinct values in a field as a multivalue entry. The order of the 
values is lexicographical. 
 
Multivalue 
and array 
functions 
 




126 
 
See also 
 

• Overview of SPL2 stats functions 
• Eval Functions Quick Reference 
 


Aggregate functions 
 
Aggregate functions summarize the values from each event to create a single, meaningful value. Common aggregate 
functions include Average, Count, Minimum, Maximum, Standard Deviation, Sum, and Variance. 
 

Most aggregate functions are used with numeric fields. However, there are some functions that you can use with either 
alphabetic string fields or numeric fields. The function descriptions indicate which functions you can use with alphabetic 
strings. 
 

For an overview, see Overview of SPL2 stats functions. 
 

avg(<value>) 
 

This function returns the average, or mean, of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

The following example returns the average of the values in the size field for each distinct value in the host field. 
 

... | stats avg(size) BY host 
 


The following example returns the average thruput of each host for each 5 minute time span. 
 

... | bin _time span=5m | stats avg(thruput) BY host 
 


The following example displays a timechart of the average of the cpu_seconds field by processor, rounded to 2 decimal 
points. 
 

... | timechart eval(round(avg(cpu_seconds),2)) BY processor 
 

When you use a eval expression with the timechart command, you must also use BY clause. 
 

count(<value>) or c(<value>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8942614e-f111-413f-a2b0-1ed0fa1ac41d�h+)�}�(h}�(h/X0points. 
 

... | timechart eval(round(avg(cpu_seconds),2)) BY processor 
 

When you use a eval expression with the timechart command, you must also use BY clause. 
 

count(<value>) or c(<value>) 
 

This function returns the number of occurrences in a field. 
 





127 
 
Usage 
 

To use this function, you can specify count(<value>), or the abbreviation c(<value>). 
 

This function processes field values as strings. 
 

To indicate a specific field value to match, use the format <field>=<value>. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

Several of these examples use an eval expression with the count function. See Using eval expressions in stats functions. 
 


The following example returns the count of events where the status field has the value "404". 
 

...| stats count(eval(status="404")) AS count_status BY sourcetype 
 


The following example separates the search results into 10 bins and counts the values in the _raw field for each bin. 
 

... | bin size bins=10 | stats count(_raw) BY size 
 


You can use search literals in functions that accept predicate expressions. Search literals are enclosed in backtick 
characters ( ` ). The following search uses a search literal to count the occurrences of the value 500 in your events. The 
results are organized by the host field: 
 

... | stats count(`500`) by host 
 

For more information, see Search literals in expressions. 
 


The following example uses the timechart command to count the events where the action field contains the value 
purchase. 
 

| from my_dataset where sourcetype="access_*" | timechart count(eval(action="purchase")) BY productName 
usenull=f useother=f 
 



distinct_count(<value>) or dc(<value>) 
 

This function returns the count of distinct values in a field. 
 

Usage 
 

To use this function, you can specify distinct_count(), or the abbreviation dc(). 
 

This function processes field values as strings. 
 



128 
 
You can use this function with the stats, eventstats, streamstats, and timechart commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$48e6eff7-355c-454a-a435-c039947a5e55�h+)�}�(h}�(h/X�This function processes field values as strings. 
 



128 
 
You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Basic examples 
 

The following example removes duplicate results with the same host value and returns the total count of the remaining 
results. 
 

... | stats dc(host) 
 


The following example generates the distinct count of the values in the devices field. The results are returned in a field 
called numdevices. 
 

...| stats dc(device) AS numdevices 
 


The following example counts the distinct client IP addresses for each host and category, and then bins the count for each 
result into five minute spans. 
 

... | stats dc(clientip) BY host, categoryId | bin _time span=5m 
 

Extended example 
 

The following search counts the number of different customers who purchased something from the Buttercup Games 
online store yesterday. The search organizes the count by the type of product , such as accessories, t-shirts, and type of 
games, that customers purchased. 
 

| from my_dataset where sourcetype="access_*" action=purchase | stats dc(clientip) BY categoryId 
 

• This example first searches for purchase events, action=purchase. 
 

made purchases. 
 



The results look like this: 
 

categoryId 
 

dc(clientip) 
 
ACCESSORIES 
 
37 
 
ARCADE 
 
58 
 
NULL 
 
8 
 
SHOOTER 
 
31 
 
SIMULATION 
 
34 
 
SPORTS 
 
13 
 
STRATEGY 
 
74 
 
TEE 
 
38 
 




129 
 
estdc(<value>) 
 

This function returns the estimated count of the distinct values in a field. 
 

Usage 
 

This function processes field values as strings. 
 

The string values 1.0 and 1 are considered distinct values and counted separately. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

The following example removes duplicate results with the same host value in a field, and returns the estimated total count 
of the remaining results. 
 

... | stats estdc(host) 
 

The results look like this: 
 

estdc(host) 
 
6�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6d525bec-566c-46c6-adad-48c15265ccd5�h+)�}�(h}�(h/X�of the remaining results. 
 

... | stats estdc(host) 
 

The results look like this: 
 

estdc(host) 
 
6 
 
The following example generates the estimated distinct count of the devices field and renames the results field, 
numdevices. 
 

...| stats estdc(devices) AS numdevices 
 


The following example estimates the distinct count for the values in the source field for each sourcetype. The results are 
organized into 5 minute time spans. 
 

... | stats estdc(source) BY sourcetype | bin 5m 
 

estdc_error(<value>) 
 

This function returns the theoretical error of the estimated count of the distinct values in a field. 
 

The error represents this ratio: 
 

absolute_value(estimate_distinct_count - real_distinct_count) / real_distinct_count 
 

Usage 
 

This function processes field values as strings. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 






130 
 
Example 
 

The following example determines the error ratio for the estimated distinct count of the values in the host field. 
 

... | stats estdc_error(host) 
 

exactperc(<value>,<percentile>) 
 

This function returns an exact percentile based on the values in a numeric field. 
 

The exactperc function provides the exact value, but is very resource expensive for high cardinality fields. The exactperc 
function can consume a large amount of memory, which might impact how long it takes for a search to complete. 
 

Usage 
 

There are three percentile functions: exactperc, perc, and upperperc. For details about the differences, see the perc 
function. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

See the perc function. 
 

max(<value>) 
 

This function returns the maximum value in a field. 
 

Usage 
 

This function processes field values as numbers if possible, otherwise processes field values as strings. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7cefa942-424e-4bd0-ba10-9d4be0b89b85�h+)�}�(h}�(h/XZThis function processes field values as numbers if possible, otherwise processes field values as strings. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

If the values in the field are non-numeric, the maximum value is found using lexicographical ordering. 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or 
	after letters. 
 

Basic example 
 

This example returns the maximum value of the size field. 
 

... | stats max(size) 
 



131 
 
Extended example 
 

Calculate aggregate statistics for the magnitudes of earthquakes in an area 
 

This search uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that 
contains magnitude (mag), coordinates (latitude, longitude), region (place), etc., for each earthquake recorded. 
 
Search for earthquakes in and around California. Calculate the number of earthquakes that were recorded. Use statistical 
functions to calculate the minimum, maximum, range (the difference between the min and max), and average magnitudes 
of the recent earthquakes. List the values by magnitude type. 
 

source=all_month.csv place=*California* | stats count, max(mag), min(mag), range(mag), avg(mag) BY magType 
 

The results look like this: 
 

magType 
 

count 
 

max(mag) 
 

min(mag) 
 

range(mag) 
 

avg(mag) 
 
H 
 
123 
 
2.8 
 
0.0 
 
2.8 
 
0.549593 
 
MbLg 
 
1 
 
0 
 
0 
 
0 
 
0.0000000 
 
Md 
 
1565 
 
3.2 
 
0.1 
 
3.1 
 
1.056486 
 
Me 
 
2 
 
2.0 
 
1.6 
 
.04 
 
1.800000 
 
Ml 
 
1202 
 
4.3 
 
-0.4 
 
4.7 
 
1.226622 
 
Mw 
 
6 
 
4.9 
 
3.0 
 
1.9 
 
3.650000 
 
ml 
 
10 
 
1.56 
 
0.19 
 
1.37 
 
0.934000 
 
mean(<value>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$705ea95e-0aeb-42ee-a54f-79093af35971�h+)�}�(h}�(h/X0 
 
0.0000000 
 
Md 
 
1565 
 
3.2 
 
0.1 
 
3.1 
 
1.056486 
 
Me 
 
2 
 
2.0 
 
1.6 
 
.04 
 
1.800000 
 
Ml 
 
1202 
 
4.3 
 
-0.4 
 
4.7 
 
1.226622 
 
Mw 
 
6 
 
4.9 
 
3.0 
 
1.9 
 
3.650000 
 
ml 
 
10 
 
1.56 
 
0.19 
 
1.37 
 
0.934000 
 
mean(<value>) 
 

This function returns the arithmetic mean of the values in a field. 
 

The mean values should be exactly the same as the values calculated using the avg() function. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Basic example 
 

The following example returns the mean of the values in the kbps field. 
 

...| stats mean(kbps) 
 

Extended example 
 

This search uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that 
contains magnitude (mag), coordinates (latitude, longitude), region (place), etc., for each earthquake recorded. 
 
Run the following search to find the mean, standard deviation, and variance of the magnitudes of recent quakes by 
magnitude type. 
 

source=usgs place=*California* | stats count mean(mag), stdev(mag), var(mag) BY magType 
 

The results look like this: 
 

132 
 
magType 
 
count 
 
mean(mag) 
 
std(mag) 
 
var(mag) 
 
H 
 
123 
 
0.549593 
 
0.356985 
 
0.127438 
 
MbLg 
 
1 
 
0.000000 
 
0.000000 
 
0.000000 
 
Md 
 
1565 
 
1.056486 
 
0.580042 
 
0.336449 
 
Me 
 
2 
 
1.800000 
 
0.346410 
 
0.120000 
 
Ml 
 
1202 
 
1.226622 
 
0.629664 
 
0.396476 
 
Mw 
 
6 
 
3.650000 
 
0.716240 
 
0.513000 
 
ml 
 
10 
 
0.934000 
 
0.560401 
 
0.314049 
 
median(<value>) 
 

This function returns the middle-most value of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

If you have an even number of search results, the median calculation is the average of the two middle-most values. 
 

Basic example 
 

Consider the following list of values, which counts the number of different customers who purchased something from the 
Buttercup Games online store yesterday. The values are organized by the type of product (accessories, t-shirts, and type�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4cdab9fa-7f7e-4948-8128-1241f9244e85�h+)�}�(h}�(h/XButtercup Games online store yesterday. The values are organized by the type of product (accessories, t-shirts, and type 
of games) that customers purchased. 
 

categoryId 
 

count 
 
ACCESSORIES 
 
37 
 
ARCADE 
 
58 
 
NULL 
 
8 
 
SIMULATION 
 
34 
 
SPORTS 
 
13 
 
STRATEGY 
 
74 
 
TEE 
 
38 
 
When the list is sorted the the middle-most value is 37. 
 

categoryId 
 

count 
 
NULL 
 
8 
 
SPORTS 
 
13 
 
SIMULATION 
 
34 
 
ACCESSORIES 
 
37 
 
TEE 
 
38 
 



133 
 
categoryId 
 
count 
 
ARCADE 
 
58 
 
STRATEGY 
 
74 
 
The middle-most value is returned when there are an odd number of results. When there are an even number of 
results, the average of the two middle-most numbers is returned. 
 

min(<value>) 
 

This function returns the minimum value in a field. 
 

Usage 
 

This function processes field values as numbers if possible, otherwise processes field values as strings. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

If the values in the field are non-numeric, the minimum value is found using lexicographical ordering. 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or 
	after letters. 
 

Basic examples 
 

The following example returns the minimum size and maximum size of the HotBucketRoller component in the _internal 
index. 
 

index=_internal component=HotBucketRoller | stats min(size), max(size) 
 


The following example returns a list of processors and calculates the minimum cpu_seconds and the maximum 
cpu_seconds. 
 

index=_internal | chart min(cpu_seconds), max(cpu_seconds) BY processor 
 

Extended example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8955b57d-d4cc-421c-92c5-ebf54cc6db82�h+)�}�(h}�(h/X\cpu_seconds. 
 

index=_internal | chart min(cpu_seconds), max(cpu_seconds) BY processor 
 

Extended example 
 

See the Extended example for the max() function. That example includes the min() function. 
 

mode(<value>) 
 

This function returns the most frequent value in a field. 
 




134 
 
Usage 
 

This function processes field values as strings. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

The mode returns the most frequent value. Consider the following data: 
 

firstname 
 

surname 
 

age 
 
Claudia 
 
Garcia 
 
32 
 
David 
 
Mayer 
 
45 
 
Alex 
 
Garcia 
 
29 
 
Wei 
 
Zhang 
 
45 
 
Javier 
 
Garcia 
 
37 
 
When you search for the mode in the age field, the value 45 is returned. 
 

...| stats mode(age) 
 


You can also use mode with fields that contain string values. When you search for the mode in the surname field, the value 
Garcia is returned. 
 

...| stats mode(surname) 
 


Here's another set of sample data: 
 

_time 
 

host 
 

sourcetype 
 
04-06-2020 17:06:23.000 PM 
 
www1 
 
access_combined 
 
04-06-2020 10:34:19.000 AM 
 
www1 
 
access_combined 
 
04-03-2020 13:52:18.000 PM 
 
www2 
 
access_combined 
 
04-02-2020 07:39:59.000 AM 
 
www3 
 
access_combined 
 
04-01-2020 19:35:58.000 PM 
 
www1 
 
access_combined 
 
If you run a search that looks for the mode in the host field, the value www1 is returned because it is the most common 
value in the host field. For example: 
 

... |stats mode(host) 
 

The results look something like this: 
 

mode(host) 
 
www1 
 


135 
 
perc(<value>,<percentile>) 
 

This function returns an approximate percentile based on the values in a numeric field. 
 

There are three percentile functions. These functions return the nth percentile of the values in a numeric field. You can 
think of this as an estimate of where the top N% starts. For example, a 95th percentile says that 95% of the values in the 
field are below the estimate and 5% of the values in the field are above the estimate. 
 

Valid percentiles are floating point numbers between 0 and 100, such as 99.95.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0b0cf4c2-1739-47e1-9a44-c68dfc79c4d6�h+)�}�(h}�(h/X�field are below the estimate and 5% of the values in the field are above the estimate. 
 

Valid percentiles are floating point numbers between 0 and 100, such as 99.95. 
 

Differences between the percentile functions: 
 

Function 
 

Description 
 

perc(<value>,<percentile>) 

• 
 
Use the perc function to calculate an approximate threshold, such that the values in a field fall below the 
percentile threshold you specify. The perc function returns a single number that represents the lower end of 
the approximate values for the percentile requested. 
 
upperperc(<value>,<percentile>) 
 
When there are more than 1000 values, the upperperc function gives the approximate upper bound for the 
percentile requested. Otherwise the upperperc function returns the same percentile as the perc function. 
 

exactperc(<value>,<percentile>) 
 
The exactperc function provides the exact value, but is very resource expensive for high cardinality fields. 
The exactperc function can consume a large amount of memory, which might impact how long it takes for 
a search to complete. 
 
The percentile functions process field values as strings. 
 

The perc and upperperc functions give approximate values for the integer percentile requested. The approximation 
algorithm that is used, which is based on dynamic compression of a radix tree, provides a strict bound of the actual value 
for any percentile. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

In the search results, the field names use this format: perc<percentage>(<value>) regardless of the 
 

Valid syntax 
 

To use this function, you can specify perc() using one of the following syntaxes: 
 

Syntax 
 

Example 
 
perc(<value>,<percentile>) ... | stats perc(host, 95) 
 
perc<percentile>(<value>)  ... | stats perc95(host) 
 
Differences between Splunk and Excel percentile algorithms 
 

If there are less than 1000 distinct values, the Splunk percentile functions use the nearest rank algorithm. See�h1h2h3}�h5Kuh�(h3h/�h}�ub�$92e9f05c-4ea4-4695-a0a5-6c728231d51d�h+)�}�(h}�(h/XODifferences between Splunk and Excel percentile algorithms 
 

If there are less than 1000 distinct values, the Splunk percentile functions use the nearest rank algorithm. See 
http://en.wikipedia.org/wiki/Percentile#Nearest_rank. Excel uses the NIST interpolated algorithm, which basically means 
you can get a value for a percentile that does not exist in the actual data, which is not possible for the nearest rank 
approach. 
 





136 
 
Splunk algorithm with more than 1000 distinct values 
 

If there are more than 1000 distinct values for the field, the percentiles are approximated using a custom radix-tree 
digest-based algorithm. This algorithm is much faster and uses much less memory, a constant amount, than an exact 
computation, which uses memory in linear relation to the number of distinct values. By default this approach limits the 
approximation error to < 1% of rank error. That means if you ask for 95th percentile, the number you get back is between 
the 94th and 96th percentile. 
 

You always get the exact percentiles even for more than 1000 distinct values by using the exactperc function instead of 
the perc function. 
 

Basic examples 
 

Consider this list of values {10,9,8,7,6,5,4,3,2,1} in the myfield field. 
 

The following example returns the 90th percentage for the values: 
 

...| stats perc(myfield, 90) 
 

The results look like this: 
 

perc90(myfield) 
 
9.1 
 
The following example returns several percentages: 
 

...| stats perc(score,95), perc(score,50), perc(score,25) 
 

The results look like this: 
 

perc95(myfield) 
 

perc50(myfield) 
 

perc55(myfield) 
 
9.55 
 
5.5 
 
3.25 
 
Extended example 
 

Consider the following set of data, which shows the number of visitors for each hour a store is open: 
 

hour 
 

visitors 
 
0800 
 
0 
 
0900 
 
212 
 
1000 
 
367 
 
1100 
 
489 
 
1200 
 
624 
 
1300 
 
609 
 
1400 
 
492 
 
1500 
 
513 
 
1600 
 
376 
 


137 
 
hour 
 
visitors 
 
1700 
 
337 
 
Let's use a dataset literal to create a temporary dataset from this data and then run the streamstats command to create a 
cumulative total for the visitors.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ef22443d-9af5-4676-b402-1242789cb3e1�h+)�}�(h}�(h/X376 
 


137 
 
hour 
 
visitors 
 
1700 
 
337 
 
Let's use a dataset literal to create a temporary dataset from this data and then run the streamstats command to create a 
cumulative total for the visitors. 
 

| FROM [{hour: 0800, visitors: 0}, {hour: 0900, visitors: 212}, {hour: 1000, visitors: 367}, {hour: 1100, 
visitors: 489}, {hour: 1200, visitors: 624}, {hour: 1300, visitors: 609}, {hour: 1400, visitors: 492}, 
{hour: 1500, visitors: 513}, {hour: 1600, visitors: 367}, {hour: 1700, visitors: 337}] | streamstats 
sum(visitors) as 'visitors total' 
 

The results from this search look like this: 
 

hour 
 

visitors 
 

visitors total 
 
0800 
 
0 
 
0 
 
0900 
 
212 
 
212 
 
1000 
 
367 
 
579 
 
1100 
 
489 
 
1068 
 
1200 
 
624 
 
1692 
 
1300 
 
609 
 
2301 
 
1400 
 
492 
 
2793 
 
1500 
 
513 
 
3306 
 
1600 
 
376 
 
3673 
 
1700 
 
337 
 
4010 
 
Let's add the stats command with the perc function to determine the 50th and 95th percentiles. 
 

| FROM [{hour: 0800, visitors: 0}, {hour: 0900, visitors: 212}, {hour: 1000, visitors: 367}, {hour: 1100, 
visitors: 489}, {hour: 1200, visitors: 624}, {hour: 1300, visitors: 609}, {hour: 1400, visitors: 492}, 
{hour: 1500, visitors: 513}, {hour: 1600, visitors: 367}, {hour: 1700, visitors: 337}] | streamstats 
sum(visitors) as 'visitors total' | stats perc50('visitors total') perc95('visitors total') 
 

The results from this search look like this: 
 

perc50(visitors total) 
 

perc95(visitors total) 
 
1996.5 
 
3858.35 
 
The perc50 estimates the 50th percentile, when 50% of the visitors had arrived. You can see from the data that the 50th 
percentile was reached between visitor number 1996 and 1997, which was sometime between 1200 and 1300 hours. The 
perc95 estimates the 95th percentile, when 95% of the visitors had arrived. The 95th percentile was reached with visitor 
3858, which occurred between 1600 and 1700 hours. 
 

range(<value>) 
 

Returns the difference between the maximum and minimum values in a field. 
 





138 
 
Usage 
 

The values in the field must be numeric.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8994181c-2bd2-4488-a77a-456cc9752eb3�h+)�}�(h}�(h/XM3858, which occurred between 1600 and 1700 hours. 
 

range(<value>) 
 

Returns the difference between the maximum and minimum values in a field. 
 





138 
 
Usage 
 

The values in the field must be numeric. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Basic example 
 

This example uses events that list the numeric sales for each product and quarter, for example: 
 

products 
 

quarter 
 

sales 
 

quota 
 
ProductA 
 
QTR1 
 
1200 
 
1000 
 
ProductB 
 
QTR1 
 
1400 
 
1550 
 
ProductC 
 
QTR1 
 
1650 
 
1275 
 
ProductA 
 
QTR2 
 
1425 
 
1300 
 
ProductB 
 
QTR2 
 
1175 
 
1425 
 
ProductC 
 
QTR2 
 
1550 
 
1450 
 
ProductA 
 
QTR3 
 
1300 
 
1400 
 
ProductB 
 
QTR3 
 
1250 
 
1125 
 
ProductC 
 
QTR3 
 
1375 
 
1475 
 
ProductA 
 
QTR4 
 
1550 
 
1300 
 
ProductB 
 
QTR4 
 
1700 
 
1225 
 
ProductC 
 
QTR4 
 
1625 
 
1350 
 
It is easiest to understand the range if you also determine the min and max values. To determine the range of sales by 
product, run this search: 
 

... | stats sum(sales), min(sales), max(sales), range(sales) BY products 
 

The results look something like this: 
 

quarter 
 

sum(sales) 
 

min(sales) 
 

max(sales) 
 

range(sales) 
 
QTR1 
 
4250 
 
1200 
 
1650 
 
450 
 
QTR2 
 
4150 
 
1175 
 
1550 
 
375 
 
QTR3 
 
3925 
 
1250 
 
1375 
 
125 
 
QTR4 
 
4875 
 
1550 
 
1700 
 
150 
 
The range(sales) is max(sales) minus min(sales). 
 

Extended example 
 

See the Extended example for the max() function. That example includes the range() function. 
 





139 
 
stdev(<value>) 
 

This function returns the sample standard deviation of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

A sample standard deviation is different than a population standard deviation. A sample standard deviation is calculated 
from a larger population by dividing the number of data points by 1 less than the total data points. 
 

For information about creating a population standard deviation, see the stdevp function. 
 

Basic example�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aff511c6-4b12-42cf-9065-31df2a69a480�h+)�}�(h}�(h/XgFor information about creating a population standard deviation, see the stdevp function. 
 

Basic example 
 

This example returns the standard deviation of fields that end in the word delay which can apply to both, delay and 
xdelay. Because a wildcard is used, you must use single quotation marks to enclose the field name. 
 

... | stats stdev('*delay') 
 

Extended example 
 

This search uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file that 
contains magnitude (mag), coordinates (latitude, longitude), region (place), etc., for each earthquake recorded. 
 
Run the following search to find the mean, standard deviation, and variance of the magnitudes of recent quakes by 
magnitude type. 
 

source=usgs place=*California* | stats count(), mean(mag), stdev(mag), var(mag) BY magType 
 

The results look like this: 
 

magType 
 

count 
 

mean(mag) 
 

std(mag) 
 

var(mag) 
 
H 
 
123 
 
0.549593 
 
0.356985 
 
0.127438 
 
MbLg 
 
1 
 
0.000000 
 
0.000000 
 
0.000000 
 
Md 
 
1565 
 
1.056486 
 
0.580042 
 
0.336449 
 
Me 
 
2 
 
1.800000 
 
0.346410 
 
0.120000 
 
Ml 
 
1202 
 
1.226622 
 
0.629664 
 
0.396476 
 
Mw 
 
6 
 
3.650000 
 
0.716240 
 
0.513000 
 
ml 
 
10 
 
0.934000 
 
0.560401 
 
0.314049 
 
stdevp(<value>) 
 

This function returns the population standard deviation of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 



140 
 
A sample population deviation is different than a sample standard deviation. A population standard deviation is calculated 
from the entire population. 
 

For information about creating a sample standard deviation, see the stdev function. 
 

Basic example 
 

The following example calculates the population standard deviation of the field lag. 
 

... | stats stdevp(lag) 
 

sum(<value>) 
 

This function returns the sum of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

You can create totals for any numeric field. For example:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4aaa4c87-4145-49af-96ad-e6a37cd94b6a�h+)�}�(h}�(h/X`Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

You can create totals for any numeric field. For example: 
 

...| stats sum(bytes) 
 

The results look something like this: 
 

sum(bytes) 
 
21502 
 

You can rename the column using the AS keyword: 
 

...| stats sum(bytes) AS "total bytes" 
 

The results look something like this: 
 

total bytes 
 
21502 
 

You can organize the results using a BY clause: 
 

...| stats sum(bytes) AS "total bytes" by date_hour 
 

The results look something like this: 
 

date_hour 
 

total bytes 
 
07 
 
6509 
 
11 
 
3726 
 


141 
 
date_hour 
 
total bytes 
 
15 
 
6569 
 
23 
 
4698 
 
sumsq(<value>) 
 

This function returns the sum of the squares of the values in a field. 
 

The sum of the squares is used to evaluate the variance of a dataset from the dataset mean. A large sum of the squares 
indicates a large variance, which tells you that individual values fluctuate widely from the mean. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Example 
 

The following table contains the temperatures taken every day at 8 AM for a week. 
 

You calculate the mean of the these temperatures and get 48.9 degrees. To calculate the deviation from the mean for 
each day, take the temperature and subtract the mean. If you square each temperature, you get results like this: 
 

day 
 

temperature 
 

mean 
 

deviation 
 

square of temperatures 
 
sunday 
 
65 
 
48.9 
 
16.1 
 
260.6 
 
monday 
 
42 
 
48.9 
 
-6.9 
 
47.0 
 
tuesday 
 
40 
 
48.9 
 
-8.9 
 
78.4 
 
wednesday 
 
31 
 
48.9 
 
-17.9 
 
318.9 
 
thursday 
 
47 
 
48.9 
 
-1.9 
 
3.4 
 
friday 
 
53 
 
48.9 
 
4.1 
 
17.2 
 
saturday 
 
64 
 
48.9 
 
15.1 
 
229.3 
 
Take the total of the squares, 954.9, and divide by 6 which is the number of days minus 1. This gets you the sum of 
squares for this series of temperatures. The standard deviation is the square root of the sum of the squares. The larger 
the standard deviation the larger the fluctuation in temperatures during the week.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cf797152-0a89-4327-8078-739897f1f9ff�h+)�}�(h}�(h/Xthe standard deviation the larger the fluctuation in temperatures during the week. 
 

You can calculate the mean, sum of the squares, and standard deviation with a few statistical functions. Let's use a 
dataset literal so that you can try this on your own: 
 

FROM [{day: "sun", temp: 65}, {day: "mon", temp: 42}, {day: "tue", temp: 40}, {day: "wed", temp: 31}, {day: 
"thu", temp: 47}, {day: "fri", temp: 53}, {day: "sat", temp: 64}] | stats mean(temp), sumsq(temp), 
stdev(temp) 
 

This search returns these results: 
 

mean(temp) 
 

sumsq(temp) 
 

stdev(temp) 
 
48.857142857142854 
 
17664 
 
12.615183595289349 
 


142 
 
upperperc(<value>,<percentile>) 
 

This function returns an approximate upper bound percentile value of a numeric field that contains more than 1000 values. 
 

The upperperc function returns an estimate of where the top N% starts. For example, a 95th percentile says that 95% of 
the data points are below the estimate and 5% of the data points are above the estimate. 
 

Usage 
 

There are three percentile functions: exactperc, perc, and upperperc. For details about the differences, see the perc 
function. 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

See the perc function. 
 

var(<value>) 
 

Returns the sample variance of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Examples 
 

Variance is often used to determine the standard deviation of a set of values. 
 

The following table contains the temperatures taken every day at 8 AM for a week. 
 

day 
 

temperature 
 
sunday 
 
65 
 
monday 
 
42 
 
tuesday 
 
40 
 
wednesday 
 
31 
 
thursday 
 
47 
 
friday 
 
53 
 
saturday 
 
64 
 
Let's use a dataset literal so that you can try this on your own: 
 

FROM [{day: "sun", temp: 65}, {day: "mon", temp: 42}, {day: "tue", temp: 40}, {day: "wed", temp: 31}, {day: 
"thu", temp: 47}, {day: "fri", temp: 53}, {day: "sat", temp: 64}] |stats mean(temp)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8d9970bd-e49a-4079-9c65-ef5edb2ce22f�h+)�}�(h}�(h/X$FROM [{day: "sun", temp: 65}, {day: "mon", temp: 42}, {day: "tue", temp: 40}, {day: "wed", temp: 31}, {day: 
"thu", temp: 47}, {day: "fri", temp: 53}, {day: "sat", temp: 64}] |stats mean(temp) 
 

You calculate the mean, which is the average, of the these temperatures and get 48.9 degrees. 
 


143 
 
mean(temp) 
 
48.857142857142854 
 
To calculate the deviation from the mean for each day, take the temperature and subtract the mean. 
 

day 
 

temp 
 

mean 
 

deviation 
 
sunday 
 
65 
 
48.9 
 
16.1 
 
monday 
 
42 
 
48.9 
 
-6.9 
 
tuesday 
 
40 
 
48.9 
 
-8.9 
 
wednesday 
 
31 
 
48.9 
 
-17.9 
 
thursday 
 
47 
 
48.9 
 
-1.9 
 
friday 
 
53 
 
48.9 
 
4.1 
 
saturday 
 
64 
 
48.9 
 
15.1 
 
To calculate the variance, square each deviation and average the result. Or just run this search: 
 

FROM [{day: "sun", temp: 65}, {day: "mon", temp: 42}, {day: "tue", temp: 40}, {day: "wed", temp: 31}, {day: 
"thu", temp: 47}, {day: "fri", temp: 53}, {day: "sat", temp: 64}] |stats mean(temp), var(temp), stdev(temp) 
 


This search returns these results: 
 

mean(temp) 
 

var(temp) 
 

stdev(temp) 
 
48.857142857142854 
 
159.14285714285748 
 
12.615183595289349 
 
The larger the standard deviation the larger the fluctuation in temperatures during the week. 
 

Extended example 
 

See the Extended example for the mean() function. That example includes the var() function. 
 

varp(<value>) 
 

Returns the population variance of the values in a field. 
 

Usage 
 

You can use this function with the stats, eventstats, streamstats, and timechart commands. 
 

Basic example 
 

See also 
 

Function information 
 

SPL2 Stats and Charting Functions Quick Reference 
Naming function arguments in the SPL2 Search Manual 
 


144 
 
Event order functions 
 
Use the event order functions to return values from fields based on the order in which the event is processed, which is not 
necessarily chronological or timestamp order. 
 

For an overview of the stats functions, see Overview of SPL2 stats functions. 
 

Chronological and timestamp order distinction�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6a364bad-e58c-44b6-9ccb-d453ea53d1f5�h+)�}�(h}�(h/X7necessarily chronological or timestamp order. 
 

For an overview of the stats functions, see Overview of SPL2 stats functions. 
 

Chronological and timestamp order distinction 
 

The following table lists the timestamps from a set of events returned from a search. This table identifies which event is 
returned when you use the first and last event order functions, and compares them with the earliest and latest time 
functions. See Time functions. 
 




_time 
 



Event order 
	function 
 




Description 
 
2021-04-28 
00:15:05 
 

first 
 
This event is the first event in the search results. But this event is not 
chronologically the earliest event. 
 
2021-05-01 
00:15:04 
 
2021-04-30 
00:15:02 
 
2021-04-28 
00:15:01 
 
2021-05-01 
00:15:05 
 

latest 
 

This event is chronologically the latest event in the search results. 
 

2021-04-27 
00:15:01 
 
earliest 

last 
 

This event is both the chronologically earliest event and the last event in the 
search results. 
 
first(<value>) 
 

Returns the first seen value in a field. 
 

The first seen value is the most recent instance of this field, based on the order in which the events are seen by the stats 
command. 
 

The order in which the events are seen is not necessarily chronological order. 
 

Usage 
 

You can use this function with the stats, streamstats, and timechart commands. 
 

• To locate the first value based on time order, use the earliest function instead. 
 

charting command. 
 



145 
 
Basic example 
 

You run the following search to locate invalid user login attempts against a specific sshd (Secure Shell Daemon). You use 
the fields command to see the values in the _time, source, and _raw fields. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw 
 


The results look something like this: 
 

_time 
 

source 
 

_raw 
 
2021-04-28 
00:15:05 
 

.../mailsv/secure.log 
 
Tue Apr 28 2021 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
tomcat from 67.170.226.218 port 1490 ssh2 
 
2021-05-01 
00:15:04 
 

.../www2/secure.log�h1h2h3}�h5Kuh�(h3h/�h}�ub�$47882194-7318-4b02-ae2b-2e14afb41198�h+)�}�(h}�(h/X"00:15:05 
 

.../mailsv/secure.log 
 
Tue Apr 28 2021 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
tomcat from 67.170.226.218 port 1490 ssh2 
 
2021-05-01 
00:15:04 
 

.../www2/secure.log 
 
Fri May 01 2021 00:15:04 www2 sshd[5258]: Failed password for invalid user 
brian from 130.253.37.97 port 4284 ssh2 
 
2021-04-30 
00:15:02 
 

.../www3/secure.log 
 
Thu Apr 30 2021 00:15:02 www3 sshd[5258]: Failed password for invalid user 
operator from 222.169.224.226 port 1711 ssh2 
 
2021-04-28 
00:15:01 
 

.../www1/secure.log 
 
Tue Apr 28 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user 
rightscale from 87.194.216.51 port 3361 ssh2 
 
2021-05-01 
00:15:05 
 

.../mailsv/secure.log 
 
Fri May 01 2021 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
testuser from 194.8.74.23 port 3626 ssh2 
 
2021-04-27 
00:15:01 
 

.../www1/secure.log 
 
Mon Apr 27 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user 
redmine from 91.208.184.24 port 3587 ssh2 
 
You extend the search using the first function. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw | stats 
first(_raw) 
 

The search returns the value for _raw field with the timestamp 2021-04-28 00:15:05, which is the first event in the original 
list of values returned. 
 

first(_raw) 
 
Tue Apr 28 2021 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user tomcat from 67.170.226.218 port 1490 
ssh2 
 
Extended example 
 

The Basic example uses the _raw field to show how the first function works. That's useful because the _raw field 
contains a timestamp. However, you can use the first function on any field. 
 

Let's start by creating some results. You can use the repeat dataset function to create a series of results to test your 
search syntax. To add a timestamp to the events, use the eval command with the now() time modifier. Include the 
streamstats command to count your results: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() 
 

The results look like this: 
 


146�h1h2h3}�h5Kuh�(h3h/�h}�ub�$86370097-7bfc-4243-8089-27658db3b33d�h+)�}�(h}�(h/X
streamstats command to count your results: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() 
 

The results look like this: 
 


146 
 
_time 
 
count 
 
2022-02-28 14:35:58 
 
1 
 
2022-02-28 14:35:58 
 
2 
 
2022-02-28 14:35:58 
 
3 
 
2022-02-28 14:35:58 
 
4 
 
2022-02-28 14:35:58 
 
5 
 
With the count field, you can create different dates in the _time field, using the eval command. 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*3600) 
 

Use 3600, the number of seconds in an hour, to create a series of hours. The calculation multiplies the value in the count 
field by the number of seconds in an hour. The result is subtracted from the original _time field to get new dates 
equivalent to 1 hours ago, 2 hours ago, and so forth. 
 

The minutes and seconds in the search results are slightly different because the timestamp is refreshed each time you 
run the search. 
 

The results look like this: 
 

_time 
 

count 
 
2022-02-28 13:45:24 
 
1 
 
2022-02-28 12:45:24 
 
2 
 
2022-02-28 11:45:24 
 
3 
 
2022-02-28 10:45:24 
 
4 
 
2022-02-28 09:45:24 
 
5 
 
The hours in the results begin with the 1 hour earlier than the original date, 2022-02-28 at 14:24. 
 

Use the eval command to add a field to your search results with values in descending order: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*3600) | eval 
field1=20-count 
 

The results look like this: 
 

_time 
 

count 
 

field1 
 
2022-02-28 14:47:12 
 
1 
 
19 
 
2022-02-28 13:47:12 
 
2 
 
18 
 
2022-02-28 12:47:12 
 
3 
 
17 
 
2022-02-28 11:47:12 
 
4 
 
16 
 
2022-02-28 10:47:12 
 
5 
 
15 
 
As you can see from the results, the first result contains the highest number in field1. This shows the order in which the 
results were processed. The first result was processed first (20-1=19) followed by the remaining results in order. 
 


147 
 
When you add the first function to the search, the only value returned is the value in the field you specify:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9a1d8faa-7ff0-47f0-9146-a25e3678a03c�h+)�}�(h}�(h/X2147 
 
When you add the first function to the search, the only value returned is the value in the field you specify: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*3600) | eval 
field1=20-count | stats first(field1) 
 

The results look like this: 
 

SingleValue 
 
19 
 
last(<value>) 
 

Returns the last seen value in a field. 
 

The last seen value of the field is the oldest instance of this field, based on the order in which the events are seen by the 
stats command. 
 

The order in which the events are seen is not necessarily chronological order. 
 

Usage 
 

You can use this function with the stats, streamstats, and timechart commands. 
 

• To locate the last value based on time order, use the latest function instead. 
 

• This function processes field values as strings. 
 

Basic example 
 

The following example returns the first log_level value for each distinct sourcetype. 
 

You run the following search to locate invalid user login attempts against a specific sshd (Secure Shell Daemon). You use 
the fields command to see the values in the _time, source, and _raw fields. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw 
 


The results look something like this: 
 

_time 
 

source 
 

_raw 
 
2021-04-28 
00:15:05 
 

.../mailsv/secure.log 
 
Tue Apr 28 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
tomcat from 67.170.226.218 port 1490 ssh2 
 
2021-05-01 
00:15:04 
 

.../www2/secure.log 
 
Fri May 01 2021 00:15:04 www2 sshd[5258]: Failed password for invalid user 
brian from 130.253.37.97 port 4284 ssh2 
 
2021-04-30 
00:15:02 
 

.../www3/secure.log 
 
Thu Apr 30 2021 00:15:02 www3 sshd[5258]: Failed password for invalid user 
operator from 222.169.224.226 port 1711 ssh2 
 
2021-04-28 
00:15:01 
 

.../www1/secure.log 
 
Tue Apr 28 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user 
rightscale from 87.194.216.51 port 3361 ssh2 
 



148 
 
_time 
 
source 
 
_raw 
 
2021-05-01 
00:15:05 
 

.../mailsv/secure.log�h1h2h3}�h5Kuh�(h3h/�h}�ub�$86d21bd0-7354-4f2e-95ac-a02372503558�h+)�}�(h}�(h/XTue Apr 28 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user 
rightscale from 87.194.216.51 port 3361 ssh2 
 



148 
 
_time 
 
source 
 
_raw 
 
2021-05-01 
00:15:05 
 

.../mailsv/secure.log 
 
Fri May 01 2021 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
testuser from 194.8.74.23 port 3626 ssh2 
 
2021-04-27 
00:15:01 
 

.../www1/secure.log 
 
Mon Apr 27 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user 
redmine from 91.208.184.24 port 3587 ssh2 
 
You extend the search using the last function. 
 

| FROM main WHERE `sourcetype=secure invalid user "sshd[5258]"` | fields _time, source, _raw | stats 
last(raw) 
 

The search returns the event with the _time value 2020-04-27 00:15:01, which is the last event in the list of events. 
However it is not the last chronological event. 
 

first(raw) 
 
Mon Apr 27 2021 00:15:01 www1 sshd[5258]: Failed password for invalid user redmine from 91.208.184.24 port 3587 
ssh2 
 
Extended example 
 

The Basic example uses the _raw field to show how the last function works. That's useful because the _raw field contains 
a timestamp. However, you can use the last function on any field. 
 

Let's start by creating some results. You can use the repeat dataset function to create a series of results to test your 
search syntax. To add a timestamp to the events, use the eval command with the now() time modifier. Include the 
streamstats command to count your results: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() 
 

The results look like this: 
 

_time 
 

count 
 
2022-02-28 14:35:58 
 
1 
 
2022-02-28 14:35:58 
 
2 
 
2022-02-28 14:35:58 
 
3 
 
2022-02-28 14:35:58 
 
4 
 
2022-02-28 14:35:58 
 
5 
 
With the count field, you can create different dates in the _time field, using the eval command. 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*86400) 
 

Use 86400, the number of seconds in a day, to create a series of days. The calculation multiplies the value in the count�(
h1h2h3}�h5Kuh�(h3h/�h}�ub�$3e5e933b-b343-478a-b535-1495b99a3dde�h+)�}�(h}�(h/X�Use 86400, the number of seconds in a day, to create a series of days. The calculation multiplies the value in the count 
field by the number of seconds in a day. The result is subtracted from the original _time field to get new dates equivalent 
to 1 day ago, 2 days ago, and so forth. 
 

The minutes and seconds in the search results are slightly different because the timestamp is refreshed each time you 
run the search. 
 


149 
 
The results look like this: 
 

_time 
 

count 
 
2022-02-27 14:45:24 
 
1 
 
2022-02-26 14:45:24 
 
2 
 
2022-02-25 14:45:24 
 
3 
 
2022-02-24 14:45:24 
 
4 
 
2022-02-23 14:45:24 
 
5 
 
The dates in the results begin with the 1 day earlier than the original date, 2022-02-28 at 14:45:24. 
 

Use the eval command to add a field to your search with values in descending order: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*86400) | eval 
field1=20-count 
 

The results look like this: 
 

_time 
 

count 
 

field1 
 
2022-02-28 14:47:12 
 
1 
 
19 
 
2022-02-28 14:47:12 
 
2 
 
18 
 
2022-02-28 14:47:12 
 
3 
 
17 
 
2022-02-28 14:47:12 
 
4 
 
16 
 
2022-02-28 14:47:12 
 
5 
 
15 
 
As you can see from the results, the last result contains the lowest number in field1. This shows the order in which the 
results were processed. The fifth result was processed last (20-5=15) after all of the other results. 
 

When you add the last function to the search, the only value returned is the value in the field you specify: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*86400) | eval 
field1=20-count | stats last(field1) 
 

The results look like this: 
 

SingleValue 
 
15 
 
See also 
 

Function information 
 

SPL2 Stats and Charting Functions Quick Reference 
Naming function arguments in the SPL2 Search Manual 
 




150 
 
Multivalue and array functions 
 
For an overview about the stats and charting functions, see Overview of SPL2 stats and chart functions. 
 

dataset() or dataset(<fields>)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$55025a3a-34d2-47d7-9675-82c246471daf�h+)�}�(h}�(h/XB150 
 
Multivalue and array functions 
 
For an overview about the stats and charting functions, see Overview of SPL2 stats and chart functions. 
 

dataset() or dataset(<fields>) 
 

The dataset function aggregates events into arrays of SPL2 field-value objects. See object in Built-in data types. 
 

Usage 
 

You can use this function in the SELECT clause in the from command and with the stats command. 
 

• If you specify dataset(), the function returns all of the fields in the events that match your search criteria. 
 

• If you specify dataset<fields>, the function returns only the specified fields in each event that match your search 
	criteria. The list of fields must be comma separated. 
 

Examples 
 

Return all fields and values in an array 
 

You can create a dataset array from all of the fields and values in the search results. 
 

Consider this set of data: 
 

_time 
 

department 
 

username 
 
13 Apr 2022 13:02:45.000 PM 
 
Engineering 
 
Claudia Garcia 
 
13 Apr 2022 10:52:41.000 AM 
 
IT 
 
Vanya Patel 
 
13 Apr 2022 06:23:48.000 AM 
 
Personnel 
 
Alex Martin 
 

Use the dataset function to create an array from all of the fields and values using the following search: 
 
...| stats dataset() 
 

The results look something like this: 
 

[{_time: 13 Apr 2022 13:02:45.000 PM, department: Engineering, username: "Claudia Garcia"}, {_time: 
13 Apr 2022 10:52:41.000 AM, department: IT, username: "Vanya Patel"}, {_time: 13 Apr 2022 
 


If you don't specify any fields with the dataset function, all of the fields are included in a single dataset array. A 
single dataset array is also returned if you specify a wildcard with the dataset function, for example: dataset(*). 
 

Return specific fields in an array 
 

You can specify multiple fields to populate the dataset arrays. 
 

Consider this set of data: 
 



151 
 
_time 
 
host 
 
action 
 
department 
 
uid 
 
username 
 
13 Apr 2022 13:02:45.000 PM 
 
mailsv2 
 
Failed password 
 
Engineering 
 
1066 
 
Claudia Garcia 
 
13 Apr 2022 10:52:41.000 AM 
 
mailsv1 
 
Failed password 
 
IT 
 
1815 
 
Vanya Patel�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8d8d7148-a9af-444e-82d4-4bbf012672d0�h+)�}�(h}�(h/X�department 
 
uid 
 
username 
 
13 Apr 2022 13:02:45.000 PM 
 
mailsv2 
 
Failed password 
 
Engineering 
 
1066 
 
Claudia Garcia 
 
13 Apr 2022 10:52:41.000 AM 
 
mailsv1 
 
Failed password 
 
IT 
 
1815 
 
Vanya Patel 
 
13 Apr 2022 06:23:48.000 AM 
 
mailsv3 
 
Session closed 
 
Personnel 
 
1916 
 
Alex Martin 
 
13 Apr 2022 06:23:48.000 AM 
 
mailsv3 
 
Failed password 
 
Engineering 
 
1862 
 
Wei Zhang 
 
12 Apr 2022 20:18:36.000 PM 
 
mailsv1 
 
Session closed 
 
Engineering 
 
1690 
 
Rutherford Sullivan 
 

The following search creates a dataset array with only the department and username field values. 
 

| FROM main SELECT dataset(department, username) 
 

The results look something like this: 
 

dataset(department, username) 
 
[{department: Engineering, username: "Claudia Garcia"}, {department: IT, username: "Vanya Patel"}, {department: Personnel, 
username: "Alex Martin"}, {department: Engineering, username: "Wei Zhang"},{department: Engineering, username: "Rutherford 
Sullivan"}] 
 

Use a BY clause to create separate arrays 
 

You can use a BY clause to organize the search results into separate dataset arrays. 
 

Consider this set of data. 
 

_time 
 

host 
 

action 
 

department 
 

uid 
 

username 
 
13 Apr 2022 13:02:45.000 PM 
 
mailsv2 
 
Failed password 
 
Engineering 
 
1066 
 
Claudia Garcia 
 
13 Apr 2022 10:52:41.000 AM 
 
mailsv1 
 
Failed password 
 
IT 
 
1815 
 
Vanya Patel 
 
13 Apr 2022 06:23:48.000 AM 
 
mailsv3 
 
Session closed 
 
Personnel 
 
1916 
 
Alex Martin 
 
13 Apr 2022 06:23:48.000 AM 
 
mailsv3 
 
Failed password 
 
Engineering 
 
1862 
 
Wei Zhang 
 
12 Apr 2022 20:18:36.000 PM 
 
mailsv1 
 
Session closed 
 
Engineering 
 
1690 
 
Rutherford Sullivan 
 

The following search organizes the dataset arrays by department. Each dataset array contains the user ID and 
username. 
 

| FROM main SELECT dataset(uid, username) GROUP BY department 
 

Because this search uses the from command, the GROUP BY clause is used. If you use this function with the 
stats command, you would specify the BY clause. 
 

The results look something like this: 
 

department 
 

dataset(uid, username) 
 


152�h1h2h3}�h5Kuh�(h3h/�h}�ub�$bfc76cc6-6770-47f4-858d-95d37181c486�h+)�}�(h}�(h/Xstats command, you would specify the BY clause. 
 

The results look something like this: 
 

department 
 

dataset(uid, username) 
 


152 
 
Engineering 
 
[{uid: 1066, username: "Claudia Garcia"}, {uid: 1690, username: "Rutherford Sullivan"}, {uid: 1862, 
username: "Wei Zhang"}] 
 
IT 
 
[{uid: 1815 , username: "Vanya Patel"}] 
 
Personnel 
 
[{uid: 1916, username: "Alex Martin"}] 
 

Rename the dataset field 
 

By default the field name created by the dataset function is the name of the function and the fields specified. You 
can rename the field that appears in the search results by using the AS keyword. For example: 
 

| FROM main | stats dataset(department, username) AS employees 
 

The results look something like this: 
 

employees 
 
[{department: Engineering, username: "Claudia Garcia"}, {department: IT, username: "Vanya Patel"}, {department: Personnel, 
username: "Alex Martin"}] 
 

Start the search with the SELECT clause 
 

This example shows how to use the dataset function with the SELECT clause in the from command. 
 

| SELECT dataset(department, username) FROM main 
 

The results look something like this: 
 

dataset(department, name) 
 
[{department: Engineering, username: "Claudia Garcia"}, {department: IT, username: "Vanya Patel"}, {department: Personnel, 
username: "Alex Martin"}, {department: Engineering, username: "Wei Zhang"},{department: Engineering, username: "Rutherford 
Sullivan"}] 
 

list(<value>) 
 

The list function returns a multivalue entry from the values in a field. The order of the values reflects the order of the 
events. 
 

Usage 
 

You can use this function with the stats, streamstats, and timechart commands. 
 

• If more than 100 values are in the field, only the first 100 are returned. 
• This function processes field values as strings. 
 

Example 
 

To illustrate what the list function does, let's start by generating a few simple results. 
 




153 
 
1. Use the from and streamstats commands to generate a set of 11 results that are simply timestamps and a count�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ec67ce3c-b44d-4534-8da1-2c73c6e4252c�h+)�}�(h}�(h/X>153 
 
1. Use the from and streamstats commands to generate a set of 11 results that are simply timestamps and a count 
	of the results, which are used as row numbers. Empty arrays with the from command generate the timestamps. 
 

| from [{},{},{},{},{},{},{},{},{},{},{}] | streamstats count AS rowNumber 
 

There are 11 results. Th first few results look something like this: 
 

_time 
 

rowNumber 
 
2019-10-10T07:19:02.000-07:00 
 
1 
 
2019-10-10T07:19:02.000-07:00 
 
2 
 
2019-10-10T07:19:02.000-07:00 
 
3 
 
2019-10-10T07:19:02.000-07:00 
 
4 
 
2019-10-10T07:19:02.000-07:00 
 
5 
 
Notice that each result appears on a separate row, with a line between each row. 
 



2. Add the stats command with the list function to the search. The numbers are returned in ascending order in a 
	single, multivalue result. 
 

| from [{},{},{},{},{},{},{},{},{},{},{}] | streamstats count AS rowNumber | stats list(rowNumber) 
AS numbers 
 

The results look something like this: 
 

numbers 
 
1 
2 
3 
4 
5 
6 
7 
8 
9 
 
11 
 
	Notice that this is a single result with multiple values. There are no lines between each value. 
3. Compare this result with the results returned by the values function. 
 

pivot(<key>,<value>) 
 

The pivot function aggregates the values in a field and returns the results as an object. See object in the list of built-in 
data types. 
 

Usage 
 

The <key> argument can be a single field or a string template, which can reference multiple fields. 
 

The <value> argument must be an aggregate, such as count() or sum(). 
 

154 
 
You can use this function with the SELECT clause in the from command, or with the stats command. 
 

Examples 
 

Using the pivot function 
 

Consider the following data that's in the main dataset: 
 

status 
 

host 
 
200 
 
www1 
 
200 
 
www2 
 
200 
 
www1 
 
400 
 
www2 
 
400 
 
www1 
 
400 
 
www3 
 
403 
 
www2 
 
404 
 
www2 
 

Use the pivot function to create an object that summarizes the HTTP status values for each separate host. The 
search looks like this: 
 

FROM main GROUP BY host SELECT host, pivot(status, count())�h1h2h3}�h5Kuh�(h3h/�h}�ub�$07f7fae7-b4bd-435a-b04a-fccab02efd7f�h+)�}�(h}�(h/X[Use the pivot function to create an object that summarizes the HTTP status values for each separate host. The 
search looks like this: 
 

FROM main GROUP BY host SELECT host, pivot(status, count()) 
 

The results look something like this: 
 

host 
 

pivot(status,count()) 
 
www1 
 
{"200":2,"400":1} 
 
www2 
 
{"200":1,"400":1,"403":1,"404":1} 
 
www3 
 
{"400":1} 
 



You can use the pivot function with the stats command to accomplish the same results: 
 

FROM main | stats pivot(status,count()) as pivotStatus by host 
 

In this search the output field, pivot(status,count()), is renamed using the AS clause. 
 

This search returns the same results as the previous search and looks something like this: 
 

host 
 

pivotStatus 
 
www1 
 
{"200":2,"400":1} 
 



155 
 
host 
 
pivotStatus 
 
www2 
 
{"200":1,"400":1,"403":1,"404":1} 
 
www3 
 
{"400":1} 
 

Creating nested objects with the pivot function 
 

You can use nested pivot functions to create nested objects. 
 

Consider the following data: 
 

status 
 

host 
 

action 
 
200 
 
www1 
 
purchase 
 
200 
 
www2 
 
purchase 
 
200 
 
www1 
 
addtocart 
 
200 
 
www2 
 
purchase 
 
400 
 
www1 
 
addtocart 
 
400 
 
www1 
 
purchase 
 
403 
 
www2 
 
changequantity 
 
404 
 
www1 
 
view 
 
404 
 
www3 
 
purchase 
 
404 
 
www2 
 
changequantity 
 
404 
 
www1 
 
purchase 
 

You can use one pivot function as the <value> argument in another pivot function to create nested objects: 
 

FROM main GROUP BY status SELECT status, pivot(host, pivot(action, count())) AS nestedPivot 
 

The results look something like this: 
 

status 
 

nestedPivot 
 
200 
 
{"www1":{"addtocart":1,"purchase":1},"www2":{"purchase":2}} 
 
400 
 
{"www1":{"addtocart":1,"purchase":1}} 
 
403 
 
{"www2":{"changequantity":1}} 
 
404 
 
{"www1":{"purchase":1,"view":1},"www2":{"changequantity":1},"www3":{"purchase":1}} 
 

Using a string template with the pivot function 
 

You can use a string template in the <value> argument of the pivot function. 
 



156 
 
In this example, the string template contains two template expressions, ${name} and ${city}, which are field�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7f5978cc-57f2-4179-b96f-df2da6ea6ac3�h+)�}�(h}�(h/X!You can use a string template in the <value> argument of the pivot function. 
 



156 
 
In this example, the string template contains two template expressions, ${name} and ${city}, which are field 
names. The entire string template is enclosed in double quotation marks: 
 

SELECT pivot("${name} in ${city}", count()) AS mylist FROM main 
 

Suppose these are the values in the name and city fields: 
 

name 
 

city 
 

date 
 
Claudia 
 
London 
 
2020-04-13 
 
Alex 
 
Berlin 
 
2020-04-19 
 
Wei 
 
Sydney 
 
2020-04-21 
 
Claudia 
 
London 
 
2020-04-30 
 

The results look something like this: 
 

mylist 
 
{"Alex in Berlin":1,"Claudia in London":2,"Wei in Sydney":1} 
 

You can add the flatten command to the search: 
 

SELECT pivot("${name} in ${city}", count()) AS mylist FROM main | flatten mylist 
 

The results look something like this: 
 


Alex in Berlin 
 

Claudia in 
	London 
 


Wei in Sydney 
 


mylist 
 

1 
 

2 
 

1 
 
{"Alex in Berlin":1,"Claudia in London":2,"Wei in 
Sydney":1} 
 

values(<value>) 
 

The values function returns a list of the distinct values in a field as a multivalue entry. 
 

Usage 
 

You can use this function with the stats, streamstats, and timechart commands. 
 

• By default there is no limit to the number of values returned. 
• This function processes field values as strings. 
 

The order of the values is lexicographical. 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

157 
 
• Uppercase letters are sorted before lowercase letters. 
 

after letters. 
 

Example 
 

To illustrate what the values function does, let's start by generating a few simple results. 
 

1. Use the from and streamstats commands to generate a set of 11 results that are simply timestamps and a count�h1h2h3}�h5Kuh�(h3h/�h}�ub�$69532aef-17c8-48a5-825c-a3ec259776ce�h+)�}�(h}�(h/X1. Use the from and streamstats commands to generate a set of 11 results that are simply timestamps and a count 
	of the results, which are used as row numbers. Empty arrays with the from command generate the timestamps. 
 

| from [{},{},{},{},{},{},{},{},{},{},{}] | streamstats count AS rowNumber 
 

There are 11 results. Th first few results look something like this: 
 

_time 
 

rowNumber 
 
2019-10-10T07:19:02.000-07:00 
 
1 
 
2019-10-10T07:19:02.000-07:00 
 
2 
 
2019-10-10T07:19:02.000-07:00 
 
3 
 
2019-10-10T07:19:02.000-07:00 
 
4 
 
2019-10-10T07:19:02.000-07:00 
 
5 
 
Notice that each result appears on a separate row, with a line between each row. 
 


| from [{},{},{},{},{},{},{},{},{},{},{}] | streamstats count AS rowNumber | stats values(rowNumber) 
AS numbers 
 

The results look something like this: 
 

numbers 
 
1 
10 
11 
2 
 
4 
5 
 
7 
8 
9 
 
	Notice that this is a single result with multiple values. There are no lines between each value. 
3. Compare these results with the results returned by the list function. 
 

See also 
 

Function information 
 

SPL2 Stats and Charting Functions Quick Reference 
Naming function arguments in the SPL2 Search Manual 
 

158 
 
Evaluation functions for JSON and multivalue data 
	JSON functions 
 



Time functions 
 
For an overview about the stats and charting functions, see Overview of SPL2 stats functions. 
 

earliest(<value>) 
 

Returns the chronologically earliest seen occurrence of a value in a field. 
 

Usage 
 

You can use this function with the stats and timechart commands. 
 

This function processes field values as strings. 
 

Basic example 
 

You run the following search to locate invalid user login attempts against a specific sshd (Secure Shell Daemon). You use 
the fields command to see the values in the _time, source, and _raw fields. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw 
 

The results look something like this: 
 

_time 
 

source 
 

_raw 
 
29 Apr 2020 
00:15:05 
 

.../mailsv/secure.log�h1h2h3}�h5Kuh�(h3h/�h}�ub�$fb0535cb-11e7-45a8-bcee-42eeb4a26843�h+)�}�(h}�(h/X�The results look something like this: 
 

_time 
 

source 
 

_raw 
 
29 Apr 2020 
00:15:05 
 

.../mailsv/secure.log 
 
Tue Apr 28 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
tomcat from 67.170.226.218 port 1490 ssh2 
 
01 May 2020 
00:15:04 
 

.../www2/secure.log 
 
Fri May 01 2020 00:15:04 www2 sshd[5258]: Failed password for invalid user 
brian from 130.253.37.97 port 4284 ssh2 
 
30 Apr 2020 
00:15:02 
 

.../www3/secure.log 
 
Thu Apr 30 2020 00:15:02 www3 sshd[5258]: Failed password for invalid user 
operator from 222.169.224.226 port 1711 ssh2 
 
28 Apr 2020 
00:15:01 
 

.../www1/secure.log 
 
Tue Apr 28 2020 00:15:01 www1 sshd[5258]: Failed password for invalid user 
rightscale from 87.194.216.51 port 3361 ssh2 
 
01 May 2020 
00:15:05 
 

.../mailsv/secure.log 
 
Fri May 01 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
testuser from 194.8.74.23 port 3626 ssh2 
 
27 Apr 2020 
00:15:01 
 

.../www1/secure.log 
 
Mon Apr 27 2020 00:15:01 www1 sshd[5258]: Failed password for invalid user 
redmine from 91.208.184.24 port 3587 ssh2 
 
You extend the search using the earliest function. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw | stats 
earliest(_raw) 
 

The search returns the event with the _time value 2020-04-27 00:15:01, which is the event with the oldest timestamp. 
 

159 
 
_time 
 
source 
 
_raw 
 
2020-04-27 
00:15:01 
 

.../www1/secure.log 
 
Mon Apr 27 2020 00:15:01 www1 sshd[5258]: Failed password for invalid user 
redmine from 91.208.184.24 port 3587 ssh2 
 
earliest_time(<value>) 
 

Returns the UNIX time of the chronologically earliest-seen occurrence of a given field value. 
 

Usage 
 

You can use this function with the stats and timechart commands. 
 

This function processes field values as strings. 
 

If you have metrics data, you can use the earliest_time function in conjunction with earliest, latest, and latest_time�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2cd78f7c-03a7-4086-863b-ed43515d2038�h+)�}�(h}�(h/XCThis function processes field values as strings. 
 

If you have metrics data, you can use the earliest_time function in conjunction with earliest, latest, and latest_time 
functions to calculate the rate of increase for a counter. Alternatively you can use the rate function counter to do the same 
thing. 
 

Basic example 
 

The following search runs against metric data. It returns the earliest UNIX time values, for every minute, for each 
metric_name that begins with deploy. 
 

| FROM _metrics WHERE earliest_time(_value) metric_name=deploy* span(metric_name, 1m) 
 

The results look something like this: 
 

_time 
 

metric_name 
 

earliest_time(_value) 
 
2018-11-11 18:14:00 
 
deploy-connections.nCurrent 
 
1541988860.000000 
 
2018-11-11 18:14:00 
 
deploy-connections.nStarted 
 
1541988860.000000 
 
2018-11-11 18:14:00 
 
deploy-server.volumeCompletedKB 
 
1541988860.000000 
 
2018-11-11 18:15:00 
 
deploy-connections.nCurrent 
 
1541988922.000000 
 
2018-11-11 18:15:00 
 
deploy-connections.nStarted 
 
1541988922.000000 
 
2018-11-11 18:15:00 
 
deploy-server.volumeCompletedKB 
 
1541988922.000000 
 
latest(<value>) 
 

Returns the chronologically latest seen occurrence of a value in a field. 
 

Usage 
 

You can use this function with the stats and timechart commands. 
 

This function processes field values as strings. 
 






160 
 
Basic example 
 

You run the following search to locate invalid user login attempts against a specific sshd (Secure Shell Daemon). You use 
the fields command to see the values in the _time, source, and _raw fields. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw 
 

The results look something like this: 
 

_time 
 

source 
 

_raw 
 
28 Apr 2020 
00:15:05 
 

.../mailsv/secure.log 
 
Tue Apr 28 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
tomcat from 67.170.226.218 port 1490 ssh2 
 
01 May 2020 
00:15:04 
 

.../www2/secure.log 
 
Fri May 01 2020 00:15:04 www2 sshd[5258]: Failed password for invalid user 
brian from 130.253.37.97 port 4284 ssh2 
 
30 Apr 2020�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0e1d509a-e08a-419d-be29-547683a36d9e�h+)�}�(h}�(h/X01 May 2020 
00:15:04 
 

.../www2/secure.log 
 
Fri May 01 2020 00:15:04 www2 sshd[5258]: Failed password for invalid user 
brian from 130.253.37.97 port 4284 ssh2 
 
30 Apr 2020 
00:15:02 
 

.../www3/secure.log 
 
Thu Apr 30 2020 00:15:02 www3 sshd[5258]: Failed password for invalid user 
operator from 222.169.224.226 port 1711 ssh2 
 
28 Apr 2020 
00:15:01 
 

.../www1/secure.log 
 
Tue Apr 28 2020 00:15:01 www1 sshd[5258]: Failed password for invalid user 
rightscale from 87.194.216.51 port 3361 ssh2 
 
01 May 2020 
00:15:05 
 

.../mailsv/secure.log 
 
Fri May 01 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
testuser from 194.8.74.23 port 3626 ssh2 
 
27 Apr 2020 
00:15:01 
 

.../www1/secure.log 
 
Mon Apr 27 2020 00:15:01 www1 sshd[5258]: Failed password for invalid user 
redmine from 91.208.184.24 port 3587 ssh2 
 
You extend the search using the latest function. 
 

| FROM main WHERE `sourcetype=secure "invalid user" "sshd[5258]"` | fields _time, source, _raw | stats 
latest(_raw) 
 

The search returns the event with the _time value 2020-05-01 00:15:05, which is the event with the most recent 
timestamp. 
 

_time 
 

source 
 

_raw 
 
01 May 2020 
00:15:05 
 

.../mailsv/secure.log 
 
Fri May 01 2020 00:15:05 mailsv1 sshd[5258]: Failed password for invalid user 
testuser from 194.8.74.23 port 3626 ssh2 
 
latest_time(<value>) 
 

Returns the UNIX time of the chronologically latest-seen occurrence of a given field value. 
 

Usage 
 

You can use this function with the stats and timechart commands. 
 

This function processes field values as strings. 
 

If you have metrics data, you can use the latest_time funciton in conjunction with earliest, latest, and earliest_time 
functions to calculate the rate of increase for a counter. Alternatively, you can use the rate function counter to do the 
 



161 
 
Basic example 
 

The following search runs against metric data. It is designed to return the earliest UNIX time values in the past 60 minutes 
for metrics with names that begin with queue..�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6c1436c1-cf9b-44b1-a602-1fe80e210a13�h+)�}�(h}�(h/X:161 
 
Basic example 
 

The following search runs against metric data. It is designed to return the earliest UNIX time values in the past 60 minutes 
for metrics with names that begin with queue.. 
 

select latest(_value), metric_name, _time from metrics where metric_name like "queue.*" group by 
metric_name, span(_time, 1m) 
 

The results look something like this: 
 

_time 
 

metric_name 
 

earliest_time(_value) 
 
2018-11-13 14:43:00 
 
queue.current_size 
 
1542149039.000000 
 
2018-11-13 14:43:00 
 
queue.current_size_kb 
 
1542149039.000000 
 
2018-11-13 14:43:00 
 
queue.largest_size 
 
1542149039.000000 
 
2018-11-13 14:43:00 
 
queue.max_size_kb 
 
1542149039.000000 
 
2018-11-13 14:43:00 
 
queue.smallest_size 
 
1542149039.000000 
 
2018-11-13 14:44:00 
 
queue.current_size 
 
1542149070.000000 
 
2018-11-13 14:44:00 
 
queue.current_size_kb 
 
1542149070.000000 
 
2018-11-13 14:44:00 
 
queue.largest_size 
 
1542149070.000000 
 
2018-11-13 14:44:00 
 
queue.max_size_kb 
 
1542149070.000000 
 
2018-11-13 14:44:00 
 
queue.smallest_size 
 
1542149070.000000 
 
per_day(<value>) 
 

Returns the values in a field or eval expression for each day. 
 

Usage 
 

You can use this function with the timechart command. 
 

Basic examples 
 

The following example returns the values for the total field for each day. 
 

... | timechart per_day(total) 
 


The following example returns the results of the eval expression eval(method="GET")) and labels the field for the 
evaluated results "Views". 
 

... | timechart per_day(eval(method="GET")) AS Views 
 

Extended example 
 

This search uses the per_day() function and eval expressions to determine how many times the web pages were viewed 
and how many times items were purchased. This example should work with any format of Apache Web access log file. 
 


162 
 
| FROM main WHERE sourcetype=access_* | timechart per_day(eval(method="GET")) AS Views_day, 
per_day(eval(action="purchase")) AS Purchases 
 

To determine the number of Views and Purchases for each hour, minute, or second you can add the other time functions�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5094ee6d-c2ec-4f87-b785-2ddf975e6add�h+)�}�(h}�(h/Xper_day(eval(action="purchase")) AS Purchases 
 

To determine the number of Views and Purchases for each hour, minute, or second you can add the other time functions 
to the search. For example: 
 

| FROM main WHERE sourcetype=access_* | timechart per_day(eval(method="GET")) AS Views_day, 
per_hour(eval(method="GET")) AS Views_hour, per_minute(eval(method="GET")) AS Views_minute, 
per_day(eval(action="purchase")) AS Purchases 
 



per_hour(<value>) 
 

Returns the values in a field or eval expression for each hour. 
 

Usage 
 

You can use this function with the timechart command. 
 

Basic examples 
 

The following example returns the values for the field total for each hour. 
 

... | timechart per_hour(total) 
 

The following example returns the results of the eval expression eval(method="POST")) and labels the field for the 
evaluated results Views. 
 

... | timechart per_hour(eval(method="POST")) AS Views 
 

per_minute(<value>) 
 

Returns the values in a field or eval expression for each minute. 
 

Usage 
 

You can use this function with the timechart command. 
 

Basic examples 
 

The following example returns the values for the field total for each minute. 
 

... | timechart per_minute(total) 
 


The following example returns the results of the eval expression eval(method="GET")) and labels the fields for the 
evaluated results "Views". 
 

... | timechart per_minute(eval(method="GET")) AS Views 
 





163 
 
per_second(<value>) 
 

Returns the values in a field or eval expression for each second. 
 

Usage 
 

You can use this function with the timechart command. 
 

Basic examples 
 

The following example returns the values for the field kb for each second. 
 

... | timechart per_second(kb) 
 

rate(<value>) 
 

Returns the per-second rate change of the value in a field. The rate function represents the following formula: 
 


(latest(<value>) - earliest(<value>) / latest_time(<value>) - earliest_time(<value>)) 
 
The rate function also handles the largest value reset if there is at least one reset. 
 

Usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$29159867-a50f-413d-8bb7-957bf0c3df35�h+)�}�(h}�(h/X:(latest(<value>) - earliest(<value>) / latest_time(<value>) - earliest_time(<value>)) 
 
The rate function also handles the largest value reset if there is at least one reset. 
 

Usage 
 

You can use this function with the statscommand. 
 

• Provides the per-second rate change for accumulating counter metrics. Accumulating counters report the total 
	counter value since the last counter reset. 
 

values to be different. 
 

• Should be used to provide rate information about single, rather than multiple, counters. 
 

Basic example 
 

The following search runs against metric data. It provides the hourly hit rate for a metric that provides measurements of 
incoming web traffic. It uses the processor filter to ensure that it is not reporting on multiple metric series (name and 
processor combinations). 
 

| FROM _metrics WHERE name=indexerpipe processor=index_thruput | stats rate(traffic.incoming) AS rate_hits 
span=1h 
 

See also 
 

Function information 
 

SPL2 Stats and Charting Functions Quick Reference 
Naming function arguments in the SPL2 Search Manual 
 






164 
 
Dataset functions 
 


Overview of SPL2 dataset functions 
 
There are two types of dataset functions: 
 

• Generating dataset functions are functions that create events to form a dataset 
• Sink dataset functions are functions that consume events from a dataset 
 

Some dataset functions can be used with any generating command. Other dataset functions are designed to be used only 
with a specific command. 
 

	Dataset 
function 
 


Description 
 

Function 
	type 
 
Use this function to map to the indexes that you have permission to access. 
 
indexes 
 

This function is used with any generating command, such as the from, join, and union 
commands. 
 
generating 
 
Use this function to create events in a temporary dataset. The SPL2 repeat() dataset function is similar 
to the SPL makeresults command. 
 
repeat 
 

This function is used with any generating command, such as the from, join, and union 
commands. 
 
generating 
 
See also 
 

Related information 
 


Function information�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d1a012eb-a978-4365-8815-2dbde12c47ab�h+)�}�(h}�(h/X�repeat 
 

This function is used with any generating command, such as the from, join, and union 
commands. 
 
generating 
 
See also 
 

Related information 
 


Function information 
 

Overview of SPL2 eval functions 
 



indexes dataset function 
 
Use the indexes() function to search event indexes that you have permission to access. 
 

This function can't be used with metric indexes. However, you can use the union command to merge metric and event 
index datasets. See Merge datasets using the union command. 
 

Syntax 
 

The required syntax is in bold. 
 

indexes(<patterns>) 
 


165 
 
Required arguments 
 

The required arguments for the indexes() function depends on the syntax that you use: 
 

Syntax 
 

Description 
 
indexes() 
 
Use this syntax to search your default event indexes, such as main. 
 
indexes('*') 
 
Use this syntax to search all of the event indexes you have access to. This syntax does not return internal indexes. 
 
indexes('_*') 
 
Use this syntax to search all of the internal event indexes you have access to. 
 

indexes(<index-name>...) 
 
Use this syntax to search specific event indexes. You must specify at least one index name. Separate multiple index 
names with commas. You can also name function arguments. See Examples. 
 
Usage 
 

You can use this function with any generating command, such as the from, join, and union commands. 
 

You can use a wildcard to specify similarly named indexes. You must enclose indexes specified with the asterisk wildcard 
in single quotation marks. See Examples. 
 

Examples 
 

These examples show different ways you can use the indexes function to search the event indexes you have access to. 
 

1. Retrieve data from your default indexes 
 

| FROM indexes() 
 

2. Retrieve data from all of the indexes you have access to 
 

When you specify a wildcard, you must enclose the asterisk in single quotation marks. 
 

| FROM indexes('*') 
 

3. Retrieve data from a group of similarly named indexes�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9fd0a29f-0989-4c16-b893-e7999983a207�h+)�}�(h}�(h/X�When you specify a wildcard, you must enclose the asterisk in single quotation marks. 
 

| FROM indexes('*') 
 

3. Retrieve data from a group of similarly named indexes 
 

When you specify a set of indexes using a wildcard, you must enclose the name and wildcard in single quotation marks. 
 

| FROM indexes('data*') 
 

4. Naming function arguments 
 

Naming arguments is optional. In the following example, the argument name patterns is used before the group of 
similarly named indexes 'data1*' and 'data2*' . When you specify multiple patterns, you must enclose the list of 
patterns in square brackets and separate the the items with commas. 
 

| FROM indexes(patterns: ['data1*', 'data2*']) 
 

5. Merge datasets using the union command 
 

Use the union command to merge the results from multiple datasets. By default the union command interleaves the 
results in descending time order. 
 


166 
 
| union indexes(webtraffic, 'webdata*') 
 

This search merges the results from these indexes: 
 

• The index webtraffic 
 


You can't use the indexes function with indexes that have a dataset kind of metrics. You must specify metrics indexes 
separately from event indexes. For example: 
 

| union indexes(webtraffic, 'webdata*'), metrics: "webmetrics" 
 

This search merges the results from these indexes: 
 

• The index webtraffic 
 

• The metrics index webmetrics 
 

6. Combine datasets using the join command 
 

Use the join command to combine the results from multiple datasets. 
 

This search joins the logons index with all of the indexes that start with logonData. This search uses an inner join. The 
indexes are joined on the id field. 
 

| FROM logons | join type=inner max=0 left=L right=R where L.id=R.id indexes('logonData*') 
 

See also 
 

Function information 
 

Naming function arguments in the SPL2 Search Manual 
 


repeat dataset function 
 
Use the repeat() function to create events in a temporary dataset. The repeat() function is often used to create events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$45cf584a-f90e-4a57-bccb-3e0f374d4708�h+)�}�(h}�(h/XNaming function arguments in the SPL2 Search Manual 
 


repeat dataset function 
 
Use the repeat() function to create events in a temporary dataset. The repeat() function is often used to create events 
for testing. You can use the repeat function anywhere you can specify a dataset name, for example with the FROM, union, 
and join commands. 
 

The SPL2 repeat() dataset function is similar to the makeresults command in SPL. 
 

Syntax 
 

The required syntax is in bold. 
 

repeat (<template>, <count>) 
 

The arguments must be enclosed in parentheses ( ). 
 




167 
 
Required arguments 
 

template 
 

Description: Either an empty object { } or a single JSON object, in the format {field: value}. Field names that 
contain characters other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in single quotation 
marks. This includes field names with spaces. String values must be enclosed in double quotation marks. 
 

count 
 


Syntax: <integer> 
 


Optional arguments 
 

None 
 

Usage 
 

The repeat() function is a generating function. Generating functions are functions that create events to form a dataset. 
 

There are some limitations using the repeat function: 
 

• You can't specify nested JSON objects with the repeat dataset function. 
 

pairs. 
 

Should I use the repeat function or a dataset literal? 
 

The repeat function is a very useful method to create a temporary dataset in certain circumstances. An alternative to the 
repeat function is to use a dataset literal. See Dataset literals in the SPL2 Search Manual. 
 

The following table describes the usage differences and limitations between the repeat function and a dataset literal: 
 

Method 
 

Usage 
 

Limitations 
 

repeat 
function 
 
Use the repeat function when you want to create multiple identical, or 
nearly identical events, where only a few values are different. You can use 
the repeat function to create a lot of events quickly. 
 

You can't use nested objects or an array of objects 
with the repeat function. 
 

dataset 
literal�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c10414ff-ea97-4910-b800-41d40dfff807�h+)�}�(h}�(h/X*the repeat function to create a lot of events quickly. 
 

You can't use nested objects or an array of objects 
with the repeat function. 
 

dataset 
literal 
 

Use a dataset literal when you want to create events with many different 
values. You can use nested objects and arrays in a dataset literal. 
 
Manually typing in each of the objects is 
time-consuming. See Sample dataset literals in the 
SPL2 Search Manual. 
 
Examples 
 

These examples show different ways to use the repeat function to create events. 
 

1. Create a dataset with empty events 
 

You can create a dataset of empty events. For example, to create a dataset with 5 events use this search: 
 

FROM repeat({}, 5) 
 

To add a timestamp to the events, use the eval command: 
 

168 
 
from repeat({},5) | eval _time = now() 
 

The results look something like this: 
 

_time 
 
25 Feb 2022 15:35:14 
 
25 Feb 2022 15:35:14 
 
25 Feb 2022 15:35:14 
 
25 Feb 2022 15:35:14 
 
25 Feb 2022 15:35:14 
 
Each event has the exact same timestamp. 
 

2. Create events with hourly or daily timestamps 
 

There are many things you can do to extend the events you create. 
 

For example, you can create a set of hourly timestamps instead of events with the exact same timestamp. Add the 
streamstats command to create a count of the events. Use the eval command to create incremental timestamps by 
multiplying the count by 3600, the number of seconds in an hour. 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*3600) 
 

The results look something like this: 
 

_time 
 

count 
 
25 Feb 2022 15:35:14 
 
1 
 
25 Feb 2022 14:35:14 
 
2 
 
25 Feb 2022 13:35:14 
 
3 
 
25 Feb 2022 12:35:14 
 
4 
 
25 Feb 2022 11:35:14 
 
5 
 
The hours in the timestamp are 1 hour apart, starting with the latest timestamp and ending with the earliest timestamp. 
 

To create daily timestamps, use 86400, the number of seconds in a day, in the eval command. 
 

3. Create events with a field-value object 
 

You can specify a JSON object to create a field in the events in the dataset.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4a3edc50-ded2-47b7-8bce-478d9176dd10�h+)�}�(h}�(h/X3. Create events with a field-value object 
 

You can specify a JSON object to create a field in the events in the dataset. 
 

| from repeat({'city-name': "San Francisco"},2) 
 

Because the field city-name contains a dash ( - ), the name must be enclosed in single quotation marks. The value San 
Francisco is a string, which must be enclosed in double quotation marks. 
 

The results look something like this: 
 

city-name 
 

169 
 
San Francisco 
 
San Francisco 
 
4. Create events with multiple fields 
 

This example shows how to specify multiple key-value pairs in a JSON object, which results in multiple, duplicate fields in 
each event in the dataset. 
 

| from repeat({host: "www1", sourcetype: "access_combined"},3) | eval _time = now() 
 

The results look something like this: 
 

_time 
 

host 
 

sourcetype 
 
25 Feb 2022 14:35:58.000 PM 
 
www1 
 
access_combined 
 
25 Feb 2022 14:35:58.000 PM 
 
www1 
 
access_combined 
 
25 Feb 2022 14:35:58.000 PM 
 
www1 
 
access_combined 
 
You can alter the duplicate events by adding the streamstats command to create a count of the events. Use the eval 
command to alter an event by the count number. 
 

For example, this search alters the value of the host field for the second event: 
 

| from repeat({host: "www1", sourcetype: "access_combined_wcookie"},3) | eval _time = now() | streamstats 
count() | eval host = if(count=2, "www2", host) 
 

The results look something like this: 
 

_time 
 

host 
 

sourcetype 
 

count 
 
25 Feb 2022 14:35:58.000 PM 
 
www1 
 
access_combined 
 
1 
 
25 Feb 2022 14:35:58.000 PM 
 
www2 
 
access_combined 
 
2 
 
25 Feb 2022 14:35:58.000 PM 
 
www1 
 
access_combined 
 
3 
 
See also 
 

Function information 
 

Naming function arguments in the SPL2 Search Manual 
 

Related information 
 

from command overview 
streamstats command overview 
 









170 
 
Custom functions and data types 
 


Custom eval functions 
 
You can create your own custom eval functions to extend SPL2. Custom functions are user-defined functions that you�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2ecae08f-5476-484f-a463-799bb52eca05�h+)�}�(h}�(h/X�170 
 
Custom functions and data types 
 


Custom eval functions 
 
You can create your own custom eval functions to extend SPL2. Custom functions are user-defined functions that you 
declare in an SPL2 module. Custom functions have zero or more parameters and return a single value. 
 

You can use custom functions in the WHERE clause of the from command and in the eval and where commands. 
 

Custom functions provide a structured way to share and reuse blocks of SPL2. Custom functions are similar to macros, 
but they have more capabilities than macros, such as data type checking and advanced optimizations. 
 

For information about the built-in eval functions, see SPL2 eval functions Quick Reference. 
 

Custom eval function syntax 
 

The required syntax is in bold. 
 

function <function-name> 
 

{ 


} 
 


[ <SPL-statement>... ] 
return <expression> 
 

The parenthesis are required, even if a <function-parameter> isn't specified. 
 

The curly braces { } are required, even if a <SPL-statement> isn't specified. 
 

Required arguments 
 

function-name 
 

Description: The word function followed by the name that you want to give to the function. Function names 
must start with a letter or underscore ( _ ) character and cannot contain spaces. 
 

expression 
 

Description: The word return followed by the expression that you want returned from the function. Expressions 
can be composed of literals, functions, fields, parameters, comparisons, and other expressions. See Types of 
expressions in the SPL2 Search Manual. 
 

Optional arguments 
 

parameter-name 
 

Description: The name that you want to give to a parameter that you want to use with a custom function. You 
can specify zero or more parameters. Separate multiple parameters with commas. Parameter names must start 
 



171 
 
specify a parameter name, you have the option to include a parameter type. The default parameter type is any. 
Example: ($firstname, $surname: string) 
 


parameter-type�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8e1f4103-80a3-49ab-a969-a42c9e96b020�h+)�}�(h}�(h/X?171 
 
specify a parameter name, you have the option to include a parameter type. The default parameter type is any. 
Example: ($firstname, $surname: string) 
 


parameter-type 
 

Description: The data type that the parameter accepts. This is the input data type. The default data type is any. 
See Built-in data types. If you specify a parameter type, you must separate the <parameter-name> and the 
<parameter-type> with a colon ( : ). 
 

Default: any 
 

default-value 
 

Description: A default value for the parameter. The value must be a constant, either a literal or a string. The 
value can't be a field name. Users can override the default value by specifying the parameter with a value. 
Example: ($count: int=5) 
 


function-type 
 

Description: The data type that the function returns. This is the output data type. The default data type is any. 
See Built-in data types. 
 


SPL-statement 
 

Description: One or more SPL2 statements to include in your custom function. See Examples. 
Default: None 
 

Using custom eval functions 
 

Consider this custom eval function example: 
 


function hello ($fullname: string): string { 
 

} 
 
The following table describes each part of this function example: 
 

Syntax 
 

Example 
 

Description 
 
function <function_name> 
 
function hello 
 
The name of the function is hello. 
 
One parameter is defined, with the name fullname. 
 
$<parameter-name>: 
<parameter-type> 
 

$fullname: string 
 

The value that you specify for the parameter must be an expression 
that resolves to a string, such as a field that contains string values or 
a string literal. 
 
<function-type> 
 
string 
 
The function returns a string. 
 
{ 
 
{ 
 
There is no SPL-statement. The expression returned is the string Howdy , a space, 
and the value specified for the parameter $fullname. 
 

172 
 
Syntax 
 
Example 
 
Description 
 
<SPL-statements> return 
<expression> 
 
return "Howdy" + " 
" + $fullname 
 

Using functions in modules 
 

You create custom eval functions in an SPL2 module. You can use a custom function multiple times within that module.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$819649b5-e4d9-4c20-ae41-e72fb4302353�h+)�}�(h}�(h/X!<expression> 
 
return "Howdy" + " 
" + $fullname 
 

Using functions in modules 
 

You create custom eval functions in an SPL2 module. You can use a custom function multiple times within that module. 
Custom functions can also be imported into other modules. 
 

Using functions in the API 
 

You can also create custom functions using the Search Service API. 
 

Supported function types 
 

When you create a custom eval function, you have the option to specify the data type for the function or the function 
parameters. The built-in data types include strings, numbers, Booleans, arrays, objects, and times. 
 

If you don't specify a data type, the default data type any is used. 
 

The dataset data type isn't applicable to custom eval functions. You use the dataset data type with a custom command 
function. See Custom command functions. 
 

To learn more about the supported data types, see Built-in data types in the SPL2 Search Reference. 
 

Testing custom functions 
 

Testing custom functions makes it easier to verify that the function works as you intend. 
 

You can test custom functions in isolation, without impacting other SPL2 statements, by using dataset literals. There are 
multiple sample dataset literals that you can use to test your functions. See Sample dataset literals in the SPL2 Search 
Manual. 
 

Consider the following dataset: 
 

name 
 

age 
 

city 
 
Wei Zhang 
 
39 
 
Seattle 
 
Rutherford Sullivan 
 
57 
 
Dublin 
 
Vanya Patel 
 
47 
 
Bangalore 
 
This dataset will be used to test the following function. This function, called hello, returns the string "Howdy", followed by 
a space and the values from the expression specified for the fullname parameter. 
 


function hello ($fullname: string): string { 
 

} 
 
The number of events in the dataset literal that you use for testing depends on how complex your function is. In simple 
examples, you could use one event. This example uses three. 
 


173 
 
This example invokes the function by using the eval command. This example creates a new field called greeting to store�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d4447118-5778-4b8c-afb2-706187d481c0�h+)�}�(h}�(h/XAexamples, you could use one event. This example uses three. 
 


173 
 
This example invokes the function by using the eval command. This example creates a new field called greeting to store 
the results of the function: 
 

$search = | from [ {name: "Wei Zhang", age: 39, city: "Seattle"}, {name: "Rutherford Sullivan", age:57, 
city: "Dublin"}, {name: "Vanya Patel", age: 47, city: "Bangalore"}] | eval greeting = hello(name) 
 


These are results of invoking this function: 
 

name 
 

age 
 

city 
 

greeting 
 
Wei Zhang 
 
39 
 
Seattle 
 
Howdy Wei Zhang 
 
Rutherford Sullivan 
 
57 
 
Dublin 
 
Howdy Rutherford Sullivan 
 
Vanya Patel 
 
47 
 
Bangalore 
 
Howdy Vanya Patel 
 
Examples 
 

1. A function with a simple return expression 
 

This example shows how to use a custom function with a simple expression. 
 

This example returns error codes that are greater than or equal to 400. The custom function is called isError and returns 
a Boolean value. A parameter is defined, called $code, which has an input data type of number. There is no SPL statement 
in this example. The expression for this function returns results only when the value of the $code parameter is greater than 
or equal to 400. 
 


function isError($code : number) : boolean { 
 

} 
 
This example invokes the function in the WHERE clause of the from command: 
 

| FROM jsondata WHERE method="GET" AND isError(status_code) 
 

In this example, the isError function is used as a filter in the WHERE clause of a from command. The status_code field is 
the value used for the $code parameter. 
 

As the events from the jsondata dataset are read, the events are filtered by the WHERE clause. Only the events that 
have a method field with a value of GET and have an error status code of 400 or greater are returned. 
 

Suppose the following events are in the jsondata dataset: 
 

_time 
 

method 
 

status_code 
 
22 Mar 2022 12:00:00 PM 
 
PUT 
 
200 
 
22 Mar 2022 11:45:00 AM 
 
GET 
 
400 
 
22 Mar 2022 11:13:00 AM 
 
GET 
 
200 
 
22 Mar 2022 10:59:00 AM 
 
POST 
 
408 
 
22 Mar 2022 10:38:00 AM 
 
GET 
 
404�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ffccdc31-8ade-4f23-9bb8-569421e0ff5a�h+)�}�(h}�(h/X�method 
 

status_code 
 
22 Mar 2022 12:00:00 PM 
 
PUT 
 
200 
 
22 Mar 2022 11:45:00 AM 
 
GET 
 
400 
 
22 Mar 2022 11:13:00 AM 
 
GET 
 
200 
 
22 Mar 2022 10:59:00 AM 
 
POST 
 
408 
 
22 Mar 2022 10:38:00 AM 
 
GET 
 
404 
 
When the search is run with the custom eval function, the following results are returned: 
 


174 
 
_time 
 
method 
 
status_code 
 
22 Mar 2022 11:45:00 AM 
 
GET 
 
400 
 
22 Mar 2022 10:38:00 AM 
 
GET 
 
404 
 
2. Using and overriding a default value 
 

This example shows how to specify a default value in a custom function and override that default value. 
 

Suppose you want to create a custom function that combines the built-in if and round functions. You want to take the 
values in a field and round the values to a specific number of decimal points, but only if the number is greater than 1. 
 

Start by creating some sample data. You can use a dataset literal like this: 
 


$sample = FROM [{score: 2.345678},{score: 0.1234},{score: 1.0076543}] 
 
Next, combine the functions that you want to use explicitly. For example, if you want to apply the function to the score 
field, this would be the function expression: 
 


if(score>1, round(score, 2), score) 
 
Then test your explicit function expression against the sample data: 
 


$function_test1 = FROM $sample SELECT score, if(score>1, round(score, 2), score)  AS newscore 
 
You can convert the explicit function expression into a custom function, which includes a default value for $precision: 
 


function roundIf($field:int, $precision:number=2): int { 
 

} 
 
Now you're ready to test the function. Notice this search doesn't specify a precision. It uses the default $precision in the 
function. 
 


$function_test2 = FROM $sample SELECT score, roundIf(score) AS newscore 
 
You can override the default $precision by specifying a different precision in your search. For example: 
 


$function_test2 = FROM $sample SELECT score, roundIf(score, 4) AS newscore 
 
3. Reusing a custom function�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c07e9fa3-c0f7-4695-b5c8-245242e2d0ad�h+)�}�(h}�(h/X$function_test2 = FROM $sample SELECT score, roundIf(score, 4) AS newscore 
 
3. Reusing a custom function 
 

You can use your custom eval functions in multiple searches within the same SPL module. To use a custom function in 
another SPL module, you must export the custom function. 
 

This custom function, isError, is identical to the custom function described in the previous example. 
 

This custom function is used in three different searches: 
 


function isError($code : number) : boolean { 
 

} 
 

| FROM jsondata WHERE method="GET" AND isError(status_code) 
 

175 
 
| FROM jsondata WHERE isError(status_code) 
 


| FROM main WHERE isError(status_code) 
 

| eval 'First Instance'=strftime('First Instance', "%Y-%m-%d %H:%M:%S") 
 

First search 
 

This search returns events where the method is GET and the values in the status_code field are equal to or greater than 
400: 
 

| FROM jsondata WHERE method="GET" AND isError(status_code) 
 

Second search 
 

This search returns events where the values in the status_code field are equal to or greater than 400. The search then 
counts the values in the method field and organizes the results by the values in the status_code field and the method field. 
 

| FROM jsondata WHERE isError(status_code) | stats count(method) BY status_code, method 
 

The results look something like this: 
 

status_code 
 

method 
 

count(method) 
 
400 
 
GET 
 
1 
 
404 
 
GET 
 
1 
 
408 
 
POST 
 
1 
 
Third search 
 

This search returns events from a different dataset where the values in the status_code field are equal to or greater than 
400. The search returns the time from the earliest event in the search results, which is the first occurrence of the 4xx 
status codes for the time range specified. The field returned is renamed First Instance. Because the earliest_time 
function returns a UNIX time, the strftime eval function is used to change the time into a human-readable time format. 
 

| FROM main WHERE isError(status_code) |stats (earliest_time(_time)) AS 'First Instance' |eval 'First�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3785b28a-08de-4fb5-a8e8-6680131dd5f7�h+)�}�(h}�(h/X�| FROM main WHERE isError(status_code) |stats (earliest_time(_time)) AS 'First Instance' |eval 'First 
Instance'=strftime('First Instance', "%Y-%m-%d %H:%M:%S") 
 

The results look something like this: 
 

First instance 
 
2022/03/22 10:38 
 


See also 
 

Functions 
 

SPL2 eval functions Quick Reference 
Documenting custom functions 
 


176 
 
Naming function arguments in the SPL2 Search Manual 
 

Related information 
 



Custom command functions 
 
You can create a custom SPL2 command by declaring a custom command function. A custom command function is a 
function that performs like a command. There are two types of custom command functions: 
 

• A generating command function creates a set of events and is used as the first command in a search. Examples 
	of built-in generating commands are from, union, and search. 
 

• A non-generating command function processes data that is piped in from generating commands or other 
	non-generating commands. Examples of built-in non-generating commands are stats, eval, and sort. 
 

Custom command function syntax 
 

The required syntax is in bold. 
 

function <function-name> 
 

{ 


} 
 


[ <SPL-statement>... ] 
return | <search> 
 

The parenthesis ( ) are required, even if a <function-parameter> is not specified. 
 

The curly braces { } are required, even if a <SPL-statement> is not specified. 
 

Required arguments 
 

function-name 
 

Description: The word function followed by the name that you want to give to the function. Function names 
must start with a letter or underscore ( _ ) character and can't contain spaces. 
 

search 
 


Syntax: return | <search> 
 


Optional arguments 
 

parameter-name 
 

Description: The name that you want to give to a parameter that you want to use with a custom function. You 
can specify zero or more parameters. Separate multiple parameters with commas. Parameter names must start 
 

specify a function parameter, you have the option to include a parameter type. The default parameter type is any. 
 

177�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2a5f179c-f027-4ff5-a17c-db0cc2f07bec�h+)�}�(h}�(h/X�specify a function parameter, you have the option to include a parameter type. The default parameter type is any. 
 

177 
 
Non-generating command functions: One function parameter must be specified to identify the dataset that the 
custom command function uses. The name $source is often used for this function parameter. 
 

Default: None 
 

parameter-type 
 

Description: The data type that the parameter accepts. This is the input data type. The default data type is any. 
See Built-in data types. If you specify a parameter type, you must separate the <parameter-name> and the 
<parameter-type> with a colon ( : ). 
 

Default: any 
 

default-value 
 

Description: A default value for the parameter. The value must be a constant, either a literal or a string. The 
value can't be a field name. Users can override the default value by specifying the function parameter with a 
value. 
 

Default: None 
 

function-type 
 

Description: The data type that the function returns. This is the output data type. The default data type is any. 
See Built-in data types. 
 

results dataset. 
 

Advantages of custom command functions 
 

There are many advantages to using custom command functions. 
 

Reusing parts of a search 
 

You can use custom command functions to reuse parts of a search. For example, you might need to perform a complex 
stats aggregation, or an intricate filtering or formatting in multiple searches. You can create a single custom function to 
perform those actions. You can then use that function in as many searches as you want. To change the actions 
performed, you only need to change the function to propagate the changes to all of the searches that use the function. 
 

For an example of a custom command function that automates parts of a search, see Testing custom functions. 
 

You can also use a custom command function to store a sample set of events, which is called a dataset literal. To see an 
example, see Examples. 
 

Simplifying search readability�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1a72fd1c-819d-4715-a465-b58956920bf9�h+)�}�(h}�(h/X�You can also use a custom command function to store a sample set of events, which is called a dataset literal. To see an 
example, see Examples. 
 

Simplifying search readability 
 

You can use custom command functions to simplify your SPL2 by turning a section of SPL2 that might be difficult to parse 
into something more readable. 
 

For example, suppose you have a search that has a lengthy section devoted to formatting the search results. Instead of 
exposing all of those lines in your search, you can create a function called tidy_data that hides the tedious formatting 
 


178 
 
section, making the search easier to read. 
 

It's a good practice to add a comment to your search to explain what the function does: 
 

... | tidy_data // This is a function that formats the results. ... 
 

This example uses a line comment to describe the function. For more information about line comments and block 
comments, see Using comments in SPL2 in the SPL2 Search Manual. 
 

Generating events to test searches 
 

It's convenient to automate the creation of a set of events using a generating command function. The events become a 
temporary dataset that you can then use to test your searches. In SPL2, there is no command that generates a set of 
events. However, you can use either the SPL2 repeat dataset function or a dataset literal to create a set of events in a 
temporary dataset. See Examples. 
 

How to use custom command functions 
 

When you create a custom command function that is a non-generating command, you must specify at least one function 
parameter that is used to identify the dataset that the command operates on. See Examples. 
 

How to invoke a function 
 

When you use a custom command function, you don't specify the $ prefix when you specify the parameter values. For 
example, suppose you have this makeresults command function to create a set of events: 
 


function makeresults($count) { 
 

               | eval _time = now() 
}�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6d980293-7f3b-40cf-a670-39313d528234�h+)�}�(h}�(h/X�example, suppose you have this makeresults command function to create a set of events: 
 


function makeresults($count) { 
 

               | eval _time = now() 
} 
 
To invoke the generating makeresults function, specify the name of the function and the value for the $count parameter: 
 

| makeresults 5 
 

Similarly with non-generating command functions, you invoke the function after you specify the dataset. Consider this 
function: 
 


function my_sourcetype($source, $field, $sourcetype: string="webaccess") { 
 

                FROM $source 
 

                GROUP BY $field, _time 
} 
 
To invoke the function, specify the dataset and the field. For example, to use this function on the host field in the main 
dataset you specify this search: 
 

FROM main | my_sourcetype host 
 

Overriding parameter default values 
 

To override the default value for a parameter, you specify the value you want to use in the search. For example, this 
function has a default value for $sourcetype: 
 

179 
 
function my_sourcetype($source, $field, $sourcetype: string="webaccess") { 
 

                FROM $source 
 

                GROUP BY $field 
} 
 
To override the function default for sourcetype with httpevent, specify the value in the search. Because the sourcetype is 
a string, it must be enclosed in double quotations: 
 

FROM main | my_sourcetype host "httpevent" 
 

Function parameters must be specified in your search in a particular order, unless you name the parameters. 
 

Parameter order and named arguments 
 

Consider the following function.. This function has six parameters, three of which are strings: 
 


function my_sourcetype($source, $field, $sourcetype:string $status:int, $action:string, $categoryId:string) 
{ 
 

      FROM $source 
 

      GROUP BY $field 
} 
 
When you invoke a function, you must specify the parameter values in the order in which the parameters appear in the 
function syntax. For example: 
 

FROM main | my_sourcetype host "webaccess" 200 "purchase" "simulation"�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a03911f7-75bc-4559-9568-96d147fdf3f9�h+)�}�(h}�(h/Xfunction syntax. For example: 
 

FROM main | my_sourcetype host "webaccess" 200 "purchase" "simulation" 
 

Unless you know the function well, it's difficult to know which value equates to each parameter. 
 

To clarify this, you can name the parameters in your search. For example: 
 

FROM main | my_sourcetype field=host sourcetype="webaccess" status=200 action="purchase" 
categoryId="simulation" 
 

Another advantage of naming the parameters is that you can specify the parameters in any order. For example: 
 

FROM main | my_sourcetype field=host status=200 categoryId="simulation" action="purchase" 
sourcetype="webaccess" 
 

Using functions in modules 
 

You create custom command functions in an SPL2 module. You can use a custom command function multiple times 
within that module. You can also import custom command functions into other modules. 
 

Using functions in the API 
 

You can also create and use custom command functions using the Search Service API. 
 






180 
 
Supported data types 
 

When you create a custom command function, you have the option to specify the data type for the function or the function 
parameters. 
 

The default data type for command functions is dataset. The default data type for function parameters is any. 
 

To learn more about the supported data types, see Built-in data types. 
 

Testing custom functions 
 

Test your custom functions to verify that the function works as you intend. 
 

You can test custom functions in isolation, without impacting other SPL2 statements, by using a dataset literal. A dataset 
literal is a dataset that you type into your search. A dataset literal consists of an array of objects consisting of field value 
pairs. For more information about dataset literals, see Dataset literals in the SPL2 Search Manual. 
 

The following is an example of a custom function that is used to automate almost all of a complex search. Because the 
search is run on a regular basis against different datasets and different fields using similar criteria, it is more efficient to�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e7ffc82e-faa4-40c3-9287-00fcc7f29cf9�h+)�}�(h}�(h/Xosearch is run on a regular basis against different datasets and different fields using similar criteria, it is more efficient to 
create a custom function for that search. Several of the parameters have default values, which can be overridden. 
 


function my_sourcetype($source, $field, $sourcetype: string="webaccess", $time: timespan=5m, $count: int=10) 
{ 
 

                FROM $source 
 

                GROUP BY $field, span(_time, $time) 
 

To invoke the function, you specify the dataset and the field. For example, to use this function on the host field in the main 
dataset you specify this search: 
 

FROM main | my_sourcetype host 
 

To test this function, substitute a dataset literal for the main dataset. 
 

Suppose these are some of the events in your dataset: 
 

_time 
 

host 
 

sourcetype 
 

action 
 

productId 
 

method 
 
6 Apr 2022 9:39:48 PM 
 
www2 
 
access_combined 
 
purchase 
 
PZ-SG-G05 
 
POST 
 
6 Apr 2022 9:34:10 PM 
 
www1 
 
webaccess 
 
view 
 
GET 
 
6 Apr 2022 9:34:02 PM 
 
www3 
 
webaccess 
 
purchase 
 
SC-MG-G10 
 
POST 
 
6 Apr 2022 9:34:01 PM 
 
www2 
 
access_combined 
 
remove 
 
CU-PG-G06 
 
GET 
 
6 Apr 2022 9:34:01 PM 
 
www1 
 
webaccess 
 
purchase 
 
POST 
 
6 Apr 2022 9:29:55 PM 
 
www3 
 
access_combined 
 
addtocart 
 
SC-MG-G10 
 
GET 
 
6 Apr 2022 9:20:51 PM 
 
www1 
 
access_combined 
 
addtocart 
 
DB-SG-G01 
 
GET 
 
6 Apr 2022 9:12:56 PM 
 
www2 
 
webaccess 
 
changequantity 
 
FS-SG-G03 
 
GET 
 
6 Apr 2022 9:12:53 PM 
 
www1 
 
access_combined 
 
DB-SG-G01 
 
GET 
 


181 
 
_time 
 
host 
 
sourcetype 
 
action 
 
productId 
 
method 
 

You could select several events as the basis for your dataset literal. In this example, the first four events are used for the 
dataset literal: 
 


[{_time: 6 Apr 2022 9:39:48, host:"www2", sourcetype:"access_combined", action:"purchase", 
productId:"PZ-SG-G05", method:"POST"}, 
 

{_time: 6 Apr 2022 9:34:02, host:"www3", sourcetype:"webaccess", action:"purchase", productId:"SC-MG-G10", 
method:"POST"}, 
 

productId:"CU-PG-G06", method:"GET"}] 
 
Here's how the function is invoked in a search using the dataset literal:�V
h1h2h3}�h5Kuh�(h3h/�h}�ub�$e757ecf4-a03f-4ccf-9323-e9d07990fd77�h+)�}�(h}�(h/X�method:"POST"}, 
 

productId:"CU-PG-G06", method:"GET"}] 
 
Here's how the function is invoked in a search using the dataset literal: 
 

FROM [ {_time: 6 Apr 2022 9:39:48, host:"www2", sourcetype:"access_combined", action:"purchase", 
productId:"PZ-SG-G05", method:"POST"}, {_time: 6 Apr 2022 9:34:10, host:"www1", sourcetype:"webaccess", 
action:"view", productId:"", method:"GET"}, {_time: 6 Apr 2022 9:34:02, host:"www3", sourcetype:"webaccess", 
action:"purchase", productId:"SC-MG-G10", method:"POST"}, {_time: 6 Apr 20229:34:01, host:"www2", 
 


You might need to adjust some of the values in the dataset literal to perform a complete test. 
 

Examples 
 

1. Create a non-generating function 
 

When you create a custom function that is a non-generating command, you must specify at least one function parameter 
that identifies the dataset that the command operates on. 
 

In SPL2 there is no command that returns the most common values for a field in a dataset. However, you can define a 
custom function that processes the events in a dataset and returns the top-most values in a specific field. 
 

For example: 
 


function top($source, $field, $limit: int) { 
 

        | stats count() by $field 
 

        | head $limit 
} 
 

• The function, top, defines three parameters. 
 

• The $field parameter is used in the stats command. The stats command counts the events and organizes the 
	count by the values in the $field. 
 

• The $limit parameter specifies the maximum number of results to return. The value specified for $limit must be 
	an integer. The head command returns the top values in the results returned from the sort command up to the 
	maximum number allowed by the $limit parameter. 
 

• 
 


182 
 
Here's an example of how the top command function is invoked to return values from the host field and limits the values 
to 5: 
 

| FROM main | top host 5 
 

Internally, this search is expanded to this: 
 

FROM main | stats count() by host | sort -count | head 5�h1h2h3}�h5Kuh�(h3h/�h}�ub�$98725cd6-8525-4318-999a-375c42fedca3�h+)�}�(h}�(h/Xto 5: 
 

| FROM main | top host 5 
 

Internally, this search is expanded to this: 
 

FROM main | stats count() by host | sort -count | head 5 
 

For another example of a non-generating function, see Testing custom functions. 
 

2. Specify a default value for a function parameter 
 

You can add a default value to a function parameter. The default value is used when the function is run, unless you 
override the value. 
 

The previous example defines a custom function, top, that processes the events in a dataset and returns the top-most 
values in a field. Here is the top function: 
 


function top($source, $field, $limit: int) { 
 

        | stats count() by $field 
 

        | head $limit 
} 
 
You can specify a default value to use for the $limit parameter. In this example, 8 is the default value: 
 


function top($source, $field, $limit: int=8) { 
 

        | stats count() by $field 
 

        | head $limit 
} 
 
When you invoke the top function now, you only need to specify the $field parameter in your search. In this example, 
host is the field parameter: 
 

| FROM main | top host 
 

Because there is a default value for $limit, the 8 top-most values are returned. 
 

You can override the default value by specifying the $limit in your search. This example returns 12 values from the host 
field: 
 

| FROM main | top host 12 
 

3. Create a generating function using the repeat function 
 

This example shows you how to create a custom command function that generates events using the repeat dataset 
function. 
 

Start with a simple command function that uses the repeat dataset function: 
 



183 
 
function makeresults($count) { 
 

 | eval _time = now() 
 

 | eval _time=_time-(count*3600); 
} 
 

• The name of the function is makeresults. 
 

• The repeat function creates multiple identical events. The first eval command is used to add the _time field, 
	which contains the timestamp when the event is created. 
 

• The second eval command is used to convert the timestamps into incremental timestamps, by multiplying the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$479504ff-fac9-4781-9649-4af88bef296b�h+)�}�(h}�(h/XXwhich contains the timestamp when the event is created. 
 

• The second eval command is used to convert the timestamps into incremental timestamps, by multiplying the 
	count by 3600, the number of seconds in an hour. That number is subtracted from the time to create the 
	incremental timestamps. 
 

To invoke the makeresults function and create 5 events, use this search: 
 

| makeresults 5 
 

The timestamps are one hour apart, starting with the latest timestamp and ending with the earliest timestamp. 
 

The results look something like this: 
 

_time 
 

count 
 
20 Apr 2022 2:35:58 PM 
 
1 
 
20 Apr 2022 1:35:58 PM 
 
2 
 
20 Apr 2022 12:35:58 PM 
 
3 
 
20 Apr 2022 11:35:58 AM 
 
4 
 
20 Apr 2022 10:35:58 AM 
 
5 
 
Alternatively, you can specify multiple key-value pairs in an object format to create multiple, duplicate fields in each event. 
 


function makeresults($count) { 
 

 | eval _time = now(); 
} 
 
When you invoke the makeresults function with a count of 3, the results look something like this: 
 

_raw 
 

_time 
 

host 
 

sourcetype 
 
{"host': "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1 
 
access_combined 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1 
 
access_combined 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1 
 
access_combined 
 
You can alter the duplicate events by adding the streamstats command to create a count of the events. Use the eval 
command to alter an event by the count number. 
 

For example: 
 


184 
 
function makeresults($count) { 
 

 | eval _time = now() 
 

 | eval host = if(count=2, "www2", host); 
} 
 
When you invoke the makeresults function, the results look something like this: 
 

_raw 
 

_time 
 

host 
 

sourcetype 
 

count 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1 
 
access_combined 
 
1 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www2 
 
access_combined 
 
2 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1�h1h2h3}�h5Kuh�(h3h/�h}�ub�$391f8a8b-7cb9-4a4d-a1a8-5c4a05e49e58�h+)�}�(h}�(h/X)1 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www2 
 
access_combined 
 
2 
 
{"host": "www1", "sourcetype": "access_combined"} 
 
20 Apr 2022 2:35:58 PM 
 
www1 
 
access_combined 
 
3 
 
If you want to create multiple events with different field values use a dataset literal instead. See the next example. 
 

4. Create a generating custom command using a dataset literal 
 

This example shows you how to create a custom command function that generates events using a dataset literal. 
 

This dataset literal contains a set of objects with key-value pairs with the type and name for cooperative and competitive 
board games: 
 


[ 
 

   {"type": "cooperative", "name": "Pandemic"}, 
 

   {"type": "competitive", "name": "Settlers of Catan"}, 
 

   {"type": "competitive", "name": "Ticket to Ride"} 
] 
 
You can use the dataset literal in a generating command function. 
 

In this example, the name of the function is test_events. Here's how to specify the test_events function with a dataset 
literal: 
 


function test_events () { 
 

        {"type": "cooperative", "name": "Forbidden Island"}, 
 

        {"type": "cooperative", "name": "Sherlock Holmes: Consulting Detective"}, 
 

        {"type": "competitive", "name": "Terraforming Mars"}, 
 

    ] 
} 
 
Even though the function does not have any parameters, the parenthesis are required before the return expression. 
 

To invoke the test_events function, you only need to specify the name of the function: 
 

test_events 
 

The results look something like this: 
 

185 
 
Event 
 
name 
 
type 
 
{"type": "cooperative", "name": "Forbidden Island"} 
 
Forbidden Island 
 
cooperative 
 
{"type": "cooperative", "name": "Pandemic"} 
 
Pandemic 
 
cooperative 
 
{"type": "cooperative", "name": "Sherlock Holmes: Consulting Detective"} 
 
Sherlock Holmes: Consulting Detective 
 
cooperative 
 
{"type": "competitive", "name": "Settlers of Catan"} 
 
Settlers of Catan 
 
competitive 
 
{"type": "competitive", "name": "Terraforming Mars"} 
 
Terraforming Mars 
 
competitive�h1h2h3}�h5Kuh�(h3h/�h}�ub�$48c4ca17-89cc-4310-ba25-ebae7b7a7e4b�h+)�}�(h}�(h/X�cooperative 
 
{"type": "competitive", "name": "Settlers of Catan"} 
 
Settlers of Catan 
 
competitive 
 
{"type": "competitive", "name": "Terraforming Mars"} 
 
Terraforming Mars 
 
competitive 
 
{"type": "competitive", "name": "Ticket to Ride"} 
 
Ticket to Ride 
 
competitive 
 
To help you get started using dataset literals, see Sample dataset literals in the SPL2 Search Manual. Use the sample 
dataset literals as-is or as a starting point for your own data. 
 

See also 
 

Custom eval functions 
Documenting custom functions 
 



Custom data types 
 
Data types define the characteristics of the data. With custom data types, you can specify a set of complex characteristics 
that define the shape of your data. 
 

You can define your own data types by using either the built-in data types or other custom data types. 
 

There are several advantages to defining your own data types: 
 

Type checking 
 

always use the right data type. Using the wrong data type can have a significant impact on search performance 
and storage. See Additional examples. 
 

	Data types that are known to the system can take advantage of auto-completion features in a user interface (UI). 
Identify data structures 
 

SPL2 built-in data types. 
 

Supported data types 
 

SPL2 uses a rich data type system, including primitive types and derived types: 
 

• Primitive data types are used by themselves or as the basis for other data types. 
• Derived types are created from one or more primitive or other derived data types. 
 

This table describes the data types supported in SPL2: 
 

Type 
 

Description 
 

186 
 
A set of common data types, such as string, integer, long, and Boolean. 
 
Primitive types 
 

All of the primitive types are built-in to SPL2. For the complete list of built-in data types, see Built-in data 
types. 
 
A derived data type that defines a sequence of homogeneous values. 
 


Array types 
 


For example: 
 

type fullnames = string[] 
 
The built-in dataset data type is another example of an array type.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$19758ca2-e76e-4515-b3ed-c89b301c3552�h+)�}�(h}�(h/X-types. 
 
A derived data type that defines a sequence of homogeneous values. 
 


Array types 
 


For example: 
 

type fullnames = string[] 
 
The built-in dataset data type is another example of an array type. 
 
A derived data type that applies a constraint, in the form of a predicate expression, on an existing built-in or custom data type. 
 

Constrained 
types 
 


For example: 
 

type http_error=int where $value in([403, 404, 408]) 
 
Stream types 
 
A derived data type that defines a continuous, unending sequence of values. 
 
A derived data type that defines a group of different data types into a single data type. The built-in object data type is an 
example of a structured type. See Built-in data types. 
 



Structured 
types 
 


Examples of structured data types are authentication events or user records, such as: 
 
type person =  { 
 

   surname:string, 
 

} 
 
A derived type that specifies more than one valid data type. A union type can map to any of the specified types. 
 


Union types 
 


For example: 
 

type ipaddress=ipv4|ipv6 
 
The built-in number data type is another example of a union type. 
 
Declaring data types 
 

Data type declarations always start with the word type followed by the type name and the type expression. For example: 
 

type <type-name> = <type-expression> 
 

The type names follow the same conventions as field names: 
 

• Type names must begin with a-z, A-Z, or the underscore ( _ ) character. 
 



187 
 
• If the name begins with or contains any other character, the type name must be enclosed in single quotation 
	marks ( ' ). 
 

The type expression depends on the data type that you are declaring. 
 

For example, the following Union data type declaration uses an expression that includes alternative data types. The 
expression declares that the number data type can be either an integer, a long, a float, or a double. 
 


type number = int | long | float | double 
 
Array types 
 

Array data types define a sequence of any other data type. You specify an empty set of square brackets [] to indicate that�h1h2h3}�h5Kuh�(h3h/�h}�ub�$50a7d45e-c4fe-41b9-a4fd-e6aa1eaa2a42�h+)�}�(h}�(h/Xtype number = int | long | float | double 
 
Array types 
 

Array data types define a sequence of any other data type. You specify an empty set of square brackets [] to indicate that 
the type is an array. 
 

Syntax 
 

The required syntax for array types is in bold: 
 

type <type-name> = <property-data-type>[] 
 

Examples 
 

You can declare an array type that is an array of strings: 
 


type fullnames = string[] 
 
You can define an array of objects: 
 


type personnel = object[] 
 
You can also define an array of objects with this declaration: 
 


type personnel = {*}[] 
 
The object data type is one of the built-in data types. Object data types consist of members of key-value pairs. For 
example, the following object consists of the keys type and 'game-name': 
 


{type: "competitive", 'game-name': "Ticket to Ride"} 
 
Constrained types 
 

Sometimes a data type is too general. You can take a data type and put constraints on it to declare a narrower data type. 
This narrower data type is called a constrained data type. 
 

You add a constraint by including a where clause followed by a predicate expression in the data type definition. 
 

Syntax 
 

The required syntax for constrained types is in bold: 
 

type <type-name> = <type-name> where <predicate-expression> 
 


188 
 
For examples of predicate expressions, see Predicate expressions in the SPL2 Search Manual. 
 

Integer examples 
 

Integers can be positive or negative whole numbers. This example creates a data type called positive_integer that 
constrains an integer to values greater than or equal to zero ( 0 ): 
 


type positive_integer = int where $value >= 0 
 
This predicate could also be expressed as where $value > -1. 
 

Suppose you want positive integers that are not zero. The following example declares a data type called 
non_zero_positive_integer that constrains an integer to values greater than zero: 
 


type non_zero_positive_integer = int where $value > 0 
 
These examples use the implicit $value variable to access the value in your data to check.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$85033333-e196-483a-bfa6-cf554e5e8d65�h+)�}�(h}�(h/X�type non_zero_positive_integer = int where $value > 0 
 
These examples use the implicit $value variable to access the value in your data to check. 
 

Regular expression examples 
 

You can use constrained types for strings like IP addresses, credit card numbers, and social security numbers that match 
a particular regular expression. 
 

The following examples use the match function for the <predicate-expression>. 
 

This example declares a data type called ipv4 that is a string that matches a regular expression for valid IPv4 addresses: 
 


type ipv4 = string WHERE match($value, 
"(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" 
 
This example declares a data type called ipv6 that is a string that matches a regular expression for valid IPv6 addresses: 
 


type ipv6 = string WHERE match($value, ("((([0-9a-fA-F]){1,4})\\:){7}([0-9a-fA-F]){1,4}") 
 
With these two IP address data types, you can create a union data type that specifies that either IP address version is 
valid: 
 


type ipaddress = ipv4 | ipv6 
 
Structured type examples 
 

You can create a constrained data type that is based on a property in a structured data type. Consider the following 
structured data type called person: 
 


type person =  { 
 

        surname:string, 
 

} 
 
You can create a constrained data type called elderly_person that references the person data type. In this example, the 
value for the age property in the person data type must be greater than 70: 
 



189 
 
type elderly_person = person WHERE $value.age > 70 
 
This data type says any person that is older than 70 is also an elderly_person. 
 

Stream types 
 

Stream data types are similar to array data types. Both define a sequence of data types. A stream data type is a 
continuous, unending sequence of object instances. Because they are unending, the instances of stream types might not 
all fit into memory. Older instances will need to roll off to make room for newer instances.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$645ad1ec-926f-40d1-9c83-4acf2f80364d�h+)�}�(h}�(h/X�all fit into memory. Older instances will need to roll off to make room for newer instances. 
 

For example, consider a stream data type that defines new employees. The company is always hiring new employees. At 
some point an employee is no longer new to the company. 
 


type 'new-hire' = { 
 

   firstname:string, 
 

   division:string, 
 

   fulltime:boolean 
} 
 
In this example, the type name new-hire is in single quotation marks because the type name contains a dash. Type 
names that contain anything other than a-z, A-Z, 0-9, and the underscore ( _ ) character must be enclosed in single 
quotation marks. 
 

You can't define a stream data type that uses another stream type. 
 

Structured types 
 

Structured data types consist of a collection of property names and property data types. Use structured types to group 
data of different types into a single data type. 
 

The value assigned to a structured type is always a JSON object, which can be rendered as flattened fields or as the 
object itself. 
 

Syntax 
 

The required syntax for structured types is in bold: 
 

type <type-name> = {<property-name> [: <property-data-type>], ...} 
 

Separate each property with a comma. Enclose properties in curly brackets { }. 
 

type-name 
 

Description: The name of the data type. Valid type names are identical to valid field names. 
 

property-name 
 

Description: The name of the data type. Valid type names are identical to valid field names. 
 



190 
 
property-data-type 
 

Description: Optional. The data type of the property. You can specify any built-in or declared data type. 
 

Property data types 
 

Specifying property data types is optional. The property data types can be any built-in or declared data type. 
 

If the properties are known to SPL2, that is if SPL2 recognizes the property, then the data types don't have to be specified 
in the type declaration. If the properties are not known to SPL2, and you don't specify the data type, the default data type 
any is used.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f00abad2-c30a-4763-8755-79064cd0d6d7�h+)�}�(h}�(h/X�in the type declaration. If the properties are not known to SPL2, and you don't specify the data type, the default data type 
any is used. 
 

The following example declares a structured data type called person with two properties, firstname and surname. The 
property data types are not declared. 
 


type person = { 
 

   surname 
} 
 
The following example shows how to specify property data types. This example declares the person data type with three 
properties. The firstname and surname properties must be strings and the age property must be an integer. 
 


type person =  { 
 

        surname:string, 
 

} 
 
Specifying unknown properties 
 

Sometimes you don't know the properties in a structured object. Or you know some, but not all of the properties. To create 
a structured data type that includes zero or more properties of any data type, use the wildcard ( * ) character 
 

For example, the built-in object data type allows for any property of any data type: 
 


type object = {*} 
 
You can also express the object data type like this 
 


type my_object = {*:any} 
 
If you know some but not all of the properties, you can combine what you know with the wildcard character. In this 
example, the person type has at least three properties: firstname, surname and age. The person type might also have 
other unknown properties which can be of any data type. 
 


 type person =  { 
 

        surname:string, 
 

         * 
} 
 




191 
 
Specifying intermittent properties 
 

In a data type declaration, you can use the question mark ( ? ) character after the property name to indicate that a 
property might or might not be present. 
 

The following table describes several structure type examples of intermittent properties: 
 

Example 
 

Description 
 

type person =  { 
 

        surname?, 
 
In this object example, the surname property might or might not be present. The surname might appear in 
some events and be absent from other events. 
 
         * 
} 
 

 type person =  { 
 

        surname:string,�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ec53951e-5ba4-4b3a-83bd-5caddae8d470�h+)�}�(h}�(h/X;some events and be absent from other events. 
 
         * 
} 
 

 type person =  { 
 

        surname:string, 
 
In this object example, there might not be an age property. If the age property does exist, it must be an 
integer. 
 
         * 
} 
 
Union types 
 

A union data type specifies multiple valid data types. You declare a union type using the pipe ( | ) character, which is like 
specifying an OR operator between each type. 
 

Syntax 
 

The required syntax for union types is in bold: 
 

type <type-name> = <data-type> | <datatype> ... 
 

Example 
 

Suppose you create constrained types for IPv4 and IPv6 addresses. You can create a union data type like this: 
 


type ipaddress = ipv4 | ipv6; 
 
For the regular expressions used to create the ipv4 and ipv6 data types, see Regular expression examples In the 
Constrained types section. 
 

Additional examples 
 

Custom data types, custom functions, and searches 
 

Custom data types are often used in custom functions, which are in turn used in searches. Here's an example. 
 

You have some data about people that looks like this: 
 

custID 
 

info 
 


192 
 
0010 
 
{fname:"Claudia", sname:"Garcia"} 
 
0020 
 
{fname:"Ikraam", sname:"Rahat"} 
 
0025 
 
{fname:"Wei", sname:"Zhang"} 
 
You want to extract the information about each person from each info object. 
 

You need a function to extract the information for the first names and surnames in each object. The function might look 
something like this: 
 


function getPerson($x: object) : <some_data_type> { 
 

} 
 

• The name of the function is getPerson 
 

• The data type of the function parameter is object 
 

To extract the information about each person, you need to declare a structured data type that represents the person 
information. This is the <some_data_type> portion of the function. 
 

You create a data type called person that identifies the data types of each of the key-value pairs in the object. The data 
type looks like this: 
 


type person = { 
 

   surname:string 
} 
 
You can now specify the name of the data type in your function:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$702d2c5d-7b27-4c20-9013-4f56db2908aa�h+)�}�(h}�(h/X�type looks like this: 
 


type person = { 
 

   surname:string 
} 
 
You can now specify the name of the data type in your function: 
 


function getPerson($x: object) : person { 
 

} 
 
The expressions for the firstname and surname indicate the path to the information in the objects. 
 

You can now create a search that uses the custom function and custom data type. This example uses a dataset literal, 
instead of a dataset, to show the data: 
 

FROM [{custID:0010, info:{fname:"Claudia", sname:"Garcia"}}, {custID:0020, info:{fname:"Ikraam", 
sname:"Rahat"}}, {custID:0025, info:{fname:"Wei", sname:"Zhang"}}] AS names SELECT getPerson(names) 
 


The results look something like this: 
 

getPerson(name) 
 
{"firstname":"Claudia", "surname":"Garcia"} 
 
{"firstname":"Ikraam", "surname":"Rahat"} 
 
{"firstname":"Wei", "surname":"Zhang"} 
 
To flatten the key-value pairs in each object, add .* to the end of the search: 
 

193 
 
FROM [{custID:0010, info:{fname:"Claudia", sname:"Garcia"}}, {custID:0020, info:{fname:"Ikraam", 
sname:"Rahat"}}, {custID:0025, info:{fname:"Wei", sname:"Zhang"}}] AS names SELECT getPerson(names).* 
 


The results look something like this: 
 

firstname 
 

surname 
 
Claudia 
 
Garcia 
 
Ikraam 
 
Rahat 
 
Wei 
 
Zhang 
 
Type checking example 
 

This example has a function called baz that expects a value that's number: 
 


function baz($x: number) { return $x;} 
 
This search calls the baz function but supplies a string value "hello": 
 


$out = FROM [{}] SELECT baz("hello") 
 
When the function performs a type check, it expects a number but receives a string instead. An error message is returned 
that says the argument "hello" is a string in the 'baz' function and that it doesn't match the parameter type 'number'. 
 

See also 
 

Related information 
	Built-in data types 
 

Custom eval functions 
Custom command functions 
 


Documenting custom functions 
 
You can add descriptions and examples to your custom functions in the form of documentation comments. In a user�h1h2h3}�h5Kuh�(h3h/�h}�ub�$18cee207-3f48-44e4-b217-1fc57240add1�h+)�}�(h}�(h/X"Custom eval functions 
Custom command functions 
 


Documenting custom functions 
 
You can add descriptions and examples to your custom functions in the form of documentation comments. In a user 
interface (UI), this documentation appears when someone hovers over or clicks on the custom function. 
 

Documentation comments versus regular comments 
 

Documentation comments differ from regular comments. Use documentation comments to explain how to use a custom 
function and regular comments to explain what a custom function does: 
 

• Documentation comments provide documentation that appears in a UI to help users understand how to use a 
	custom function. 
 








194 
 
Documentation comment tagging 
 

You use a special type of comment tag to document custom functions: 
 

1. The documentation comment starts with the /** tag. 
 

3. Use the backtick ( ` ) character to format text in the monospace font. Monospace font is typically used on 
	command, function, dataset, parameter, and field names to distinguish these names from the surrounding text. 
 


You place the documentation comment immediately before the function definition. 
 

Specifying function and parameter descriptions 
 

Consider this custom function called isError: 
 


function isError($code : number) : boolean { 
 

} 
 
You can specify an overall description for a custom function and descriptions for each parameter that is defined in that 
custom function. If the descriptions appear in a Ui, keep the descriptions short and concise. 
 

Overall description 
 

The overall description must be at the beginning of the documentation comment. Make the overall description one or more 
sentences in length. 
 

Parameter descriptions 
 

The parameter descriptions must begin with @param followed by the name of the parameter. For example, @param $field. 
 

Description and parameter example 
 

Here is an example of the overall description and parameter descriptions inside a documentation comment for the isError 
custom function: 
 


/** 
 

 * 
 

 */ 
 

  return $code >= 400 
}�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cf8bf900-48b5-424c-a40f-8cd5f3dccdee�h+)�}�(h}�(h/XPHere is an example of the overall description and parameter descriptions inside a documentation comment for the isError 
custom function: 
 


/** 
 

 * 
 

 */ 
 

  return $code >= 400 
} 
 
Notice that the document comment appears immediately before the definition for the isError custom function. 
 

Including examples in a documentation comment 
 

You can include examples in the documentation comment for a custom function. 
 



195 
 
Format an example 
 

Examples in a documentation comment must be formatted in a specific way: 
 

1. Each example must begin with @example. 
 

3. To format the SPL2 in the example: 
 

2. End the example with three backtick ( ``` ) characters. 
 


Here is an example: 
 


 * Looks for error codes greater than or equal to 400 and returns a Boolean value. 
 

 * @param $code - A numeric field that contains HTTP error codes. 
 

 * @example 
 

 * the data in the `jsondata` index. The `status_code` field is the value used for 
 

 * ```spl 
 

 * ``` 
 
Documentation comment examples 
 

The following example includes a documentation comment that contains an overall description, parameter descriptions, 
and multiple examples: 
 


/** 
 

 * values in a specific field. 
 

 * @param $source - Identifies the dataset that the command operates on. 
 

 * The `stats` command counts the events and organizes the count by the 
 

 * @param $limit - Specifies the maximum number of results to return. 
 

 * The `head` command returns the top values in the results from the `sort` 
 

 * 
 

 * Return the top 5 values from the `host` field. 
 

 * from sample_data_index | top host 5 
 

 * 
 

 * Return the top 12 values from the `clientip` field. 
 

 * FROM main | top clientip 12 
 

 */ 
 

    return | FROM $source 
 

196 
 
        | stats count() by $field 
 

        | head $limit 
} 
 
In addition to adding a documentation comment to a function, you can add regular comments as well. The following 
example is the same as the previous example, with the addition of regular comments to describe parts of the function. 
 


/** 
 

 * values in a specific field.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7037fc0c-9369-468f-8d3d-ba2d7c5885ac�h+)�}�(h}�(h/X%example is the same as the previous example, with the addition of regular comments to describe parts of the function. 
 


/** 
 

 * values in a specific field. 
 

 * @param $source - Identifies the dataset that the command operates on. 
 

 * The `stats` command counts the events and organizes the count by the 
 

 * @param $limit - Specifies the maximum number of results to return. 
 

 * The `head` command returns the top values in the results from the `sort` 
 

 * 
 

 * Return the top 5 values from the `host` field. 
 

 * from sample_data_index | top host 5 
 

 * 
 

 * Return the top 12 values from the `clientip` field. 
 

 * FROM main | top clientip 12 
 

 */ 
 

    return | FROM $source 
 

        | sort -count // SORTS THE COUNTS IN DESCENDING ORDER 
 

} 
 
See also 
 

Functions 
 

Custom command functions 
 

Related information 
 















197 
 
Search Command Quick Reference 
 


SPL2 Command Quick Reference 
 
The following commands are supported in SPL2. Use the links in the table to see the command syntax, examples, and 
usage information. 
 

Command 
 

Description 
 

Example 
 


bin 
 

Puts continuous numerical 
values into discrete sets, or 
bins. 
 
Example: Return the average for a field for a specific time span. Bin the search results using a 5 
minute time span on the _time field. Return the average thruput of each host for each 5 
minute time span. 
 
...| bin span=5m _time | stats avg(thruput) by _time, host 
 
Processes one set of 
events or search results, in 
 
Example: Read the events in the main index dataset into memory one time. Process the events in 
two branches using subsearches to determine the most popular hosts and sources. 
 
branch 
 
branches. Each branch 
must end with the into 
command. 
 

| from main | branch [stats count() BY host | where count > 50 select 

source | into p_sources] 
 


dedup 
 
Removes the events that 
contain an identical 
combination of values for 
the fields that you specify. 
 

Example: Remove duplicates of results with the same host value. 

... | dedup host�h1h2h3}�h5Kuh�(h3h/�h}�ub�$06c2b786-a604-40f1-bce7-99d3644fa21e�h+)�}�(h}�(h/X-dedup 
 
Removes the events that 
contain an identical 
combination of values for 
the fields that you specify. 
 

Example: Remove duplicates of results with the same host value. 

... | dedup host 
 
Example: Create a new field that contains the result of a calculation. Create a new field called 
velocity in each event. Calculate the velocity by dividing the values in the distance field by the 
values in the time field. 
 



eval 
 

Calculates an expression 
and puts the resulting 
value into a search results 
field. 
 

... | eval velocity=distance/time 


Example: Use the if function to analyze field values. Create a new field called 
error in each event. Using the if function, set the value in the error field to OK if the 
status value is 200. Otherwise set the error field value to Problem. 
 

... | eval error = if(status == 200, "OK", "Problem") 
 


eventstats 
 

Generates summary 
statistics from fields in your 
 
Example: Calculate an average for each distinct value of the date_minute field. The new field 
avgdur is added to each event with the average value based on its particular value of 
 
statistics into a new field. 
 

... | eventstats avg(duration) AS avgdur BY date_minute 
 
expand 
 
Produce a separate result 
 
Example: Expand the array in the bridges field. Here is the event before the field is expanded: 
 
row for each object in an 
array that is in a field. 
 
_time 
 
bridges 
 
5 May 2021 2:29:02 
PM 
 
[{"name":"Tower Bridge","length":801},{"name":"Millennium 
Bridge","length":1066}] 
 
... | expand bridges 
 

Here are the results after the expand command is run: 
 



198 
 
Command 
 
Description 
 
Example 
 

_time 
 

bridges 
 
5 May 2021 2:29:02 PM 
 
{"name":"Tower Bridge","length":801} 
 
5 May 2021 2:29:02 PM 
 
{"name":"Millennium Bridge","length":1066} 
 


fields 
 

Keeps or removes fields 
from search results based 
on the list of fields that you 
specify. 
 

Example: Specify a list of fields to include in the search results. Return only the host and src 
fields from the search results. 

... | fields host, src�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4312400a-d01e-41ea-a837-9a8f73a6938e�h+)�}�(h}�(h/XLon the list of fields that you 
specify. 
 

Example: Specify a list of fields to include in the search results. Return only the host and src 
fields from the search results. 

... | fields host, src 
 
Example: Return the summary statistics for all incoming fields. 
 


fieldsummary 
 
Calculates summary 
statistics for one or more 
fields in your events, 
displayed as a results 
table. 
 

...| fieldsummary 


Example: Return the summary statistics for a specific field. 
 

...| fieldsummary fields=[action] 
 
Example: Flattens the values in the bridges object into separate fields. 
 




flatten 
 


Converts the key-value 
pairs in the object into 
separate fields in an event. 
Flattens only the first level 
 

| FROM [{}] SELECT _time, {name: "Tower Bridge", length: 801} as bridges 
| flatten bridges 

The results look like this: 
 
of an object. 
 
_time 
 
bridges 
 
length 
 
name 
 

21 Sep 2022 2:34:17 PM 
 

[{"name":"Tower Bridge", "length":801}] 
 

801 
 
Tower 
Bridge 
 






from 
 

Retrieves data from a 
dataset, such as an index, 
metric index, lookup, view, 
or job. 

The from command 
has a flexible syntax, 
which enables you to 
start a search with 
either the FROM clause 
 




Example: Return data from the main index for the last 5 minutes. Group the results by host. 
Calculate the sum of the bytes field. Return the sum and the host fields where the sum of the bytes 
is greater than I MB. 

| FROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host SELECT 
sum(bytes) AS sum, host HAVING sum > 1024*1024 
 



head 
 


Returns the first N number 
of specified results in 
search order. 
 

Example: Stop searching when a null value is encountered. This example returns results while 
action=purchase or the action field does not exist in the results (null=true). A maximum of 
50 results are returned. 
 
...| head while (action="purchase") null=true 50 
 


into 
 
Sends results to a dataset 
that is writable, a dataset 
sink. Appends or replaces 
the dataset sink in the 
 

Example: Append the search results to the mytable dataset, which is a lookup kind of dataset.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9c2914d7-7ea9-4fd7-802c-ec8e8329dcb7�h+)�}�(h}�(h/X	Sends results to a dataset 
that is writable, a dataset 
sink. Appends or replaces 
the dataset sink in the 
 

Example: Append the search results to the mytable dataset, which is a lookup kind of dataset. 

... | into mode=append mytable 
 

join 
 

199 
 
Command 
 
Description 
 
Example 
 
Combines the results from 
two datasets by using one 
or more common fields. 
 
Example: Join datasets on fields that have the same name. Combine the results from a search 
with the vendors dataset. The data is joined on the product_id field, which is common to both 
datasets. 
 

... | join left=L right=R where L.product_id=R.product_id vendors 
 
Example: Put corresponding information from a lookup dataset into your events. 
 




lookup 
 




Invokes field value 
lookups. 
 

Append the data returned from your search results with the data in the users 
lookup dataset using the uid field. For search results that contains a uid field, the 
value in that field is matched with the uid field in the users lookup dataset. The 
username and department fields from the users lookup dataset are appended to 
each search result. If the search results already have the username and 
department fields, the OUTPUTNEW argument only fills in missing values in those 
fields. 
 

... | lookup users uid OUTPUTNEW username, department 
 


mvexpand 
 
Expands the values of a 
multivalue field into 
separate events, one event 
for each value in the 
multivalue field. 
 

Example: Expand the values in the myfield field. 

... | mvexpand myfield 
 


rename 
 

Renames one or more 
fields. 
 
Example: Rename a field with special characters. Rename the ip-add field to IPAddress. Field 
names that contain anything other than a-z, A-Z, 0-9, or "_", need single-quotation marks. 
 
... | rename 'ip-add' AS IPAddress 
 

reverse 
 

Reverses the order of the 
search results. 
 
Example: 

... | reverse 
 





rex 
 


Use to either extract fields 
using regular expression 
named groups, or replace 
or substitute characters in 
a field using sed 
expressions.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3b05bc08-aff9-4465-99bb-bdbe4f07636c�h+)�}�(h}�(h/X.search results. 
 
Example: 

... | reverse 
 





rex 
 


Use to either extract fields 
using regular expression 
named groups, or replace 
or substitute characters in 
a field using sed 
expressions. 
 
Example: Extract values from a field using a <regex-expression>. Extract user, app, and 
SavedSearchName from a field called savedsearch_id in scheduler.log events. 

... | rex field=savedsearch_id 
"(?<user>\\w+);(?<app>\\w+);(?<SavedSearchName>\\w+)" 

If the contents of the field is savedsearch_id=bob;search;my_saved_search then 
this rex command syntax extracts user=bob, app=search, and 
SavedSearchName=my_saved_search. 
 
Example: Search for a field-value pair for a specific source IP, src. 
 

search src="192.0.2.0" 
 


search 
 
Retrieve events from 
indexes or filter the results 
of a previous search 
command in the pipeline. 
 


Example: Search for multiple field-value pairs with boolean and comparison 
operators. This example searches for events with code values of either 10, 29, or 
43 and any host that is not "localhost", and an xqp value that is greater than 5. 
 

search (code=10 OR code=29 OR code=43) host!="localhost" xqp>5 
 
select 
 
See the from command. 
The SELECT clause is part 
 
Example: Calculate the sum of the bytes field. Return the sum and the host fields from the main 
index for the last 5 minutes. Group the results by host. 
 


200 
 
Command 
 
Description 
 
Example 
 
of the from command. 
 
| SELECT sum(bytes) AS sum, host FROM main WHERE earliest=-5m@m GROUP BY 
host 
 


sort 
 

Sorts all of the results by 
the specified fields. 
 
Example: Sort the results first by the surname field in ascending order and then by the 
firstname field in descending order. 
 
... | sort surname, -firstname 
 
Example: Consider this SPL search: 
 

error OR http_code=404 
 



spl1 
 
Embed all or part of an 
SPL search into an SPL2 
search. The spl1 
command supports two 
syntaxes: backtick ( ` ) 
character syntax and 
explicit spl1 command 
syntax. 
 

Embed this search into an SPL2 search using the backtick ( ` ) character syntax:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$eac05894-6ad4-458d-ac30-88608ad2a6fc�h+)�}�(h}�(h/X�search. The spl1 
command supports two 
syntaxes: backtick ( ` ) 
character syntax and 
explicit spl1 command 
syntax. 
 

Embed this search into an SPL2 search using the backtick ( ` ) character syntax: 

`search index=main error OR http_code=404` 


Example: In this SPL2 search only the portion of the search not supported by 
SPL2, the addinfo command, uses the backtick ( ` ) character syntax: 
 

from sample_data_index | stats sum(bytes) BY host | `addinfo` 
 


stats 
 
Calculates aggregate 
statistics such as average, 
count, and sum, over the 
results set. 
 
Example: Take the incoming result set and calculate the sum of the bytes field and groups the 
sums by the values in the host field. 

... | stats sum(bytes) BY host 
 


streamstats 
 

Adds a cumulative 
statistical value to each 
search result as each 
result is processed. 
 
Example: Use a <by-clause> to add a running count to search results. This search uses the host 
field to reset the count. For each search result, a new field is appended with a count of the results 
based on the host value. The count is cumulative and includes the current result. 

... | streamstats count() BY host 
 



thru 
 
Writes data to a writeable 
dataset and then passes 
the same data to the next 
command in the search 
string. By default, the thru 
command appends data to 
the dataset. 
 


Example: Append all the incoming search result set to the actions dataset. Those same search 
results are also passed into the eval command. 

... | thru actions | eval field=<expr> 
 

timechart 
 
Creates a time series chart 
with corresponding table of 
 
Example: For each minute, calculate the average value of the CPU field for each host. 
 
... | timechart span=1m avg(CPU) BY host 
 



timewrap 
 
Compare data over a 
specific time period, such 
as day-over-day or 
month-over-month, or 
multiple time periods, such 
as a two week period over 
another two week period. 
 


Example: Display a timechart that has a span of 1 day for each count in a week over week�h1h2h3}�h5Kuh�(h3h/�h}�ub�$778d94d0-c419-44f5-9dcb-04900ebdba87�h+)�}�(h}�(h/X]month-over-month, or 
multiple time periods, such 
as a two week period over 
another two week period. 
 


Example: Display a timechart that has a span of 1 day for each count in a week over week 
comparison table. Each table column, which is the series, is 1 week of time. 

... | timechart count span=1d | timewrap 1week 
 
union 
 
Merges the results from 
two or more datasets into 
one dataset. One dataset 
can be piped into the 
union command and 
 
Example: Merge events from the customers, orders, and vendors datasets. You must separate the 
dataset names with a comma. 

| union customers, orders, vendors 
 


201 
 
Command 
 
Description 
 
Example 
 
dataset. 
 
Example: Append the current results of the main search with the tabular results of 
errors from the subsearch. 
 

... | stats count() BY category1 | union [search error | stats count() BY 
category2] 
 
Example: Use the like comparison operator with the percent symbol ( % ) as a wildcard. This 
example returns all results where the ipaddress field contains values that start with "192.". 
 

... | where ipaddress like "192.%" 
 



where 
 


Filters search results based 
on the outcome of a 
Boolean expression. 
 


Example: Compare one field to another field. 

... | where ipaddress=clientip 
 


Example: Filter using a field-value pair. 
 

... | where host="www1" 
 
See also 
 

Other Quick References 
 

SPL2 stats and chart functions Quick Reference 
 

Related information 
 





























202 
 
bin command 
 


bin command overview 
 
Puts continuous numerical values into discrete sets, or bins, by adjusting the value of <field> so that all of the items in a 
particular set have the same value. 
 

The bin command is automatically called by the timechart command. Use the bin command for only statistical 
operations that the timechart command cannot process. 
 

Syntax 
 

The required syntax is in bold. 
 

bin 
[<bin-options>...] 
 


How the bin command works 
 

Use the bin command to group events by the numerical values in a field. Consider the following timestamps: 
 

Event number 
 

_time 
 

Hour and minute�h1h2h3}�h5Kuh�(h3h/�h}�ub�$acc424cb-21dc-4bf0-b441-3f4d4a9ef4d6�h+)�}�(h}�(h/X}bin 
[<bin-options>...] 
 


How the bin command works 
 

Use the bin command to group events by the numerical values in a field. Consider the following timestamps: 
 

Event number 
 

_time 
 

Hour and minute 
 

Minutes from first time 
 
1 
 
22 Aug 2021 01:56:37 AM 
 
01:56 
 
2 
 
22 Aug 2021 01:58:21 AM 
 
01:58 
 
2 minutes 
 
3 
 
22 Aug 2021 01:59:59 AM 
 
01:59 
 
3 minutes 
 
4 
 
22 Aug 2021 02:03:16 AM 
 
02:03 
 
7 minutes 
 
5 
 
22 Aug 2021 02:05:43 AM 
 
02:05 
 
9 minutes 
 
6 
 
22 Aug 2021 02:09:38 AM 
 
02:09 
 
13 minutes 
 
7 
 
22 Aug 2021 02:12:31 AM 
 
02:12 
 
16 minutes 
 
You decide to run a search that bins the search results using a 5 minute time span on the _time field. 
 

...| bin span=5m _time 
 


The bin command groups the timestamps in the _time field into 5 minutes intervals. The groups are: 
 

Group 
 

Timestamps from _time 
 

Timestamp span range for each bin 
 
22 Aug 2021 01:56:37 AM 
 
1 
 

22 Aug 2021 01:58:21 AM 
22 Aug 2021 01:59:59 AM 
 
22 Aug 2021 01:56:37 AM --- 22 Aug 2021 02:01:36 AM 
 
2 
 
22 Aug 2021 02:03:16 AM 
 
22 Aug 2021 02:01:37 AM --- 22 Aug 2021 02:06:36 AM 
 


203 
 
Group 
 
Timestamps from _time 
 
Timestamp span range for each bin 
 
22 Aug 2021 02:05:43 AM 
 
3 
 
22 Aug 2021 02:09:38 AM 
 
22 Aug 2021 02:07:37 AM --- 22 Aug 2021 02:11:36 AM 
 
4 
 
22 Aug 2021 02:12:31 AM 
 
22 Aug 202102:11:37 AM --- 22 Aug 2021 02:16:36 AM 
 

For searching purposes only, the bin command adjusts the value of _time so that all of the results use the same _time 
value. Commands in your search that come after the bin command will use this temporary value for _time. 
 

The temporary timestamps for subsequent commands are the first timestamp in the span range, unless you specify a 
snap-to time. 
 


Group 
 


Timestamps from _time 
 


Timestamp span range for each bin 
 

Timestamps for subsequent 
	commands 
 
22 Aug 2021 01:56:37 AM 
 

1 
 

22 Aug 2021 01:58:21 
AM 
 

22 Aug 2021 01:56:37 AM --- 22 Aug 2021 02:01:36 
AM 
 

22 Aug 2021 01:56:37 AM 
 

AM 
 
22 Aug 2021 02:03:16 AM 
 
2 
 

22 Aug 2021 02:05:43 
AM 
 
22 Aug 2021 02:01:37 AM --- 22 Aug 2021 02:06:36 
AM�h1h2h3}�h5Kuh�(h3h/�h}�ub�$423835c3-06dc-4177-9dc2-4125214952ca�h+)�}�(h}�(h/X	AM 
 

22 Aug 2021 01:56:37 AM --- 22 Aug 2021 02:01:36 
AM 
 

22 Aug 2021 01:56:37 AM 
 

AM 
 
22 Aug 2021 02:03:16 AM 
 
2 
 

22 Aug 2021 02:05:43 
AM 
 
22 Aug 2021 02:01:37 AM --- 22 Aug 2021 02:06:36 
AM 
 
22 Aug 2021 02:01:37 AM 
 

3 
 

22 Aug 2021 02:09:38 AM 
 
22 Aug 2021 02:07:37 AM --- 22 Aug 2021 02:11:36 
AM 
 

22 Aug 2021 02:07:37 AM 
 

4 
 

22 Aug 2021 02:12:31 AM 
 
22 Aug 2021 02:11:37 AM --- 2019-08-22 02:16:36 
AM 
 

22 Aug 2021 02:11:37 AM 
 

The bin command is frequently used in a search before the stats command. In this example, after the search results are 
organized into bins, the stats command returns the average "thruput" of each "host" for every 5 minute time span. The 
search results are arranged by _time and host. 
 

...| bin span=5m _time | stats avg(thruput) by _time, host 
 

See also 
 

bin command 
 

bin command usage 
 



bin command syntax details 
 






204 
 
Syntax 
 

The required syntax is in bold. 
 

bin 
[<bin-options>...] 
 


The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can 
specify the keyword in uppercase or lowercase. 
 

Required arguments 
 

field 
 


Syntax: <field> 
 


Optional arguments 
 

bin-options 
 

Description: Discretization options. See the Bin options section for the syntax and description for each of these 
options. 
 

newfield 
 

Description: A new name for the field. 
 

Bin options 
 

bins 
 


Syntax: bins=<int> 
 


minspan 
 

Description: Specifies the smallest span granularity to use to automatically infer the span from the data time 
range. 
 

span 
 


Syntax: span = <span-length> | <log-span> 
 


<start-end> 
 

Description: Sets the minimum and maximum extents for numerical bins. The data in the field is analyzed and 
the beginning and ending values are determined. The start and end arguments are used when a span value is not 
specified. 
 




205 
 
You can use the start or end arguments only to expand the range, not to shorten the range. For example, if the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$da6b57a4-7978-420d-87ba-4db0dde01d88�h+)�}�(h}�(h/XNspecified. 
 




205 
 
You can use the start or end arguments only to expand the range, not to shorten the range. For example, if the 
field represents seconds the values are from 0-59. If you specify a span of 10, then the bins are calculated in 
increments of 10. The bins are 0-9, 10-19, 20-29, and so forth. If you do not specify a span, but specify end=1000, 
the bins are calculated based on the actual beginning value and 1000 as the end value. 
 

If you set end=10 and the values are >10, the end argument has no effect. 
 

aligntime 
 

Description: Align the bin times to something other than base UTC time (epoch 0). The aligntime option is valid 
only when doing a time-based discretization. Ignored if span is in days, months, or years. 
 

Span options 
 

log-span 
 

Description: Sets to logarithm-based span. The first number is a coefficient. The second number is the base. If 
the first number is supplied, it must be a real number >= 1.0 and < the base number. Base, if supplied, must be 
 

Example: span=2log10 
 

span-length 
 

Description: A span of each bin. If discretizing based on the _time field or used with a timescale, this is treated 
as a time range. If not, this is an absolute bin length. 
 

timescale 
 

Description: Time scale units. If discretizing based on the _time field. 
Default: sec 
 

Time scale 
 

Syntax 
 

Description 
 
<sec> 
 
sec | secs | second | seconds 
 
Time scale in seconds. 
 
<min> 
 
min | mins | minute | minutes 
 
Time scale in minutes. 
 
<hr> 
 
hr | hrs | hour 
 
Time scale in hours. 
 
<day> 
 
day | days 
 
Time scale in days. 
 
<month> 
 
month | months 
 
Time scale in months. 
 
<subseconds> 
 
ms | cs | ds 
 
Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds). 
 
See also 
 

bin command 
 

bin command usage 
 







206 
 
bin command usage 
 

Differences between SPL and SPL2 
 

Command options must be specified before command arguments 
 

Version 
 

Example 
 


SPL 
 
...bin 
myfield 
span=1d 
AS mytime 
 


SPL2 
 
...bin 
span=1d 
myfield AS 
mytime 
 
See also 
 

bin command�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4a35f795-0d36-4d66-965b-9d73924f2f91�h+)�}�(h}�(h/XaCommand options must be specified before command arguments 
 

Version 
 

Example 
 


SPL 
 
...bin 
myfield 
span=1d 
AS mytime 
 


SPL2 
 
...bin 
span=1d 
myfield AS 
mytime 
 
See also 
 

bin command 
 

bin command syntax details 
bin command examples 
 


bin command examples 
 
The following are examples for using the SPL2 bin command. To learn more about the bin command, see How the bin 
command works. 
 

1. Return the average for a field for a specific time span 
 

Bin the search results using a 5 minute time span on the _time field. Return the average "thruput" of each "host" for each 
5 minute time span. 
 

...| bin span=5m _time | stats avg(thruput) by _time, host 
 


Alternative: You can also specify the span directly with the stats command. 
 

...| stats avg(thruput) by span(_time, 5m), host 
 

2. Specify a bin size and return the count of raw events for each bin 
 

Bin the search results into 10 bins for the size field and return the count of raw events for each bin. 
 

... | bin bins=10 size AS bin_size | stats count(_raw) BY bin_size 
 







207 
 
3. Create bins with a large end value to ensure that all possible values are included 
 

Create bins with an end value larger than you need to ensure that all possible values are included. Bin the results based 
on the amount field. 
 

... | bin end=1000 amount 
 



4. Align the bins to a specific time and set the span to 12 hour intervals from that time 
 

Set the span to 12h. Align the bins to 3am (local time). The bins will represent 3am - 3pm, then 3pm - 3am (the next day), 
and so on. Bin the results based on the _time field. 
 

...| bin span=12h aligntime=@d+3h _time 
 



5. Align the bins to a specific UTC time 
 

Align the bins to the UTC time of 1500567890 for values in the _time field. 
 

...| bin aligntime=1500567890 _time 
 

See also 
 

bin command 
 

bin command syntax details 
bin command usage 
 



























208 
 
branch command 
 


branch command overview 
 
Processes one set of events or search results, in parallel, simultaneous searches. Each search branch must end with the 
into command.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$76bdb04d-9e7e-41d8-9219-26d4cf3552ac�h+)�}�(h}�(h/X�bin command usage 
 



























208 
 
branch command 
 


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

Syntax 
 

The required syntax is in bold. 
 

branch 
 

[<SPL-literal> | into <dataset>] ... 
 

How the branch command works 
 

Using the branch command, you can take one set of data and run multiple searches simultaneously against that data. The 
simultaneous searches are referred to as branches. The results of the searches are placed into separate lookup or 
splv1sink datasets, using the into command. The data that you search can be events or search results. 
 

Consider the following search. This search reads the events in the main index dataset into memory one time. The events 
are then processed in two branches using subsearches to determine the most popular hosts and sources. 
 

| from main | branch [stats count() BY host | where count > 50 select host | into p_hosts], [stats count() 
BY source | where count > 100 select source | into p_sources] 
 



• The first branch uses the stats command to count the events by host and returns only those hosts with a count 
	above the threshold of 50. Using the into command, the results are appended to the p_hosts dataset. 
 

sources with a count above the threshold of 100. Using the into command, the results are appended to the 
p_sources dataset. 
 

The branch command does not return any results to the search endpoint. You must send the search results to a lookup 
or splv1sink dataset using the into command. The into must be the last command in each branch. 
 

The data that you search can be events or search results. The previous example used events from the main index. The 
following search uses the results returned from the beginning of a search and then processes that data in 3 branches. 
 

| from my_dataset where earliest=-5m@m AND latest=@m | branch [stats avg(cpu_usage) BY host | where�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ee7b79e6-dd14-4f19-b3ee-2ce503a79ecc�h+)�}�(h}�(h/X	| from my_dataset where earliest=-5m@m AND latest=@m | branch [stats avg(cpu_usage) BY host | where 
avg(cpu_usage) > 2000000 select host | into cpu_hosts], [stats count() BY host | where count > 50 select 
host | into p_hosts], [stats count() BY source | where count > 100 select source | into p_sources ] 
 

In this example, the average and count aggregations must be calculated first, because the filtering, with the where 
command, use those aggregations. In other situations, you might want to filter before the aggregations. See the branch 
command examples. 
 


209 
 
See also 
 

branch command 
 

branch command usage 
branch command examples 
 

Other commands 
 

where command overview 
 


branch command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

branch 
 

[<SPL-literal> | into <dataset> ] ... 
 

Each branch is enclosed in square brackets and separated by commas. 
 

Required arguments 
 

SPL-literal 
 

Description: A snippet of fully-formed SPL that is complete enough to be run as a separate search. 
 

dataset 
 


Syntax: <dataset-name> 
 

default the into command appends the search results to the dataset. To replace the data in the dataset with the 
data from the search, you must use the mode=replace argument with the into command. The mode only applies 
to lookups. The mode is not used with datasets where the kind of dataset is spl1sink. 
 

Optional arguments 
 

None. 
 

See also 
 

branch command 
 

branch command usage 
branch command examples 
 

Related information 
 



210 
 
branch command usage 
 
You can use the first command in a branch to specify condition or filters for that branch, for example: 
 

| from people | branch [where (age < 13 ) | stats count() BY firstname | into child_names], [where gender = 
"M" | stats count() BY firstname | into male_names], [where gender = "F" | stats count() BY firstname | into 
female_names], [stats count() BY firstname | into names] 
 

This search loads all of the people into memory and then sends those events down 4 branches.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8c93820e-8138-4d85-b803-6f1b6830fe3c�h+)�}�(h}�(h/Xfemale_names], [stats count() BY firstname | into names] 
 

This search loads all of the people into memory and then sends those events down 4 branches. 
 

• The first 3 branches use the where command to filter the events for people in particular groups (children, men and 
	women) and then calculates the count using the stats command. 
 


See also 
 

branch command 
 

branch command syntax details 
branch command examples 
 


branch command examples 
 
The following are examples for using the SPL2 branch command. To learn more about the branch command, see How the 
branch command works. 
 

1. Specifying multiple branches 
 

You must specify at least 2 branches. This example uses 3 branches. 
 

| search sourcetype=access_* | branch [ stats count() BY productId | into sales ], [ stats avg() BY 
productId | into metrics ], [ stats count() BY host | into hosts] 
 

While this search is valid, it isn't very efficient because it doesn't filter the search on anything other than sourcetype. 
 

The next example shows how to use a filter to speed up the processing of your branches. 
 

2. Specifying filters 
 

Make your search more efficient by specify a filter on the data. 
 

Filtering on a branch 
 

This search loads all the cities into memory and then processes those events in 3 separate branches. This example uses 
the where command to filter the data. Because the filter is different for each branch, the filter is added at the beginning of 
the branch. 
 

| from cities | branch [ where population < 10000 | stats count() BY name | into villages], [ where 
population >= 10000 AND population <= 1000000 | stats count() by name | into towns], [ where population > 
 



211 
 
This example filters the data before performing the stats command aggregations. For an example of filtering after the 
aggregations, see the section How the branch command works in branch command overview. 
 

Filtering on the main search 
 

Here is an example that returns results based on successful sales and purchase issues. Because one of the filters is the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7a4d5f1b-2be6-4509-ab5f-12b071e0be57�h+)�}�(h}�(h/X�Filtering on the main search 
 

Here is an example that returns results based on successful sales and purchase issues. Because one of the filters is the 
same for all of the branches, that filter action=purchase is added to the main search. Additionally, each branch includes a 
filter using the where command. 
 

| search sourcetype=access_* action=purchase | branch [ where status=200 | stats count() BY product | into 
sales ], [ where status!=200 | stats count() BY product | into purchase_issues] 
 

See also 
 

branch command 
 

branch command syntax details 
branch command usage 
 

Other commands 
 

where command overview 
 





































212 
 
dedup command 
 


dedup command overview 
 
Removes the events that contain an identical combination of values for the fields that you specify. 
 

With the dedup command, you can specify the number of duplicate events to keep for each value of a single field, or for 
each combination of values among several fields. 
 

Events returned by the dedup command are based on search order. For historical searches, the most recent events are 
searched first. For real-time searches, the first events that are received are searched, which are not necessarily the 
most recent events. 
 

Syntax 
 

The required syntax is in bold. 
 

dedup 
[<int>] 
 

[consecutive=<bool>] 
<field-list> 
 

How the dedup command works 
 

Suppose that you have the following search results: 
 

host 
 

action 
 

client_ip 
 
www1 
 
view 
 
211.166.11.101 
 
www2 
 
addtocart 
 
194.215.205.19 
 
www3 
 
view 
 
74.53.23.135 
 
www1 
 
addtocart 
 
128.241.220.82 
 
www1 
 
purchase 
 
64.66.0.20 
 
www3 
 
view 
 
107.3.146.207 
 
www2 
 
remove 
 
194.215.205.19 
 
You want to remove search results where the host is a duplicate value. 
 

... | dedup host 
 


The results show the unique host names. 
 

host 
 

action 
 

client_ip 
 



213 
 
host 
 
action 
 
client_ip 
 
www1 
 
view 
 
211.166.11.101 
 
www2 
 
addtocart 
 
194.215.205.19 
 
www3 
 
view 
 
74.53.23.135 
 
This example returns only one result for each host value. 
 


You can specify more than one field with the dedup command. For example:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4881db61-90f5-466b-ae56-3460c6d2d1c0�h+)�}�(h}�(h/Xbwww2 
 
addtocart 
 
194.215.205.19 
 
www3 
 
view 
 
74.53.23.135 
 
This example returns only one result for each host value. 
 


You can specify more than one field with the dedup command. For example: 
 

... | dedup host, client_ip 
 

For each combination of host name and client IP address, duplicate results are removed. 
 

host 
 

action 
 

client_ip 
 
www1 
 
view 
 
211.166.11.101 
 
www2 
 
addtocart 
 
194.215.205.19 
 
www3 
 
view 
 
74.53.23.135 
 
www1 
 
addtocart 
 
128.241.220.82 
 
www1 
 
purchase 
 
64.66.0.20 
 
www3 
 
view 
 
107.3.146.207 
 
In this example, the result with host=www2 and client_ip=194.215.205.19 is removed. 
 

See also 
 

dedup command 
 

dedup command usage 
dedup command examples 
 


dedup command syntax details 
 

Syntax details 
 

The required syntax is in bold. 
 

dedup 
[<int>] 
 

[consecutive=<bool>] 
<field-list> 
 

Required arguments 
 

<field-list> 
 


214 
 
Description: A list of comma-separated field names to remove duplicate values from. You must specify at least 
one field. 
 

Optional arguments 
 

consecutive 
 

Description: If set to true, removes only events with duplicate combinations of values that are consecutive. 
Default: false 
 

<int> 
 


Syntax: <int> 
 

number for <int> must be greater than 0. If you do not specify a number, only the first occurring event is kept. All 
other duplicates are removed from the results. 
 


keepempty 
 

Description: If set to true, keeps every event where one or more of the specified fields is not present (null). 
Default: false. All events where any of the selected fields are null are dropped. 
 

The keepempty=true argument keeps every event that does not have one or more of the fields in the <field-list>. 
 



See also 
 

dedup command 
 

dedup command usage 
dedup command examples 
 


dedup command usage 
 
Avoid using the dedup command on the _raw field if you are searching over a large volume of data. If you search the _raw 
field, the text of every event in memory is retained which impacts your search performance. This is expected behavior. 
 


Differences between SPL and SPL2�h1h2h3}�h5Kuh�(h3h/�h}�ub�$83c7eb4f-da50-4a3f-a9e6-74c511477bfc�h+)�}�(h}�(h/Xfield, the text of every event in memory is retained which impacts your search performance. This is expected behavior. 
 


Differences between SPL and SPL2 
 

Command options must be specified first 
 

In SPL2, command options must be specified before the <field-list>. 
 

Version 
 

Example 
 
SPL 
 
... dedup host source 2 
 
SPL2 
 
... dedup 2 host, source 
 


215 
 
Version 
 
Example 
 

List of fields must be comma-delimited 
 

In SPL2, the list of fields must be comma-delimited. Otherwise a parsing error is returned. 
 

Version 
 

Example 
 
SPL 
 
... dedup host source 
 
SPL2 
 
... dedup host, source 
 


The sortby argument is not supported 
 

The sortby argument is not supported in SPL2. Use the sort command before the dedup command if you want to change 
the order of the events, which dictates which event is kept when the dedup command is run. 
 

Version 
 

Example 
 
SPL 
 
... dedup host source sortby -_size 
 
SPL2 
 
... sort -_size | dedup host, source 
 
Alternative: If you are using the from command, you can specify the ORDER BY clause instead of using the sort command. 
 

The keepevents argument is not supported 
 

The keepevents=<boolean> argument is not supported in SPL2. 
 

Version 
 

Example 
 
SPL 
 
... dedup host keepevents=true 
 
SPL2 
 
Not supported 
 
See also 
 

dedup command 
 

dedup command examples 
 


dedup command examples 
 
The following are examples for using the SPL2 dedup command. To learn more about the dedup command, see How the 
dedup command works. 
 

1. Remove duplicate results based on one field 
 

Remove duplicate search results with the same host value. 
 

... | dedup host 
 



216 
 
2. Keep the first 3 duplicate results 
 

For search results that have the same source value, keep the first 3 that occur and remove all subsequent results. 
 

... | dedup 3 source 
 

3. Sort events in ascending order before removing duplicate values 
 

Use the order by clause in the from command to sort the events by time in ascending order, the default order. Sorting the�)
h1h2h3}�h5Kuh�(h3h/�h}�ub�$c5149cf1-fbc6-41a1-af69-6588db8b6fe5�h+)�}�(h}�(h/X�3. Sort events in ascending order before removing duplicate values 
 

Use the order by clause in the from command to sort the events by time in ascending order, the default order. Sorting the 
events ensures that the oldest events are listed first. Remove duplicate results with the same source value. Only the 
oldest events are retained. 
 

| from main order by ASC _time | dedup source 
 

4. Sort events after removing duplicate values 
 

Remove duplicate search results with the same host value and sort the events by the _size field in descending order. 
 

... | dedup host | sort -_size 
 

5. Keep results that have the same combination of values in multiple fields 
 

For search results that have the same combination of source AND host values, keep the first 2 that occur and remove all 
subsequent results. 
 

... | dedup 2 source, host 
 

6. Remove only consecutive duplicate events 
 

Remove only consecutive duplicate events. Keep non-consecutive duplicate events. In this example duplicates must have 
the same combination of values the source and host fields. 
 

... | dedup consecutive=true source, host 
 

See also 
 

dedup command 
 

dedup command syntax details 
dedup command usage 
 















217 
 
eval command 
 


eval command overview 
 
The eval command calculates an expression and puts the resulting value into a search results field. 
 

• If the field name that you specify does not match a field in the output, a new field is added to the search results. 
 

eval expression overwrite the values in that field. 
 

The eval command evaluates mathematical, string, and boolean expressions. 
 

You can chain multiple eval expressions in one search using a comma to separate subsequent expressions. The search 
processes multiple eval expressions left-to-right and lets you reference previously evaluated fields in subsequent 
expressions. 
 

Syntax 
 

The required syntax is in bold. 
 

eval 
 


How the eval command works�h1h2h3}�h5Kuh�(h3h/�h}�ub�$46360518-af9d-41a4-be89-b22e3600c304�h+)�}�(h}�(h/Xexpressions. 
 

Syntax 
 

The required syntax is in bold. 
 

eval 
 


How the eval command works 
 

Most of the time the eval command is used to create a new field in your search results and the values in that new field are 
the result of an expression. There are many types of expressions you can specify. 
 

Using mathematical expressions 
 

One type of expression you can perform is a mathematical expression, such as multiplication, division, addition, and 
subtraction. 
 

Suppose you want to divide the values in one field by the values in another field. This example creates a new field called 
velocity in each event and calculate the velocity by dividing the values in the distance field by the values in the time 
field. 
 

... | eval velocity=distance/time 
 

Using eval functions 
 

There are dozens of built-in functions that you can use in the eval expression. The functions are organized into these 
categories: 
 

• Comparison and Conditional functions 
• Conversion functions 
 

• Date and Time functions 
• Informational functions 
 

218 
 
• JSON functions 
 

• Multivalue eval functions 
• Statistical eval functions 
• Text functions 
 


One common function is the if function. Suppose that you want to create a field called error and set the value in the 
error field to OK if the status value is 200. Otherwise set the error field value to Problem. 
 

... | eval error = if(status == 200, "OK", "Problem") 
 

Separate events into categories and calculate the count, minimum, maximum for each category 
 

This example uses recent earthquake data downloaded from the USGS Earthquakes website. The data is a comma separated ASCII text file 
that contains magnitude (mag), coordinates (latitude, longitude), region (place), and so forth, for each earthquake recorded. 
 
Earthquakes occurring at a depth of less than 70 km are classified as shallow-focus earthquakes, while those with a 
focal-depth between 70 and 300 km are commonly termed mid-focus earthquakes. In subduction zones, deep-focus�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c316f53a-f753-4e20-b79f-bc59967ba2c6�h+)�}�(h}�(h/Xfocal-depth between 70 and 300 km are commonly termed mid-focus earthquakes. In subduction zones, deep-focus 
 


To classify recent earthquakes based on their depth, you use the following search. 
 

FROM all_month | eval Description=case(depth<=70, "Shallow", depth>70 AND depth<=300, "Mid", depth>300, 
"Deep") | stats count() min(Mag) max(Mag) by Description 
 

The eval command is used to create a field called Description, which takes the value of "Shallow", "Mid", or "Deep" 
based on the Depth of the earthquake. The case() function is used to specify which ranges of the depth fits each 
description. For example, if the depth is less than 70 km, the earthquake is characterized as a shallow-focus quake; and 
the resulting Description is Shallow. 
 

The search also pipes the results of the eval command into the stats command to count the number of earthquakes and 
display the minimum and maximum magnitudes for each Description. 
 

The results look something like this: 
 

Description 
 

count 
 

min(Mag) 
 

max(Mag) 
 
Deep 
 
35 
 
4.1 
 
6.7 
 
Mid 
 
635 
 
0.8 
 
6.3 
 
Shallow 
 
6236 
 
-0.60 
 
7.70 
 
See also 
 

eval command 
 

eval command usage 
eval command examples 
 

Functions 
 




219 
 
Related Information 
 



eval command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

eval 
 


To specify multiple evaluations, separate each <assignment_expression> with a comma. 
 

Required arguments 
 

assignment_expression 
 

Description: The <field> is a destination field name for the result of the <expression>. If the field name already 
exists in your events, the eval command overwrites the values with the results of the <expression>. Otherwise the 
eval command creates a new field using <field>. The field name that you specify can't be a reserved word and 
can't include square brackets [ ]. See eval command usage. 
 

The <expression> is a <string> which can be a combination of values, variables, operators, and functions that are 
processed to determine the value to place in the destination <field>.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$36dd3db8-e944-460a-8d91-9e4369b9df74�h+)�}�(h}�(h/XThe <expression> is a <string> which can be a combination of values, variables, operators, and functions that are 
processed to determine the value to place in the destination <field>. 
 

◊ The <expression> is case-sensitive. The syntax of the <expression> is checked before running the 
	search, and an exception is returned for an invalid expression. 
 

evaluated successfully for a given event, the eval command erases the resulting field. 
 

surrounded by single quotation marks. For example, if the field name is server-1 you specify the field 
name like this  ...| eval new=count+'server-1'. 
 

quotation marks. For example, if the string you want to use is server- you specify the string like this ...| 
eval new="server-"+host. 
 

See also 
 

eval command 
 

eval command usage 
eval command examples 
 

Related information 
 







220 
 
eval command usage 
 

General 
 

You must specify a field name for the results that are returned from your eval command expression. You can specify a 
name for a new field or for an existing field. 
 

If the field name that you specify matches an existing field name, the values in the existing field are replaced by the 
results of the eval expression. 
 

If you specify a name for a new field, the name can't be a reserved word. For a list of the reserved words, see Reserved 
words. 
 

Numbers and strings can be assigned to fields, while booleans cannot be assigned. However you can convert booleans 
and nulls to strings using the tostring() function, which can be assigned to fields. 
 

If you are using a search as an argument to the eval command and functions, you cannot use a saved search name; you 
must pass a literal search string or a field that contains a literal search string (like the 'search' field extracted from 
index=_audit events). 
 

Boolean values 
 

Some evaluation functions return a Boolean value, such as the in or isint functions. While you can use these functions 
with the where or WHERE clause in the from command without issue, the eval command is a different matter.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8ed3d718-685c-4a27-ab24-49a1704edcce�h+)�}�(h}�(h/X�with the where or WHERE clause in the from command without issue, the eval command is a different matter. 
 

The eval command cannot accept a Boolean value directly. For functions that return a Boolean value, you must specify 
the function inside the another function, such as the if function, which can accept a Boolean value as an input. 
 

Numeric calculations 
 

During calculations, numbers are treated as double-precision floating-point numbers, subject to all the usual behaviors of 
floating point numbers. If the calculation results in the floating-point special value NaN(Not a Number), it is represented as 
"nan" in your results. The special values for positive and negative infinity are represented in your results as "inf" and "-inf" 
respectively. Division by zero results in a null field. 
 

Rounding 
 

Results are rounded to a precision appropriate to the precision of the input results. The precision of the results can be no 
greater than the precision of the least-precise input. For example, the following search has different precision for 0.2 in 
each of the calculations based on the number of zeros following the number 2: 
 

|makeresults | eval decimal1=8.250 * 0.2, decimal2=8.250 * 0.20, decimal3=8.250 * 0.200, exact=8.250 * 
exact(0.2) 
 

The results look like this: 
 

_time 
 

decimal1 
 

decimal2 
 

decimal3 
 

exact 
 
2022-09-02 21:53:30 
 
2 
 
1.7 
 
1.65 
 
1.650 
 



221 
 
If you want to return an arbitrary number of digits of precision, use the exact function, as shown the the last calculation in 
the search. 
 

Long numbers 
 

There are situations where the results of a calculation contain more digits than can be represented by a floating- point 
number. In those situations precision might be lost on the least significant digits. The limit to precision is 17 significant 
digits, or -2  +1 to 2  -1. 
 

Significant digits 
 

If a result returns a long number with more digits than you want to use, you can specify the number of digits to return�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aadb3467-6fc0-4c09-87c0-a98d8abad395�h+)�}�(h}�(h/X�digits, or -2  +1 to 2  -1. 
 

Significant digits 
 

If a result returns a long number with more digits than you want to use, you can specify the number of digits to return 
using the sigfig function. See Example 2 of the sigfig(X) function examples. 
 

Functions 
 

You can use a wide range of functions with the eval command. See Overview of SPL2 eval functions. 
 

Operators 
 

The following table lists the basic operations you can perform with the eval command. For these evaluations to work, the 
values need to be valid for the type of operation. For example, with the exception of addition, arithmetic operations might 
not produce valid results if the values are not numerical. When concatenating values, Splunk software reads the values as 
strings, regardless of the value. 
 

Type 
 

Operator 
 
Arithmetic 
 
+ - * / % 
 
Concatenation 
 
+ 
 
Boolean 
 
AND OR NOT XOR < > <= >=  != = == LIKE 
 


Operators that produce numbers 
 

• The plus ( + ) operator accepts two numbers for addition, or two strings for concatenation. 
 


Operators that produce strings 
 

• The plus ( + ) operator concatenates both strings and number. You must include a space on either side of the plus 
	( + ) operator. Numbers are concatenated in their string represented form. 
 

Operators that produce Booleans 
 

• The AND, OR, and XOR operators accept two Boolean values. 
 

or two strings. The single equal sign ( = ) is a synonym for the double equal sign ( ==). 
 

string LIKE pattern. The pattern operator supports literal text, a percent ( % ) character for a wildcard, and an 
underscore ( _ ) character for a single character match. For example, field LIKE "a%b_" matches any string 
 


222 
 
starting with a, followed by anything, followed by b, followed by one character. 
 

Field names 
 

If a field name begins with a number, you must enclose it in single quotation marks. 
 

To specify a field name with multiple words, you can either concatenate the words, or use single quotation marks when�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a09324ff-efd3-4f28-8495-7c43ec63d0c1�h+)�}�(h}�(h/X
To specify a field name with multiple words, you can either concatenate the words, or use single quotation marks when 
you specify the name. For example, to specify the field name "Account ID" you can specify 'AccountID' or 'Account ID'. 
 

To specify a field name with special characters, such as a period, use single quotation marks. For example, to specify the 
field name First.Name use 'First.Name'. 
 

Search event tokens 
 

If you are using the eval command in search event tokens, some of the evaluation functions might be unavailable or have 
a different behavior. 
 

Using wildcards 
 

You can use wildcards to match characters in string values. With the eval command, you must use the like function. 
 

• Use the percent ( % ) symbol as a wildcard for matching multiple characters 
• Use the underscore ( _ ) character as a wildcard to match a single character 
 

In this example, the eval command returns search results for values in the ipaddress field that start with 198. 
 

... | eval specificIP = like (ipaddress, "198.%" ) 
 

See the like (<str>, <pattern>) function in the list of Comparison and Conditional eval functions. 
 

Differences between SPL and SPL2 
 

Field names with special character must be in single quotes 
 

Field names that contain anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character, must be enclosed in single 
quotation marks. 
 

Version 
 

Example 1 
 

Example 2 
 
SPL 
 
eval something&strange = error 
 
eval "spaced field" = "value" 
 
SPL2 
 
eval 'something&strange' = error 
 
eval 'spaced field' = "value" 
 
The concatenation operator is the plus ( + ) sign 
 

In SPL2, the concatenation operator is the plus ( + ) sign. Use " " to include a space character as part of the 
concatenation. 
 

Version 
 

Example 1 
 

Example 2 
 
SPL 
 
...eval fullName = firstName.lastName 
 
...eval fullName = firstName" "." "lastName 
 
SPL2 
 
...eval fullName = firstName+lastName 
 
...eval fullName = (firstName+" "+lastName) 
 


223 
 
Use literals for true, false, and null�h1h2h3}�h5Kuh�(h3h/�h}�ub�$00697c29-0eb0-4896-94ab-cb0527402147�h+)�}�(h}�(h/X...eval fullName = firstName" "." "lastName 
 
SPL2 
 
...eval fullName = firstName+lastName 
 
...eval fullName = (firstName+" "+lastName) 
 


223 
 
Use literals for true, false, and null 
 

In SPL2, the true(), false(), and null() functions are removed. Use the literals true, false, and null instead of the 
functions. 
 

Version 
 

Example 
 
SPL 
 
...eval description=case(status==200,"OK", status==404, "Not found", true(), "Other") 
 
SPL2 
 
... eval description=case(status==200,"OK", status==404, "Not found", true, "Other") 
 
See also 
 

eval command 
 

eval command syntax details 
eval command examples 
 


eval command examples 
 
The following are examples for using the SPL2 eval command. To learn more about the eval command, see How the 
eval command works. 
 

Many of these examples use the evaluation functions. See Eval functions Quick Reference. 
 

1. Create a new field that contains the result of a calculation 
 

Create a new field called speed in each event. Calculate the speed by dividing the values in the distance field by the 
values in the time field. 
 

... | eval speed=distance/time 
 

2. Use the if function to analyze field values 
 

Create a new field called error in each event. Using the if function, set the value in the error field to OK if the status 
value is 200. Otherwise set the error field value to Problem. 
 

... | eval error = if(status == 200, "OK", "Problem") 
 

3. Convert values to lowercase 
 

Create a new field in each event called lowuser. Using the lower function, populate the field with the lowercase version of 
the values in the username field. 
 

... | eval lowuser = lower(username) 
 

4. Specify field names that contain dashes or other characters 
 

When a field name contains anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character, you must enclose the 
name in single quotation marks. This includes the wildcard ( * ) character. 
 



224 
 
This example shows how to specify a field name that includes a dash. The lower function is used to populate the lowuser�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8f5a3ec6-b4fa-4c96-884b-f5af1a739e94�h+)�}�(h}�(h/X�224 
 
This example shows how to specify a field name that includes a dash. The lower function is used to populate the lowuser 
field with the lowercase version of the values in the user-name field. 
 

... | eval lowuser = lower('user-name') 
 

5. Calculate the sum of the areas of two circles 
 

This example uses the pi and pow functions to calculate the area of two circles. A new field called sum_of_areas is created 
to store the sum of the areas of the two circles. 
 

... | eval sum_of_areas = pi() * pow(radius_a, 2) + pi() * pow(radius_b, 2) 
 

6. Return a string value based on the value of a field 
 

This example uses the case function to evaluate the value of the HTTP error codes in the error field. Based on the HTTP 
error codes, a text interpretation of the HTTP error codes is stored in a new field called error_msg. . 
 

... | eval error_msg = case(error == 404, "Not found", error == 500, "Internal Server Error", error == 200, 
"OK") 
 

7. Concatenate values from two fields 
 

Use the plus ( + ) sign to concatenate the values in first_name field with the values in the last_name field. Use quotation 
marks to insert a space character between the two names. When concatenating, the values are read as strings, 
regardless of the actual value. 
 

... | eval full_name = first_name+" "+last_name 
 

The concatenation operator accepts both strings and numbers. Numbers are concatenated as strings and produces a 
string. 
 

8. Separate multiple eval operations with a comma 
 

You can specify multiple eval operations by using a comma to separate the operations. In the following search the 
full_name evaluation uses the plus ( + ) sign to concatenate the values in the last_name field with the values in the 
first_name field. In this example, there is a comma and space between the last_name field and the first_name field. The 
low_name evaluation uses the lower function to convert the full_name evaluation into lowercase. 
 

... | eval full_name = last_name+", "+first_name, low_name = lower(full_name)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$44ed83df-3604-448f-acd3-44987272902f�h+)�}�(h}�(h/X�low_name evaluation uses the lower function to convert the full_name evaluation into lowercase. 
 

... | eval full_name = last_name+", "+first_name, low_name = lower(full_name) 
 

9. Convert a numeric field value to a string and include commas in the output 
 

Convert a numeric field value to a string. Specify that the string value display with commas. In this example replaces the 
values in an existing field x instead of creating a new field for the converted values. If the original value of x is 1000000, 
this search returns x as 1,000,000. 
 

... | eval x=tostring(x, "commas") 
 






225 
 
10. Include a currency symbol when you convert a numeric field value to a string 
 

Using the previous example, you can include a currency symbol at the beginning of the string. Instead of returning x as 
1,000,000, the search returns x as $1,000,000. 
 

... | eval x="$"+tostring(x, "commas") 
 

See also 
 

eval command 
 

eval command syntax details 
eval command usage 
 















































226 
 
eventstats command 
 


eventstats command overview 
 
Generates summary statistics from fields in your events and saves those statistics into a new field. The eventstats 
command places the generated statistics in new field that is added to the original raw events. 
 

Syntax 
 

The required syntax is in bold. 
 

eventstats 
[allnum=<bool>] 
<stats-agg-term>... 
[<by-clause>] 
 

How the eventstats command works 
 

It's much easier to see what the eventstats command does by showing you examples, using a set of simple events. 
 

These examples use the from command to create a set of events. The streamstats and eval commands are used to 
create additional fields in the events. 
 

Creating a set of events 
 

Let's start by creating a set of four events by using a dataset literal. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"city": "Seattle"}] | eval _time = now() | streamstats count()�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9f5dd733-55b6-426a-9504-12dc5171b71f�h+)�}�(h}�(h/XN| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"city": "Seattle"}] | eval _time = now() | streamstats count() 
 

• The from command is used to create four results, which contain the timestamp when the results where created. 
	The dataset literal specifies fields and values for four events. The fields are "age" and "city". 
 

• The streamstats command is used to create the count field. The streamstats command calculates a cumulative 
	count for each event, at the time the event is processed. 
 

The results of the search look like this: 
 

_time 
 

age 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
Seattle 
 
4 
 






227 
 
Using eventstats with a BY clause 
 

The BY clause in the eventstats command is optional, but is used frequently with this command. The BY clause groups 
the generated statistics by the values in a field. You can use any of the statistical functions with the eventstats command 
to generate the statistics. See the Stats and charting functions Quick Reference. 
 


In this example, the eventstats command generates the average age for each city. The generated averages are placed 
into a new field called avg(age). 
 

The following search is the same as the previous search, with the eventstats command added at the end: 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"city": "Seattle"}] | eval _time = now() | streamstats count() | eventstats avg(age) BY city 
 

• For San Francisco, the average age is 28 = (25 + 31) / 2. 
 

that average in every event for Seattle, including events that did not contain a value for age. 
 

The results of the search look like this: 
 

_time 
 

age 
 

avg(age) 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
28 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
28 
 
San Francisco 
 
3�h1h2h3}�h5Kuh�(h3h/�h}�ub�$2ce24584-19c4-4724-8908-4474add6ba0a�h+)�}�(h}�(h/Xj_time 
 

age 
 

avg(age) 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
28 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
28 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
39 
 
Seattle 
 
4 
 
Renaming the new field 
 

By default, the name of the new field that is generated is the name of the statistical calculation. In these examples, that 
name is avg(age). You can rename the new field using the AS keyword. 
 

In the following search, the eventstats command has been adjusted to rename the new field to average age by city. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"city": "Seattle"}] | eval _time = now() | streamstats count() | eventstats avg(age) AS 
'average age by city' BY city 
 

The results of the search look like this: 
 

_time 
 

age 
 

average age by city 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
28 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
28 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
39 
 
Seattle 
 
4 
 




228 
 
Events with text values 
 

The previous examples show how an event is processed that does not contain a value in the age field. Let's see how 
events are processed that contain an alphabetic character value in the field that you want to use to generate statistics. 
 

The following search includes the word test as a value in the age field. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"age":"test", "city": "Seattle"}] | eval _time = now() | streamstats count() 
 


The results of the search look like this: 
 

_time 
 

age 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
test 
 
Seattle 
 
4 
 

Let's add the eventstats command to the search. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San�h1h2h3}�h5Kuh�(h3h/�h}�ub�$147327a6-0a1f-4564-93fd-c513609d48c5�h+)�}�(h}�(h/X-3 
 
02 May 2022 18:32:07 
 
test 
 
Seattle 
 
4 
 

Let's add the eventstats command to the search. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"age":"test", "city": "Seattle"}] | eval _time = now() | streamstats count() | eventstats 
avg(age) BY city 
 


The alphabetic values are treated like null values. The results of the search look like this: 
 

_time 
 

age 
 

avg(age) 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
28 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
28 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
test 
 
39 
 
Seattle 
 
4 
 
Using the allnum argument 
 

But suppose you don't want statistics generated when there are alphabetic characters in the field or the field is empty? 
 

The allnum argument controls how the eventstats command processes field values. The default setting for the allnum 
argument is FALSE. Which means that the field used to generate the statistics does not need to contain all numeric 
values. Fields with empty values or alphabetic character values are ignored. You've seen this in the earlier examples. 
 

You can force the eventstats command to generate statistics only when the fields contain all numeric values. To 
accomplish this, you can set the allnum argument to TRUE. 
 

| from [{"age":25, "city": "San Francisco"}, {"age": 39, "city": "Seattle"}, {"age":31, "city": "San 
Francisco"}, {"age":"test", "city": "Seattle"}] | eval _time = now() | streamstats count() | eventstats 
allnum=true avg(age) BY city 
 

229 
 
The results of the search look like this: 
 

_time 
 

age 
 

avg(age) 
 

city 
 

count 
 
02 May 2022 18:32:07 
 
25 
 
28 
 
San Francisco 
 
1 
 
02 May 2022 18:32:07 
 
39 
 
Seattle 
 
2 
 
02 May 2022 18:32:07 
 
31 
 
28 
 
San Francisco 
 
3 
 
02 May 2022 18:32:07 
 
test 
 
Seattle 
 
4 
 
Because the age field contains values for Seattle that are not all numbers, the entire set of values for Seattle are ignored. 
No average is calculated.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0f2cdc81-9cfa-4242-b18b-7667aa4e06b4�h+)�}�(h}�(h/X3 
 
02 May 2022 18:32:07 
 
test 
 
Seattle 
 
4 
 
Because the age field contains values for Seattle that are not all numbers, the entire set of values for Seattle are ignored. 
No average is calculated. 
 

The allnum=true argument applies to empty values as well as alphabetic character values. 
 

See also 
 

eventstats command 
 

eventstats command usage 
eventstats command examples 
 

Other commands 
 

streamstats command overview 
 

Blogs 
 


Search commands > stats, eventstats and streamstats 
 


eventstats command syntax details 
 
The required syntax is in bold. 
 

Syntax 
 

eventstats 
[allnum=<bool>] 
 

[<by-clause>] 
 

The AS and BY keywords are displayed in uppercase in the syntax and examples to make the syntax easier to read. 
You can specify these keywords in uppercase or lowercase. 
 

Required arguments 
 

aggregation 
 



230 
 
Description: A statistical aggregation function. The function can be applied to an eval expression, or to a field or 
set of fields. You can specify multiple aggregation functions. Separate each aggregation function with a comma. 
 

By default, the name of the field added to the output is the same as your function. For example, if your search is 
... | eventstats avg(bytes) the field name in the output is avg(bytes). Use the AS clause to place the 
generated result into a new field with a name that you specify, for example ... | eventstats avg(bytes) AS 
'avg of bytes'. 
 

The syntax for the <aggregate-function> depends on the function that you use. See Statistical and charting 
functions Quick Reference for information about the statistical functions. 
 

Optional arguments 
 

allnum 
 


Syntax: allnum=<bool> 
 

are numerical. If you have a BY clause, the allnum argument applies to each group independently. 
Default: false 
 

by-clause 
 

Description: The name of one or more fields to group the results by. You can specify a time span to apply to the 
grouping. The <by-clause> returns one row for each distinct value in the <by-clause> fields. You cannot use the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5d341b0e-e7df-44a5-b070-d6e21e8643a9�h+)�}�(h}�(h/X�grouping. The <by-clause> returns one row for each distinct value in the <by-clause> fields. You cannot use the 
wildcard character to specify multiple fields with similar names. You must specify each field separately. 
 

over the entire incoming result set. 
 

See also 
 

eventstats command 
 

eventstats command usage 
eventstats command examples 
 


eventstats command usage 
 
The following sections contain information to help you understand and use the eventstats command. 
 

Differences between eventstats and stats 
 

The eventstats command is similar to the stats command. You can use both commands to generate aggregations like 
average, sum, and maximum. 
 

The differences between these commands are described in the following table: 
 

stats command 
 

eventstats command 
 
Events are transformed into a table of aggregated search 
results 
 
Aggregations are placed into a new field that is added to each of the events in 
your output 
 


231 
 
stats command 
 
eventstats command 
 
You can only use the fields in your aggregated results in 
subsequent commands in the search 
 
You can use the fields in your events in subsequent commands in your search, 
because the events have not been transformed 
 
How eventstats generates aggregations 
 

The eventstats command looks for events that contain the field that you want to use to generate the aggregation. The 
command creates a new field in every event and places the aggregation in that field. The aggregation is added to every 
event, even events that were not used to generate the aggregation. 
 

For example, you have 4 events and 3 of the events have the field you want to aggregate on, the eventstats command 
generates the aggregation based on the data in the 3 events. A new field is added all 4events and the aggregation is 
added to that field in every event. See eventstats command overview. 
 

Limitations and optimizations 
 

There are several default search limitations that might impact using the eventstats command:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c107c8bd-b5ba-497d-9101-aa47aa3abc6b�h+)�}�(h}�(h/X�added to that field in every event. See eventstats command overview. 
 

Limitations and optimizations 
 

There are several default search limitations that might impact using the eventstats command: 
 

• There is default limit to the amount of memory that the eventstats command can use to keep track of information 
	when processing a search. If the eventstats command reaches this limit, the command stops adding the 
	requested fields to the search results. 
 


You can avoid reaching these limit by filtering out events before you use the eventstats command in your search. 
 



Functions and memory usage 
 

Some functions are inherently more expensive, from a memory standpoint, than other functions. For example: 
 

• The distinct_count function requires far more memory than the count function. 
• The values and list functions also can consume a lot of memory. 
 

You can avoid running into memory issues by filtering out events before you use the eventstats command in your search. 
 

When to use the estimated distinct count function 
 

If you are using the distinct_count function without a BY clause field or with a low-cardinality field in the BY clause, 
consider replacing the distinct_count function with the estdc function (estimated distinct count). The estdc function can 
result in significantly lower memory usage and run times. 
 

Event order functions 
 

When you use the stats and eventstats commands to order events based on time, use the earliest and latest 
functions. 
 

• To locate the first value based on time order, use the earliest function. 
• To locate the last value based on time order, use the latest function. 
 

When searching events based on time, the first and last functions do not produce accurate results, 
 

232 
 
For more information about these functions, see Time functions. 
 

See also 
 

eventstats command 
 

eventstats command syntax details 
eventstats command examples 
 


eventstats command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ada315f3-bef6-457d-8ad1-b32101c42a4a�h+)�}�(h}�(h/X*232 
 
For more information about these functions, see Time functions. 
 

See also 
 

eventstats command 
 

eventstats command syntax details 
eventstats command examples 
 


eventstats command examples 
 
The following are examples for using the SPL2 eventstats command. To learn more about the eventstats command, see 
How the eventstats command works. 
 

Many of these examples use the statistical functions. See Overview of SPL2 stats and chart functions. 
 

Calculate the overall average duration 
 

Calculate the overall average duration and place the calculation in a new field called avgdur. Because no BY clause is 
specified, a single aggregation is created and added to every event. 
 

... | eventstats avg(duration) AS avgdur 
 

A new field called avgdur is created that field contains only one unique value. 
 

Calculate the average duration grouped by a specific field 
 

This example is the same as the previous example except that an average is calculated for each distinct value of the 
date_minute field. The new field avgdur is added to each event with the average value based on its particular value of 
date_minute. 
 

... | eventstats avg(duration) AS avgdur BY date_minute 
 

Search for spikes in the volume of errors 
 

This example searches for spikes in error volume in the status field. You can use this search to trigger an alert if the 
count of errors is higher than average. 
 

| search eventtype="error" | eventstats avg(status) AS avg | where status>avg 
 

See also 
 

eventstats command 
 

eventstats command syntax details 
eventstats command usage 
 

Blogs 
 


Search commands > stats, eventstats and streamstats 
 


233 
 
expand command 
 


expand command overview 
 
Use the expand command on a field that contains an array of values to produce a separate result row for each object in 
the array. If there are other fields in the original event, those field values are included in the new rows when the array is 
expanded. 
 

Syntax 
 

The required syntax is in bold. 
 

expand <object-field> 
 

How the expand command works�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8cd11792-8a9f-4e56-b5fd-3f96f8f27c3a�h+)�}�(h}�(h/Xexpanded. 
 

Syntax 
 

The required syntax is in bold. 
 

expand <object-field> 
 

How the expand command works 
 

The expand command works on fields that contain arrays. 
 

Consider the following array, which contains two objects with information about famous bridges in London, England: 
 


[ 
 

    {name:"Millennium Bridge", length:1066} 
] 
 
You can create an event for this array by using several clauses in the from command: 
 

• Use the FROM clause with an empty dataset literal to create an event with the _time field, which contains the 
	timestamp when the event was created. 
 

field called bridges for the array, and fields called city and country. 
 

The search to create the event looks like this: 
 

| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
AS bridges, "London" AS city, "England" AS country 
 

The event looks like this: 
 

_time 
 

bridges 
 

city 
 

country 
 
05 May 2022 2:29:02.000 
PM 
 
[{"name":"Tower Bridge","length":801},{"name":"Millennium 
Bridge","length":1066}] 
 

London 
 

England 
 
Expanding an array 
 

You can separate the objects in the array into individual results by using the expand command: 
 

| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
AS bridges, "London" AS city, "England" AS country | expand bridges 
 



234 
 
The results look like this: 
 

_time 
 

bridges 
 

city 
 

country 
 
05 May 2022 2:29:02.000 PM 
 
{"name":"Tower Bridge","length":801} 
 
London 
 
England 
 
05 May 2022 2:29:02.000 PM 
 
{"name":"Millennium Bridge","length":1066} 
 
London 
 
England 
 
All of the other fields remain unchanged and are duplicated in each result row. 
 

Flattening an object 
 

The expand command is often used with the flatten command. 
 

You can separate the values in the objects into individual fields by using the flatten command: 
 

| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ]�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6d7a180b-c661-4fcb-9bdd-28a97d766bf3�h+)�}�(h}�(h/XS| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
AS bridges, "London" AS city, "England" AS country | expand bridges | flatten bridges 
 


The results look like this: 
 

_time 
 

bridges 
 

city 
 

country 
 

length 
 

name 
 
05 May 2022 2:29:02.000 PM 
 
{"name":"Tower Bridge","length":801} 
 
London 
 
England 
 
801 
 
Tower Bridge 
 
05 May 2022 2:29:02.000 PM 
 
{"name":"Millennium Bridge","length":1066} 
 
London 
 
England 
 
1066 
 
Millennium Bridge 
 
The order of the field names in the output is lexicographical, which is alphabetical and case-sensitive. Internal fields 
come first, followed by uppercase letters, and finishing with lowercase letters. If you had named the field city instead of 
City, the city field would appear after the bridges field in the results. 
 

To learn more about lexicographical order, see Lexicographical order in the SPL2 Search Manual. 
 

See also 
 

expand command 
 

expand command usage 
expand command examples 
 

Related information 
 



expand command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

expand <object-field> 
 


235 
 
Required arguments 
 

object-field 
 

Description: The name of the field that contains the array of objects that you want to expand. 
 

Optional arguments 
 

None. 
 

See also 
 

expand command 
 

expand command usage 
expand command examples 
 


expand command usage 
 

Use with the flatten command 
 

The expand command is often used with the flatten command. 
 

For an example of how these two commands are used together, see expand command overview. 
For additional examples, see expand command examples and flatten command examples. 
 

Nested arrays 
 

You can expand nested arrays by using multiple sets of the expand and flatten commands. See expand command 
examples. 
 

See also 
 

expand command 
 

expand command syntax details 
expand command examples 
 


expand command examples 
 
The following are examples for using the SPL2 expand command. To learn more about the expand command, see How the 
expand command works.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f34bf7da-a091-46a9-b68e-1355cbfa25dc�h+)�}�(h}�(h/X�expand command examples 
 


expand command examples 
 
The following are examples for using the SPL2 expand command. To learn more about the expand command, see How the 
expand command works. 
 

1. Expanding nested arrays 
 

To show how to expand nested arrays, let's use this array, which contains information about famous bridges in Italy and 
China: 
 


236 
 
[ 
 

      [ 
 

         {name: "Ponte Vecchio Bridge", length: 276, city: "Florence"} 
 

     country: "Italy" 
 

   {famous_bridges: 
 

         {name: "Hangzhou Bay Bridge", length: 110880, city:"Jiaxing"}, 
 

      ], 
 

   } 
 

There is an outer array that contains two objects. Each object contains a set of key-value pairs. The first key is 
famous_bridges which has as an array as it's value. The second key is country, which has a string as it's value. 
 

Expand the outer array 
 

First you must expand the objects in the outer array. 
 

Use the FROM command with an empty dataset literal to create a timestamp field called _time in the event. Use the 
SELECT command to specify several fields in the event, including a field called bridges for the array. Add the expand 
command to separate out the nested arrays by country. 
 

The search to expand the outer array looks like this: 
 

|FROM [{}] SELECT _time, [ {famous_bridges: [{name: "Rialto Bridge", length: 157, city: "Venice"}, {name: 
"Ponte Vecchio Bridge", length: 276, city: "Florence"}], country: "Italy"}, {famous_bridges: [{name: 
"Hangzhou Bay Bridge", length: 110880, city:"Jiaxing"}, {name: "Nanpu Bridge", length: 27381, 
city:"Shanghai"}], country: "China"}] AS bridges | eval _time = now() | expand bridges 
 

The nested arrays becomes individual arrays. The results look like this: 
 

_time 
 

bridges 
 
13 Apr 2022 
2:42:17.000 PM 
 
{"famous_bridges":[{"name":"Rialto Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 
13 Apr 2022 
2:42:17.000 PM�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a35d3097-882b-40eb-9f59-4a01fc7fd5c1�h+)�}�(h}�(h/X.{"famous_bridges":[{"name":"Rialto Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 
13 Apr 2022 
2:42:17.000 PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 
The next step would be to flatten the fields in the bridges field. 
 

2. Flattening arrays that have been expanded 
 

You can separate the field-value pairs in the objects into individual fields by using the flatten command. 
 

Let's take the results from the previous example. The results look like this: 
 

_time 
 

bridges 
 



237 
 
_time 
 
bridges 
 
13 Apr 2022 
2:42:17.000 PM 
 
{"famous_bridges":[{"name":"Rialto Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 
13 Apr 2022 
2:42:17.000 PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 
Add the flatten command to the end of the search to flatten the bridges field: 
 

...| flatten bridges 
 

The two keys, famous_bridges and country, become field names. The values for these keys become values for the fields. 
For country, there is a single value. For famous_bridges, the value is an array of objects. 
 

The results look like this: 
 

_time 
 

bridges 
 

country 
 

famous_bridges 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 

China 
 
Expand and flatten the nested array fields 
 

To separate out the details for each bridge, you must expand and flatten the famous_bridges field, which contains the 
array.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$34720be9-690b-4043-ba97-ea5203a2a0eb�h+)�}�(h}�(h/XSChina 
 
Expand and flatten the nested array fields 
 

To separate out the details for each bridge, you must expand and flatten the famous_bridges field, which contains the 
array. 
 

Let's start with expanding the famous_bridges field. 
 

...| flatten bridges | expand famous_bridges 
 

When you expand the famous_bridges field, the results look like this: 
 

_time 
 

bridges 
 

country 
 

famous_bridges 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
 

Italy 
 

{"name":"Rialto 
Bridge","length":157,"city":"Venice"} 
 

13 Apr 2022 
3:00:03.000 
PM 
 

{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 


Italy 
 

{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"} 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 

China 
 

{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"} 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
 
China 
 
{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"} 
 


238 
 
_time 
 
bridges 
 
country 
 
famous_bridges 
 

Then add the flatten command to the end of the search: 
 

...| flatten bridges | expand famous_bridges | flatten famous_bridges 
 

When you flatten the famous_bridges field, the individual key-value pairs in the array are separated out into fields. The 
results look like this: 
 

When you expand the famous_bridges field, the results look like this: 
 

_time 
 

bridges 
 

city 
 

country 
 

famous_bridges 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Venice 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto�h1h2h3}�h5Kuh�(h3h/�h}�ub�$382c2961-ce2f-4d62-b8a0-3bbe9b475c07�h+)�}�(h}�(h/X!Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Venice 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Florence 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 

Jiaxing 
 

China 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 

Shanghai 
 

China 
 
You must expand and flatten each set of arrays. If a field contains four levels of nested arrays, then you must expand 
and flatten four times. 
 

Removing unwanted fields in the output 
 

When you expand and flatten arrays, especially nested arrays, you can end up with a lot of unnecessary fields in the 
output. 
 

For example, in this set of results, the bridges and famous_bridges fields are not really necessary. The details from each 
object have been placed in individual fields: 
 

_time 
 

bridges 
 

city 
 

country 
 

famous_bridges 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Venice 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Rialto 
Bridge","length":157,"city":"Venice"},{"name":"Ponte Vecchio 
Bridge","length":276,"city":"Florence"}],"country":"Italy"} 
 

Florence 
 

Italy 
 
13 Apr 2022 
3:00:03.000 
PM 
 
{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
 
Jiaxing 
 
China 
 


239 
 
_time 
 
bridges 
 
city 
 
country 
 
famous_bridges 
 

13 Apr 2022 
3:00:03.000 
PM 
 

{"famous_bridges":[{"name":"Hangzhou Bay�h1h2h3}�h5Kuh�(h3h/�h}�ub�$83484b17-1dea-4d57-9eb1-24f96c61fd7f�h+)�}�(h}�(h/X�Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
 
Jiaxing 
 
China 
 


239 
 
_time 
 
bridges 
 
city 
 
country 
 
famous_bridges 
 

13 Apr 2022 
3:00:03.000 
PM 
 

{"famous_bridges":[{"name":"Hangzhou Bay 
Bridge","length":110880,"city":"Jiaxing"},{"name":"Nanpu 
Bridge","length":27381,"city":"Shanghai"}],"country":"China"} 
 


Shanghai 
 


China 
 

To remove the unwanted fields, you can add the SELECT command to the end of your search and specify only the fields 
you want in the output. For example: 
 

...| flatten bridges | expand famous_bridges | flatten famous_bridges | SELECT _time, name, length, city, 
country 
 

The order that you specify the fields with the SELECT command is the order that the fields appear in the output: 
 

_time 
 

name 
 

length 
 

city 
 

country 
 
13 Apr 2022 3:00:03.000 PM 
 
Rialto Bridge 
 
157 
 
Venice 
 
Italy 
 
13 Apr 2022 3:00:03.000 PM 
 
Ponte Vecchio Bridge 
 
276 
 
Florence 
 
Italy 
 
13 Apr 2022 3:00:03.000 PM 
 
Hangzhou Bay Bridge 
 
110880 
 
Jiaxing 
 
China 
 
13 Apr 2022 3:00:03.000 PM 
 
Nanpu Bridge 
 
27381 
 
Shanghai 
 
China 
 
See also 
 

expand command 
 

expand command syntax details 
expand command usage 
 

Related information 
 


























240 
 
fields command 
 


fields command overview 
 
The fields command specifies which fields to keep or remove from the search results. 
 

By default, the internal fields _raw and _time are included in the output. 
 

Syntax 
 

The required syntax is in bold. 
 

fields [+|-] <field-list> 
 

How the fields command works 
 

Use the fields command to which specify which fields to keep or remove from the search results. Consider the following 
set of results: 
 

products 
 

quarter 
 

sales 
 

quota 
 

highest_region 
 

highest_seller 
 
ProductA 
 
QTR1 
 
1200 
 
1000 
 
EMEA 
 
Maria.Dubois@example.com 
 
ProductB 
 
QTR1 
 
1400 
 
1550 
 
EMEA 
 
David.Mayer@sample.net 
 
ProductC 
 
QTR1 
 
1650 
 
1275 
 
APAC 
 
Manish.Das@example.com 
 
ProductA 
 
QTR2 
 
1425 
 
1300 
 
NA 
 
stewart.mcintosh@sample.net 
 
ProductB 
 
QTR2 
 
1175 
 
1425 
 
EMEA 
 
masuda.bashir@example.com 
 
ProductC 
 
QTR2 
 
1550 
 
1450 
 
NA 
 
Claudia.Garcia@sample.net 
 
ProductA�h1h2h3}�h5Kuh�(h3h/�h}�ub�$eaef786f-35ae-4d92-bdce-6c9a08d0a6ee�h+)�}�(h}�(h/X�ProductA 
 
QTR2 
 
1425 
 
1300 
 
NA 
 
stewart.mcintosh@sample.net 
 
ProductB 
 
QTR2 
 
1175 
 
1425 
 
EMEA 
 
masuda.bashir@example.com 
 
ProductC 
 
QTR2 
 
1550 
 
1450 
 
NA 
 
Claudia.Garcia@sample.net 
 
ProductA 
 
QTR3 
 
1300 
 
1400 
 
APAC 
 
Wei.Zhang@example.com 
 
ProductB 
 
QTR3 
 
1250 
 
1125 
 
EMEA 
 
Maria.Dubois@example.com 
 
ProductC 
 
QTR3 
 
1375 
 
1475 
 
LATAM 
 
eduardo.rodriguez@sample.net 
 
ProductA 
 
QTR4 
 
1550 
 
1300 
 
NA 
 
Vanya.Patel@example.com 
 
ProductB 
 
QTR4 
 
1700 
 
1225 
 
APAC 
 
na.lui@sample.net 
 
ProductC 
 
QTR4 
 
1625 
 
1350 
 
EMEA 
 
Alex.Martin@oursample.de 
 
You decide to keep only the quarter and highest_seller fields in the results. You add the fields command to the 
search: 
 

... | fields quarter, hightest_seller 
 

The results appear like this: 
 

quarter 
 

highest_seller 
 


241 
 
quarter 
 
highest_seller 
 
QTR1 
 
Maria.Dubois@example.com 
 
QTR1 
 
David.Mayer@sample.net 
 
QTR1 
 
Manish.Das@example.com 
 
QTR2 
 
stewart.mcintosh@sample.net 
 
QTR2 
 
masuda.bashir@example.com 
 
QTR2 
 
Claudia.Garcia@sample.net 
 
QTR3 
 
Wei.Zhang@example.com 
 
QTR3 
 
Maria.Dubois@example.com 
 
QTR3 
 
eduardo.rodriguez@sample.net 
 
QTR4 
 
Vanya.Patel@example.com 
 
QTR4 
 
na.lui@sample.net 
 
QTR4 
 
Alex.Martin@oursample.de 
 
Alternatively, you decide to remove the quota and highest_seller fields from the results. You add this fields command 
to the search: 
 

... | fields - quota, hightest_seller 
 

The results appear like this: 
 



products 
 



quarter 
 



sales 
 



highest_region 
 
ProductA 
 
QTR1 
 
1200 
 
EMEA 
 
ProductB 
 
QTR1 
 
1400 
 
EMEA 
 
ProductC 
 
QTR1 
 
1650 
 
APAC 
 
ProductA 
 
QTR2 
 
1425 
 
NA 
 
ProductB 
 
QTR2 
 
1175 
 
EMEA 
 
ProductC 
 
QTR2 
 
1550 
 
NA 
 
ProductA 
 
QTR3 
 
1300 
 
APAC 
 
ProductB 
 
QTR3 
 
1250 
 
EMEA 
 
ProductC 
 
QTR3 
 
1375 
 
LATAM 
 
ProductA 
 
QTR4 
 
1550 
 
NA 
 
ProductB 
 
QTR4 
 
1700 
 
APAC 
 
ProductC 
 
QTR4 
 
1625 
 
EMEA 
 



242 
 
See also 
 

fields command 
 

fields command usage 
fields command examples 
 


fields command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

fields [+|-] <field-list> 
 

Required arguments 
 


Syntax: <field>, <field>, ...�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f4c9ed0a-5ae7-4a74-95b7-d37cc58b5742�h+)�}�(h}�(h/XRfields command usage 
fields command examples 
 


fields command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

fields [+|-] <field-list> 
 

Required arguments 
 


Syntax: <field>, <field>, ... 
 

names, but must enclose those field names in single quotation marks. For example ... | fields host, 
 
'server*' 
 

Optional arguments 
 

+ | - 
 


Syntax: + | - 
 

negative ( - ) symbol is specified, the fields in the field-list are removed from the results. The symbol you 
specify applies to all of the fields in the field-list. 
 


See also 
 

fields command 
 

fields command usage 
fields command examples 
 


fields command usage 
 

Internal fields 
 

The leading underscore is reserved for names of internal fields such as _raw and _time. By default, the internal fields _raw 
and _time are included in the search results. The fields command does not remove these internal fields unless you 
explicitly specify that the fields should not appear in the output. 
 

For example, to remove all internal fields, you specify: 
 

243 
 
... | fields - _* 
 

To exclude a specific field, such as _raw, you specify: 
 

... | fields - _raw 
 




Be cautious removing the _time field. Statistical commands, such as timechart, cannot display date or time information 
without the _time field. 
 

Differences between SPL and SPL2 
 

List of fields must be comma-delimited 
 

The list of fields must be comma-delimited. Otherwise a parsing error is returned. Because the include operator ( + ) is the 
default, it is not shown in these examples. 
 

Version 
 

Example 1 
 
SPL 
 
... fields userId ip 
 
SPL2 
 
... fields userId, ip 
 
Command options must be specified first 
 

Command options must be specified before command arguments. The exclude and include operators are command 
options. 
 

Version 
 

Example 1 
 
SPL 
 
... fields - host src 
 
SPL2 
 
... fields - host, src 
 
Field names with special character must be in single quotes 
 

Field names that contain anything other than a-z, A-Z, 0-9, or underscore ( _ ), need to be enclosed in single quotation 
marks. 
 

Version�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4147c789-0633-4a51-88da-0324bad9675c�h+)�}�(h}�(h/X�Field names with special character must be in single quotes 
 

Field names that contain anything other than a-z, A-Z, 0-9, or underscore ( _ ), need to be enclosed in single quotation 
marks. 
 

Version 
 

Example 1 
 
SPL 
 
... fields - "_*" host src 
 
SPL2 
 
... fields - '_*', host, src 
 


See also 
 

fields command 
 

fields command examples 
 




244 
 
fields command examples 
 
The following are examples for using the SPL2 fields command. To learn more about the fields command, see How the 
fields command works. 
 

1. Specify a list of fields to include in the search results 
 

Return only the host and src fields from the search results. 
 

... | fields host, src 
 



2. Specify a list of fields to remove from the search results 
 

Use the negative ( - ) symbol to specify which fields to remove from the search results. In this example, remove the host 
and ip fields from the results. 
 

... | fields - host, ip 
 



3. Remove all internal fields from the search results 
 

Internal fields are returned by default. All internal fields begin with an underscore character, for example _time. Use a wild 
card character ( * ) after the underscore to specify all internal fields. This example keep only the host and ip fields, and 
remove all of the internal fields. 
 

... | fields host, ip | fields - '_*' 
 



4. Remove specific internal fields from the search results 
 

Remove unwanted internal fields from the results. The fields to exclude are _raw, _indextime, _sourcetype, _subsecond, 
and _serial. 
 

| from _internal where sourcetype="splunkd" | head 5 | fields - _raw, _indextime, _sourcetype, _subsecond, 
_serial 
 



5. Store the results in a KV lookup dataset 
 

Keep the host and ip fields. Remove all internal fields from the search results. Store the results in a KV lookup dataset. 
 

...| fields host, ip | fields - '_*' | into myKVlookup 
 






245 
 
6. Use a wildcard to specify multiple fields that start with a similar name�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4af3d3a8-cf4b-41b1-9d99-81e38c573ed0�h+)�}�(h}�(h/X|...| fields host, ip | fields - '_*' | into myKVlookup 
 






245 
 
6. Use a wildcard to specify multiple fields that start with a similar name 
 

Keep only the fields source, sourcetype, host, and all fields that begin with error. Because a wildcard is used, the field 
name must be enclosed in single quotation marks. 
 

... | fields source, sourcetype, host, 'error*' 
 

See also 
 

fields command 
 

fields command syntax details 
fields command usage 
 















































246 
 
fieldsummary command 
 


fieldsummary command overview 
 
The fieldsummary command calculates summary statistics for one or more fields in your events. The summary 
information is displayed as a results table. 
 

Syntax 
 

The required syntax is in bold. 
 

fieldsummary 
[maxvals=<unsigned_int>] 
[fields="["<wc-field-list>"]" ] 
 

How the fieldsummary command works 
 

The fieldsummary command calculates summary statistics, such as the count, maximum value, minimum value, mean, 
and standard deviation for the fields in your search results. These summary statistics are displayed in a table for each 
field in your results or for the fields you specify with the fieldsummary command. 
 

For example, suppose you have the following visitor_log information: 
 

hour 
 

visitor_count 
 
0800 
 
0 
 
0900 
 
212 
 
1000 
 
367 
 
1100 
 
489 
 
1200 
 
624 
 
1300 
 
609 
 
1400 
 
492 
 
1500 
 
513 
 
1600 
 
367 
 
1700 
 
337 
 
1800 
 
104 
 
To return summary statistics for all of the fields in your search results, add the fieldsummary command to the end of your 
search: 
 

FROM visitor_log | fieldsummary 
 

The result looks similar to this: 
 

field 
 

count 
 

max 
 

mean 
 

min 
 

stdev 
 


247 
 
distinct_ 
	count 
 
	is_ 
exact 
 
numeric_ 
	count 
 
hour 
 
11 
 
11 
 
0 
 
1800 
 
1300 
 
800 
 
11 
 
331.6 
 
visitor_ 
count 
 

11 
 

10 
 

1 
 

624 
 

374 
 

0 
 

11 
 

201.1 
 
Insights into the summary fields 
 

The fieldsummary command returns 10 fields with summary information. 
 

Looking at the results shown in the previous example, notice a few things about these results: 
 

values field�h1h2h3}�h5Kuh�(h3h/�h}�ub�$afc0b9da-577e-4141-b08a-1870a5416399�h+)�}�(h}�(h/X�The fieldsummary command returns 10 fields with summary information. 
 

Looking at the results shown in the previous example, notice a few things about these results: 
 

values field 
 


◊ The entries in the values field are organized by count in descending order. You can see this clearly in the 
	visitor_count row. The value "367" has a count of "2". All of the other values have a count of "1". Even 
	though there are 11 values, only 10 are returned. This is because the default for the maxvals argument is 
	10. 
 

lexicographical order. You can see this clearly in the hours row. The values that start with 1, such as 
"1000" come before values that start with 8 or 9, such as "800". The value "900" is not returned because 
only the first 10 values are returned by default. For more information, see Lexicographical order in the 
SPL2 Search Manual. 
 

distinct_count field 
 

10 different values for the hours in the day. For the visitor_count row, there are 9 different values for the 
number of visitors. The value "367" appears for both the 1000 hour and the 1600 hour. 
 

is_exact field 
 


◊ This field specifies whether the count is an exact count or an approximate count of the distinct values in a 
	field. The value "1" indicates that the count is exact. The value "0" indicates that the count is an 
	approximate count. The maxvals argument controls whether the count is exact or approximate. In this 
	search, the maxvals argument is not specified so the default value for the maxvals argument is used. The 
	default value for the maxvals argument is 10. 
 

For more information about the fields returned from the fieldsummary command, see fieldsummary command usage. 
 

Optional arguments 
 

There are two optional arguments that you can use with the fieldsummary command, maxvals and fields. 
 

You can use the maxvals argument to specify how many distinct values you want returned from the search. If not 
specified, a maximum of 10 values is returned.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ee18285a-4d81-4608-a807-bbb7c841d932�h+)�}�(h}�(h/X�You can use the maxvals argument to specify how many distinct values you want returned from the search. If not 
specified, a maximum of 10 values is returned. 
 

You can use the fields argument to specify which fields you want summary information for. If not specified, summary 
information is returned for all of the fields in your search results. 
 

See also 
 

fieldsummary command 
 


248 
 
fieldsummary command usage 
fieldsummary command examples 
 


fieldsummary command syntax details 
 
The required syntax is in bold. 
 

fieldsummary 
[maxvals=<unsigned_int>] 
[fields="["<wc-field-list>"]" ] 
 

Required arguments 
 

fieldsummary 
 

Description: Returns the distinct values for every field in your events, unless you specify fields that you want 
summary information for by using the fields arguments. By default, the fieldsummary command returns a 
maximum of 10 distinct values. Use the maxvals argument to specify a different maximum. 
 

Optional arguments 
 

maxvals 
 

Description: Specifies the maximum distinct values to return for each field. This can't be a negative number. If 
you set maxvals = 0, all available distinct values for each field are returned, which can impact search 
performance. 
 


fields 
 



Syntax: fields=[ <wc-field>, <wc-field> ...] 
 

square brackets ( [ ] ). You can use the asterisk ( * ) as a wildcard to specify a list of fields with similar names. For 
example, if you want to specify all fields that start with "value", you can use a wildcard such as value*. 
 

See also 
 

fieldsummary command 
 

fieldsummary command usage 
fieldsummary command examples 
 


fieldsummary command usage 
 
The fieldsummary command displays the summary information in a results table. The following information appears in the 
results table: 
 

Summary field 
	name 
 

Description 
 

249 
 
field 
 
The field name in the event. 
 
count 
 
The number of events or results with that field. 
 
distinct_count 
 
The number of unique values in the field. 
 

is_exact�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f871a29e-8bb0-442b-94cc-5f09c9a28b1a�h+)�}�(h}�(h/X"name 
 

Description 
 

249 
 
field 
 
The field name in the event. 
 
count 
 
The number of events or results with that field. 
 
distinct_count 
 
The number of unique values in the field. 
 

is_exact 
 
Whether or not the count of the distinct field values is exact. If the number of distinct values of the field exceeds the 
maxvals value, then fieldsummary stops retaining all the distinct values and computes an approximate distinct count 
instead of an exact one. 1 means the distinct count is exact; 0 means the distinct count is not exact. 
 
max 
 
If the field is numeric, the maximum of its value. 
 
mean 
 
If the field is numeric, the mean of its values. 
 
min 
 
If the field is numeric, the minimum of its values. 
 
numeric_count 
 
The count of numeric values in the field. The count doesn't include null values. 
 
stdev 
 
If the field is numeric, the standard deviation of its values. 
 

values 
 
The distinct values of the field and count of each value. The values are sorted first by highest count and then by distinct 
value, in ascending order. 
 
Differences between SPL and SPL2 
 

Default maximum values returned has changed 
 

The default number of distinct values returned for a field is different in SPL2: 
 

Version 
 

Value 
 
SPL 
 
100 
 
SPL2 
 
10 
 
Field argument syntax is different 
 

The field argument in SPL2 has a different syntax than in SPL: 
 

Version 
 

Syntax 
 

Example 
 
wc-field-list 
 
SPL 
 
| fieldsummary action pid 
quantity 
 
A single field name or a space-delimited list of field names. 
 
field=[<field-list>] 
 

SPL2 
 


A single field name or a comma-delimited list of field names. The field 
names must be enclosed in square brackets [ ] . 
 
| fieldsummary fields=[action, 
pid, quantity] 
 
See also 
 

fieldsummary command 
 

fieldsummary command syntax details 
fieldsummary command examples 
 



250 
 
fieldsummary command examples 
 
The following are examples for using the SPL2 fieldsummary command. To learn more about the fieldsummary 
command, see How the fieldsummary command works.�c
h1h2h3}�h5Kuh�(h3h/�h}�ub�$be38bc1c-9688-417b-974a-30901e054c90�h+)�}�(h}�(h/X�250 
 
fieldsummary command examples 
 
The following are examples for using the SPL2 fieldsummary command. To learn more about the fieldsummary 
command, see How the fieldsummary command works. 
 

For a description of the summary information returned by the fieldsummary command, see fieldsummary command 
usage. 
 

1. Return summaries for all fields 
 

Consider the following data from a set of events in the orders dataset: 
 

_time 
 

clientip 
 

action 
 

pid 
 

quantity 
 

price 
 
20 Jan 2022 12:00 
 
192.0.2.0 
 
purchase 
 
DC-SG-G02 
 
1 
 
39.99 
 
20 Jan 2022 11:58 
 
addtochart 
 
MB-AG-G07 
 
3 
 
27.99 
 
20 Jan 2022 11:58 
 
203.0.113.0 
 
purchase 
 
WC-SH-A01 
 
1 
 
20 Jan 2022 11:56 
 
198.51.100.255 
 
changequantity 
 
PZ-SG-G05 
 
2 
 
4.99 
 
20 Jan 2022 11:51 
 
192.0.2.0 
 
purchase 
 
SF-BVS-01 
 
1 
 
49.99 
 
20 Jan 2022 11:47 
 
198.51.100.0 
 
purchase 
 
SF-BVS-G01 
 
1 
 
26.99 
 
20 Jan 2022 11:42 
 
192.0.2.0 
 
purchase 
 
WC-SH-T02 
 
2 
 
19.99 
 
20 Jan 2022 11:39 
 
198.51.100.0 
 
purchase 
 
PZ-SG-G05 
 
1 
 
4.99 
 
This search returns summaries for all fields in the orders dataset: 
 

| FROM orders | fieldsummary 
 

The following results are returned. The values for the mean and stdev fields are truncated, but look similar to this: 
 


field 
 


count 
 

distinct_ 
	count 
 

	is_ 
exact 
 


max 
 


mean 
 


min 
 

numeric_ 
	count 
 


stdev 
 


values 
 

action 
 

8 
 

3 
 

1 
 

0 
 
[{"value":"purchase","count":6}, 
{"value":"addtochart","count":1}, 
{"value":"changequantity","count":1}] 
 


clientip 
 


7 
 


4 
 


1 
 


0 
 
[{"value":"192.0.2.0","count":3}, 
{"value":"198.51.100.0","count":2}, 
{"value":"198.51.100.255","count":1}, 
{"value":"203.0.113.0","count":1}] 
 
pid 
 
8 
 
7 
 
1 
 
0 
 
[{"value":"PZ-SG-G05","count":2}, 
{"value":"DC-SG-G02","count":1}, 
{"value":"MB-AG-G07","count":1}, 
{"value":"SF-BVS-01","count":1}, 
{"value":"SF-BVS-G01","count":1}, 
{"value":"WC-SH-A01","count":1}, 
{"value":"WC-SH-T02","count":1}] 
 


251 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_ 
	count 
 
stdev 
 
values 
 




price 
 




7 
 




6 
 




1 
 




49.99 
 




24.99 
 




4.99 
 




7 
 




16.7 
 

[{"value":"4.99","count":2},�h1h2h3}�h5Kuh�(h3h/�h}�ub�$108cc6f1-c904-433b-8d14-744862b54ac9�h+)�}�(h}�(h/X	251 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_ 
	count 
 
stdev 
 
values 
 




price 
 




7 
 




6 
 




1 
 




49.99 
 




24.99 
 




4.99 
 




7 
 




16.7 
 

[{"value":"4.99","count":2}, 
{"value":"19.99","count":1}, 
{"value":"26.99","count":1}, 
{"value":"27.99","count":1}, 
{"value":"39.99","count":1}, 
{"value":"49.99","count":1}] 
 

quantity 
 

8 
 

3 
 

1 
 

3 
 

1.5 
 

1 
 

8 
 

0.7 
 
[{"value":"1","count":5}, 
{"value":"2","count":2}, 
{"value":"3","count":1}] 
 
For a description of the summary information returned by the fieldsummary command, see fieldsummary command 
usage. 
 

2. Return summaries for specific fields 
 

Consider the following data from a set of events in the orders dataset: 
 

_time 
 

clientip 
 

action 
 

pid 
 

quantity 
 

price 
 
20 Jan 2022 12:00 
 
192.0.2.0 
 
purchase 
 
DC-SG-G02 
 
1 
 
39.99 
 
20 Jan 2022 11:58 
 
addtochart 
 
MB-AG-G07 
 
3 
 
27.99 
 
20 Jan 2022 11:58 
 
203.0.113.0 
 
purchase 
 
WC-SH-A01 
 
1 
 
20 Jan 2022 11:56 
 
198.51.100.255 
 
changequantity 
 
PZ-SG-G05 
 
2 
 
4.99 
 
20 Jan 2022 11:51 
 
192.0.2.0 
 
purchase 
 
SF-BVS-01 
 
1 
 
49.99 
 
20 Jan 2022 11:47 
 
198.51.100.0 
 
purchase 
 
SF-BVS-G01 
 
1 
 
26.99 
 
20 Jan 2022 11:42 
 
192.0.2.0 
 
purchase 
 
WC-SH-T02 
 
2 
 
19.99 
 
20 Jan 2022 11:39 
 
198.51.100.0 
 
purchase 
 
PZ-SG-G05 
 
1 
 
4.99 
 
You can return summaries for all of the fields by including the fieldsummary command in your search without any other 
arguments. By default, a maximum of 10 values are returned for each field. 
 

However, most of the time you want to specify which fields you want the summaries for. This search returns summaries 
for the specified fields in the orders dataset. 
 

| FROM orders | fieldsummary fields=[action, pid, quantity] 
 


The following results are returned. The values for the mean and stdev fields are truncated, but look similar to this: 
 


field 
 


count 
 

distinct_ 
	count 
 

	is_ 
exact 
 


max 
 


mean 
 


min 
 

numeric_ 
	count 
 


stdev 
 


values 
 
action 
 
8 
 
3 
 
1 
 
0 
 
[{"value":"purchase","count":6}, 
{"value":"addtochart","count":1}, 
 


252 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3dce247f-ef3d-4931-a07d-d98330db7550�h+)�}�(h}�(h/X/	min 
 

numeric_ 
	count 
 


stdev 
 


values 
 
action 
 
8 
 
3 
 
1 
 
0 
 
[{"value":"purchase","count":6}, 
{"value":"addtochart","count":1}, 
 


252 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_ 
	count 
 
stdev 
 
values 
 





pid 
 





8 
 





7 
 





1 
 





0 
 

[{"value":"PZ-SG-G05","count":2}, 
{"value":"DC-SG-G02","count":1}, 
{"value":"MB-AG-G07","count":1}, 
{"value":"SF-BVS-01","count":1}, 
{"value":"SF-BVS-G01","count":1}, 
{"value":"WC-SH-A01","count":1}, 
{"value":"WC-SH-T02","count":1}] 
 

quantity 
 

8 
 

3 
 

1 
 

3 
 

1.5 
 

1 
 

8 
 

0.7 
 
[{"value":"1","count":5}, 
{"value":"2","count":2}, 
{"value":"3","count":1}] 
 
Notice that the results are sorted by the field column in ascending order. In the values column, the values are sorted first 
by highest count and then by distinct value, in ascending order. 
 

3. Using wildcards when specifying field names 
 

When you use wildcards to search for field names, you must enclose the field name in single quotation marks. For more 
information, see Quotation marks in the SPL2 Search Manual. 
 

Consider the following data from a set of events in the hosts dataset: 
 

_time 
 

host 
 

average_kbps 
 

instanenous_kbps 
 

kbps 
 
14 Feb 2022 12:00 
 
danube.sample.com 
 
2.643 
 
1.865 
 
3.420 
 
14 Feb 2022 11:53 
 
mekong.buttercupgames.com 
 
0.710 
 
0.164 
 
1.256 
 
14 Feb 2022 11:47 
 
danube.sample.com 
 
1.325 
 
0.419 
 
2.230 
 
14 Feb 2022 11:42 
 
yangtze.buttercupgames.com 
 
2.249 
 
0.000 
 
2.249 
 
14 Feb 2022 11:39 
 
nile.example.net 
 
2.874 
 
3.841 
 
1.906 
 
14 Feb 2022 11:33 
 
nile.example.net 
 
2.023 
 
0.915 
 
3.130 
 
This search returns summaries for fields in the hosts dataset with names that contain "kbps": 
 

FROM hosts| fieldsummary fields=[host, '*kbps*'] 
 


The results look similar to this: 
 


field 
 


count 
 

distinct_ 
	count 
 

	is_ 
exact 
 


max 
 


mean 
 


min 
 

numeric_ 
	count 
 


stdev 
 
average_ 
kbps 
 

6 
 

6 
 

1 
 

2.874 
 

1.9 
 

0.71 
 

6 
 

0.8 
 
host 
 
6 
 
4 
 
1 
 
0 
 
instanenous_kbps 
 
6 
 
6 
 
1 
 
3.841 
 
1.2 
 
0.0 
 
6 
 
1.4 
 
kbps 
 
6 
 
6 
 
1 
 
3.42 
 
2.3 
 
1.256 
 
6 
 
0.7 
 


253 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_�h1h2h3}�h5Kuh�(h3h/�h}�ub�$90b84edb-ccb4-4521-8bc8-09bfdec44729�h+)�}�(h}�(h/X	0.71 
 

6 
 

0.8 
 
host 
 
6 
 
4 
 
1 
 
0 
 
instanenous_kbps 
 
6 
 
6 
 
1 
 
3.841 
 
1.2 
 
0.0 
 
6 
 
1.4 
 
kbps 
 
6 
 
6 
 
1 
 
3.42 
 
2.3 
 
1.256 
 
6 
 
0.7 
 


253 
 
field 
 
count 
 
distinct_ 
	count 
 
	is_ 
exact 
 
max 
 
mean 
 
min 
 
numeric_ 
	count 
 
stdev 
 

4. Specifying the number of values to return 
 

By default, the fieldsummary command returns a maximum of 10 values. Use the maxvals argument to specify the number 
of values you want returned. 
 

Consider the following data from a set of events in the hosts dataset: 
 

_time 
 

host 
 

average_kbps 
 

instanenous_kbps 
 

kbps 
 
14 Feb 2022 12:00 
 
danube.sample.com 
 
2.643 
 
1.865 
 
3.420 
 
14 Feb 2022 11:53 
 
mekong.buttercupgames.com 
 
0.710 
 
0.164 
 
1.256 
 
14 Feb 2022 11:47 
 
danube.sample.com 
 
1.325 
 
0.419 
 
2.230 
 
14 Feb 2022 11:42 
 
yangtze.buttercupgames.com 
 
2.249 
 
0.000 
 
2.249 
 
14 Feb 2022 11:39 
 
nile.example.net 
 
2.874 
 
3.841 
 
1.906 
 
14 Feb 2022 11:33 
 
nile.example.net 
 
2.023 
 
0.915 
 
3.130 
 
This search returns summaries for fields in the hosts dataset with names that contain "kbps" and returns a maximum of 2 
values: 
 

FROM hosts| fieldsummary fields=[host, 'kbps*'] maxvals=2 
 


The results look similar to this: 
 


field 
 


count 
 

distinct_ 
	count 
 

	is_ 
exact 
 


max 
 


mean 
 


min 
 

numeric_ 
	count 
 


stdev 
 


values 
 
average_ 
kbps 
 

6 
 

6 
 

1 
 

2.874 
 

1.9 
 

0.71 
 

6 
 

0.8 
 
host 
 
6 
 
4 
 
1 
 
0 
 
instanenous_kbps 
 
6 
 
6 
 
1 
 
3.841 
 
1.2 
 
0.0 
 
6 
 
1.4 
 
kbps 
 
6 
 
6 
 
1 
 
3.42 
 
2.3 
 
1.256 
 
6 
 
0.7 
 
The values are sorted first by highest count and then by distinct value, in ascending order. Compare this with the results 
returned in the example Using wildcards when specifying field names. 
 

5. Returning summaries for object members in a field 
 

Consider the following data in the supply_orders dataset. The address field contains an object with key-value members: 
 

supplier_ID 
 

supplier_name 
 

address 
 

orders 
 
1009 
 
Mile High Games 
 
{"city":"Denver", "state/province":"Colorado", "country":"United States"} 
 
45 
 
1238 
 
Area 51 Games 
 
{"city":"Roswell", "state/province":"New Mexico", "country":"United States"} 
 
21 
 
4111�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aabccc7f-0fa3-49b8-8484-e986f857ce07�h+)�}�(h}�(h/X�{"city":"Denver", "state/province":"Colorado", "country":"United States"} 
 
45 
 
1238 
 
Area 51 Games 
 
{"city":"Roswell", "state/province":"New Mexico", "country":"United States"} 
 
21 
 
4111 
 
Isthmus Pastimes 
 
{"city":"Panama City", "state/province":"Panama","country":"Panama"} 
 
7 
 

254 
 
supplier_ID 
 
supplier_name 
 
address 
 
orders 
 

5007 
 

EuroToys 
 

{"city":"Prague", "state/province":"Central Bohemia", "country":"Czech Republic"} 
 

15 
 
1238 
 
Area 51 Games 
 
{"city":"Roswell", "state/province":"New Mexico", "country":"United States"} 
 
6 
 
5020 
 
Blarney Games 
 
{"city":"Dublin", "state/province":"Dublin", "country":"Ireland"} 
 
23 
 
5007 
 
EuroToys 
 
{"city":"Prague", "state/province":"Central Bohemia", "country":"Czech Republic"} 
 
39 
 
5007 
 
EuroToys 
 
{"city":"Prague", "state/province":"Central Bohemia", "country":"Czech Republic"} 
 
18 
 
Use the following search to return the supplier ID and the city names from the object in the address field: 
 

| FROM supply_orders | fieldsummary fields=[supplier_ID, address.city] 
 

The following results are returned. The values for the mean and stdev fields are truncated, but look similar to this: 
 


field 
 


count 
 

distinct_ 
	count 
 

	is_ 
exact 
 


max 
 


mean 
 


min 
 

numeric_ 
	count 
 


stdev 
 

city 
 

8 
 

5 
 

1 
 

0 
 

supplier_ID 
 

8 
 

5 
 

1 
 

5020 
 

3454.6 
 

1009 
 

8 
 

1924.2 
 
See also 
 

fieldsummary command 
 

fieldsummary command syntax details 
fieldsummary command usage 
 




























255 
 
flatten command 
 


flatten command overview 
 
Use the flatten command on an object to convert the key-value pairs in the object into separate fields in an event. The 
flatten command can flatten only the first level of an object, see flatten command usage. 
 

Syntax 
 

The required syntax is in bold. 
 

flatten <object> 
 

How the flatten command works 
 

The following object contains information about the Tower Bridge in London, England: 
 


{name: "Tower Bridge", length: 801} 
 
You use the flatten command to create separate fields from the key-value pairs in the object. 
 

Consider the following search:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1246fb38-609b-4977-8894-dea29477b70a�h+)�}�(h}�(h/X){name: "Tower Bridge", length: 801} 
 
You use the flatten command to create separate fields from the key-value pairs in the object. 
 

Consider the following search: 
 

| FROM [{}] SELECT _time, {name: "Tower Bridge", length: 801} as bridges, "London" AS City, "England" AS 
Country | flatten bridges 
 

• Using an empty dataset literal with the from command produces a timestamp in the _time field. 
 

following elements: 
 

♦ Values with named fields like "London" AS City 
♦ Arrays of objects 
 

The results look like this: 
 

_time 
 

City 
 

Country 
 

bridges 
 

length 
 

name 
 
08 Mar 2022 3:43:48.000 PM 
 
London 
 
England 
 
{"name":"Tower Bridge","length":801} 
 
801 
 
Tower Bridge 
 
The order of the field names in the output is lexicographical, which is alphabetical and case-sensitive. Internal fields 
come first, followed by uppercase letters, and finishing with lowercase letters. If you had named the field city instead of 
City, the city field would appear after the bridges field in the results. 
 

To learn more about lexicographical order, see Lexicographical order in the SPL2 Search Manual. 
 

You can use the flatten command with arrays of objects as well single objects. For additional examples, see flatten 
command examples. 
 




256 
 
See also 
 

flatten command 
 

flatten command usage 
flatten command examples 
 


flatten command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

flatten <object-field> 
 

Required arguments 
 

object-field 
 

Description: The name of the field that contains an object, whose key-value pairs you want to promote into 
individual fields. 
 

Optional arguments 
 

None. 
 

See also 
 

flatten command 
 

flatten command usage 
flatten command examples 
 


flatten command usage 
 

Flattening nested objects 
 

The flatten command can flatten only the first level of an object. For example, when an object such {a: {b: 2}} is 
flattened a field called a is created with a value {b: 2}. 
 

To flatten nested objects, use the expand command with the flatten command.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ca3e5ce6-c469-4525-aa7d-d262def4e9b8�h+)�}�(h}�(h/XEflattened a field called a is created with a value {b: 2}. 
 

To flatten nested objects, use the expand command with the flatten command. 
 

For an example of how these two commands are used together, see flatten command examples and expand command 
examples. 
 





257 
 
Field order in the output 
 

When you flatten the values in an object, fields are created in the search results. The order of the fields displayed in the 
output is lexicographical. Lexicographical order means that numbers come before letters and uppercase letters come 
before lowercase letters. 
 

For example, suppose you have the following object: 
 


{name: "Akashi-Kaikyo Bridge", length: 12800, city: "Kobe", country: "Japan", Opened: 1998} 
 
When the object is flattened, the order of the fields are rearranged to this: 
 

• Opened 
• city 
 

• length 
• name 
 

The output looks like this: 
 

Opened 
 

city 
 

country 
 

length 
 

name 
 
1998 
 
Kobe 
 
Japan 
 
12800 
 
Akashi-Kaikyo Bridge 
 
To learn more about lexicographical order, see Lexicographical order in the SPL2 Search Manual. 
 

See also 
 

flatten command 
 

flatten command syntax details 
flatten command examples 
 


flatten command examples 
 
The following examples use the SPL2 flatten command. To learn more about the flatten command, see How the flatten 
command works. 
 

The flatten command is often used with the expand command when you want to flatten arrays or nested objects. 
 

1. Flatten individual objects 
 

You can flatten a field that contains a single object of key-value pairs. 
 

Consider the following search: 
 

| FROM [{}] SELECT _time, {name: "Helix Bridge", length: 918, country: "Singapore"} as bridges 
 

This search uses several clauses in the from command: 
 



258 
 
• Use the FROM clause with an empty dataset literal to create an event with the _time field, which contains the 
	timestamp when the event was created. 
 

918, country: "Singapore"}. 
 

The result looks like this: 
 

_time 
 

bridges 
 
08 Mar 2022 3:45:25.000 PM 
 
{name: "Helix Bridge", length: 918, country: "Singapore"}�h1h2h3}�h5Kuh�(h3h/�h}�ub�$939f0419-fca2-46e4-81ab-d239a04bff42�h+)�}�(h}�(h/X@918, country: "Singapore"}. 
 

The result looks like this: 
 

_time 
 

bridges 
 
08 Mar 2022 3:45:25.000 PM 
 
{name: "Helix Bridge", length: 918, country: "Singapore"} 
 
When you add the flatten command, you must specify the field to flatten: 
 

| FROM [{}] SELECT _time, {name: "Helix Bridge", length: 918, country: "Singapore"} as bridges | flatten 
bridges 
 

The result looks like this: 
 

_time 
 

bridges 
 

country 
 

length 
 

name 
 
08 Mar 2022 3:45:25.000 PM 
 
{name: "Helix Bridge", length: 918, country: "Singapore"} 
 
Singapore 
 
918 
 
Helix Bridge 
 
2. Flattening arrays 
 

The following array contains two objects with information about bridges in London, England. 
 


[ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
 
Consider the following search: 
 

| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
as bridges, "London" AS City, "England" AS Country 
 

This search uses several clauses in the from command: 
 

• Use the FROM clause with an empty dataset literal to create an event with the _time field, which contains the 
	timestamp when the event was created. 
 

♦ Arrays of objects like [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 
 
♦ Individual objects like {name: "Tower Bridge", length: 801} 
♦ Values with named fields like "London" AS City 
 

The results look like this: 
 

_time 
 

City 
 

Country 
 

bridges 
 
08 Mar 2022 3:45:25.000 
PM 
 

London 
 

England 
 
[{"name":"Tower Bridge","length":801},{"name":"Millennium 
Bridge","length":1066}] 
 
Expand arrays into objects 
 

Before you can use the flatten command, you must first expand the array into separate objects. 
 

This is the search: 
 

259 
 
| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
as bridges, "London" AS City, "England" AS Country | expand bridges 
 

Each object is separated into its own search result. The results look like this: 
 

_time 
 

City 
 

Country 
 

bridges�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d966859b-f1cb-4965-9359-0617deeb442f�h+)�}�(h}�(h/X6as bridges, "London" AS City, "England" AS Country | expand bridges 
 

Each object is separated into its own search result. The results look like this: 
 

_time 
 

City 
 

Country 
 

bridges 
 
08 Mar 2022 3:44:57.000 PM 
 
London 
 
England 
 
{"name":"Tower Bridge","length":801} 
 
08 Mar 2022 3:44:57.000 PM 
 
London 
 
England 
 
{"name":"Millennium Bridge","length":1066} 
 
Flatten objects into fields 
 

You can use the flatten command to create separate fields from the key-value pairs in the objects: 
 

| FROM [{}] SELECT _time, [ {name: "Tower Bridge", length: 801}, {name: "Millennium Bridge", length: 1066} ] 
as bridges, "London" AS City, "England" AS Country | expand bridges | flatten bridges 
 


The results look like this: 
 

_time 
 

City 
 

Country 
 

bridges 
 

length 
 

name 
 
08 Mar 2022 3:43:48.000 PM 
 
London 
 
England 
 
{"name":"Tower Bridge","length":801} 
 
801 
 
Tower Bridge 
 
08 Mar 2022 3:43:48.000 PM 
 
London 
 
England 
 
{"name":"Millennium Bridge","length":1066} 
 
1066 
 
Millennium Bridge 
 
3. Flatten nested objects 
 

To show how to flatten nested arrays, let's use this array, which contains information about popular board games: 
 


[ 
 

      [ 
 

         {name: "Pandemic", players: "2-4"}, 
 

      ], 
 

   }, 
 

      [ 
 

         {name: "Ticket to Ride", players: "2-5"} 
 

     type: "competitive" 
 

] 
 
There is an outer array that contains two objects. Each object contains a set of key-value pairs. The first key is games 
which has an array as its value. The second key is type, which has a string as its value. 
 

Expand the outer array 
 

First you must expand the objects in the outer array using a search that looks like this: 
 

| FROM [{}] SELECT _time, [{games: [ {name: "Forbidden Island", players: "2-4"}, {name: "Pandemic", players: 
"2-4"},{name: "Sherlock Holmes: Consulting Detective", players: "1-8"}], type: "cooperative"}, {games: 
 

260 
 
[{name: "Settlers of Catan", players: "3-4"}, {name: "Ticket to Ride", players: "2-5"}], type: 
"competitive"}] AS boardgames | expand boardgames�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f7215157-99b0-491a-b2eb-85aa8d16e6d5�h+)�}�(h}�(h/X260 
 
[{name: "Settlers of Catan", players: "3-4"}, {name: "Ticket to Ride", players: "2-5"}], type: 
"competitive"}] AS boardgames | expand boardgames 
 

The outer objects become individual events. The results look like this: 
 

_time 
 

boardgames 
 

08 Mar 2022 
2:42:17.000 PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock Holmes: Consulting 
Detective","players":"1-8"}],"type":"cooperative"} 
 
08 Mar 2022 
2:42:17.000 PM 
 
{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 
Flatten to separate the objects 
 

You must flatten the fields, games and type, out of the outer objects. 
 

Add the flatten command to the end of the search to flatten the boardgames field: 
 

...| flatten boardgames 
 

The two keys, games and type, become field names. The values for these keys become values for the fields. For the 
type field, there is a single value. For the games field, the value is an array of objects. 
 

The results look like this: 
 

_time 
 

boardgames 
 
08 Mar 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 
08 Mar 2022 
2:42:17.000 
PM 
 
{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 
Expand and flatten the nested array fields 
 

To separate out the details for each game, you must expand and flatten the games field, which contains the array. 
 

Start with expanding the games field. 
 

...| flatten boardgames | expand games 
 

When you expand the games field, the results look like this: 
 

_time 
 

boardgames 
 

games 
 
08 Mar 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Forbidden�h1h2h3}�h5Kuh�(h3h/�h}�ub�$284b170f-7182-49e1-91fa-423d126c79b9�h+)�}�(h}�(h/X7{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Forbidden 
Island","players":"2-4"} 
 
08 Mar 2022   {"games":[{"name":"Forbidden 
 



261 
 
_time 
 
boardgames 
 
games 
 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 
08 Mar 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 
{"name":"Sherlock Holmes: 
Consulting 
Detective","players":"1-8"} 
 
08 Mar 2022 
2:42:17.000 
PM 
 
{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 
{"name":"Settlers of 
Catan","players":"3-4"} 
 
08 Mar 2022 
2:42:17.000 
PM 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 

{"name":"Ticket to 
Ride","players":"2-5"} 
 
Then add the flatten command to the end of the search: 
 

...| flatten boardgames | expand games | flatten games 
 

When you flatten the games field, the individual key-value pairs in the array are separated out into fields. The results look 
like this: 
 

_time 
 

boardgames 
 

games 
 
08 Mar 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Forbidden 
Island","players":"2-4"} 
 
08 Mar 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

08 Mar 2022 
3:00:03.000 
PM 
 

{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Sherlock Holmes:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3316ec13-65b2-449e-8aa3-70bddccaf7ea�h+)�}�(h}�(h/XIsland","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Sherlock Holmes: 
Consulting 
Detective","players":"1-8"} 
 

08 Mar 2022 
2:42:17.000 
PM 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 

{"name":"Settlers of 
Catan","players":"3-4"} 
 
08 Mar 2022 
2:42:17.000 
PM 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 

{"name":"Ticket to 
Ride","players":"2-5"} 
 
You must expand and flatten each set of arrays. If a field contains four levels of nested arrays, then you must expand 
and flatten four times. 
 

4. Removing unwanted fields in the output 
 

When you expand and flatten arrays, especially nested arrays, you can end up with a lot of unnecessary fields in the 
output. 
 

For example, in this set of results, the boardgames and games fields are not really necessary. The details from each object 
have been placed in individual fields for name, players, and type of game. 
 


262 
 
_time 
 
boardgames 
 
games 
 
21 Apr 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Forbidden 
Island","players":"2-4"} 
 
21 Apr 2022 
3:00:03.000 
PM 
 
{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

21 Apr 2022 
3:00:03.000 
PM 
 

{"games":[{"name":"Forbidden 
Island","players":"2-4"},{"name":"Pandemic","players":"2-4"},{"name":"Sherlock 
Holmes: Consulting Detective","players":"1-8"}],"type":"cooperative"} 
 

{"name":"Sherlock Holmes: 
Consulting 
Detective","players":"1-8"} 
 

21 Apr 2022 
2:42:17.000 
PM 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ee34c554-8252-47ce-930c-792caaf0e654�h+)�}�(h}�(h/X?{"name":"Sherlock Holmes: 
Consulting 
Detective","players":"1-8"} 
 

21 Apr 2022 
2:42:17.000 
PM 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 

{"name":"Settlers of 
Catan","players":"3-4"} 
 
21 Apr 2022 
2:42:17.000 
 

{"games":[{"name":"Settlers of Catan","players":"3-4"},{"name":"Ticket to 
Ride","players":"2-5"}],"type":"competitive"} 
 

{"name":"Ticket to 
Ride","players":"2-5"} 
 
To remove the unwanted fields, you can add the SELECT clause to the end of your search and specify only the fields you 
want in the output. For example: 
 

...| SELECT _time, type, name, players 
 

The order that you specify the fields with the SELECT clause is the order that the fields appear in the output: 
 

_time 
 

type 
 

name 
 

players 
 
21 Apr 2022 3:00:03.000 PM 
 
cooperative 
 
Forbidden Island 
 
2-4 
 
21 Apr 2022 3:00:03.000 PM 
 
cooperative 
 
Pandemic 
 
2-4 
 
21 Apr 2022 3:00:03.000 PM 
 
cooperative 
 
Sherlock Holmes: Consulting Detective 
 
1-8 
 
21 Apr 2022 2:42:17.000 PM 
 
competitive 
 
Settlers of Catan 
 
3-4 
 
21 Apr 2022 2:42:17.000 PM 
 
competitive 
 
Ticket to Ride 
 
2-5 
 
See also 
 

flatten command 
 

flatten command syntax details 
flatten command usage 
 

expand command 
 










263 
 
from command 
 


from command overview 
 
Use the SPL2 from command to retrieve data from a dataset, such as an index, metric index, lookup, view, or job. 
 

The from command is the primary command used to read data out of a dataset, such as an index, metric index, lookup, 
view, or job. The from command has optional clauses to filter, aggregate, project, and order the data. 
 

The from command has a flexible syntax, which enables you to start a search with either the FROM clause or the SELECT 
clause. For example, these two searches are identical and return the exact same results: 
 

Start with the FROM clause 
 

Start with the SELECT clause 
 
| FROM main 
 
| SELECT sum(bytes) AS sum, host 
 

WHERE earliest=-5m@m GROUP BY host 
 

FROM main WHERE earliest=-5m@m�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3a5f873d-776c-4a60-a433-95316d47c080�h+)�}�(h}�(h/X6Start with the FROM clause 
 

Start with the SELECT clause 
 
| FROM main 
 
| SELECT sum(bytes) AS sum, host 
 

WHERE earliest=-5m@m GROUP BY host 
 

FROM main WHERE earliest=-5m@m 
 

SELECT sum(bytes) AS sum, host 
 

GROUP BY host 
 
The only difference between these searches is that one starts with the FROM clause and the other search starts with the 
SELECT clause. 
 

Regardless of which clause you start a search with, to use the optional clauses you must specify the clauses in a specific 
hierarchical order. See from command usage. 
 

Syntax 
 

The required syntax is in bold. 
 

FROM <dataset> [ AS <alias>] 
 

[ WHERE ( <predicate-expression> [<logical-operator> <predicate-expression>] ) ... ] 
 

) | <field> span=( [<int>]<timescale> ) ] 
 

[ HAVING <expression> ] 
 

[ LIMIT <integer> ] 
 


Uppercase and lowercase clause names 
 

The clause names are shown in uppercase in the syntax for readability. You can specify the clause names in uppercase 
or lowercase. For example, you can specify FROM or from, GROUP BY or group by. However, you cannot specify the names 
in mixed case, such as Group By. 
 






264 
 
Using the from command clauses 
 

The following table provides a brief explanation of what each clause is used for: 
 

Clause 
 

Explanation 
 
FROM 
 
Use the FROM clause to specify the dataset that you want to search. 
 
JOIN 
 
Use the JOIN clause to enrich your event data with data from another dataset. 
 
WHERE 
 
Use the WHERE clause to filter data. You use the WHERE clause before the data is aggregated. 
 
GROUP BY 
 
Use the GROUP BY clause to organize the search results. 
 
SELECT 
 
Use the SELECT clause to specify the fields you want returned from the search, or to aggregate the data. 
 
HAVING 
 
Use the HAVING clause to filter the results after the data is aggregated 
 
ORDER BY 
 
Use the ORDER BY clause to sort the results 
 
LIMIT 
 
Use the LIMIT clause to set a maximum for the number of results to return. 
 
OFFSET 
 
Use the OFFSET clause to return a window of records from the results by skipping rows in the result set.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$23dcd841-8411-4393-a0cd-8773db5d2730�h+)�}�(h}�(h/XLIMIT 
 
Use the LIMIT clause to set a maximum for the number of results to return. 
 
OFFSET 
 
Use the OFFSET clause to return a window of records from the results by skipping rows in the result set. 
 
For detailed information about each clause, see from command syntax details. 
 

How the from command works 
 

The from command is very SQL-like, but you don't have to know SQL to use it. 
 

The from command supports two different syntax hierarchies. One hierarchy starts with the FROM clause. The other 
hierarchy starts with the SELECT clause. See from command usage. 
 

The following examples focus on the FROM clause. To see examples that start with the SELECT clause and examples 
using the other clauses, see from command examples. 
 

Use the from command to read data in any kind of dataset, such as a timestamped index, a metric index, a view, or a 
lookup. 
 

The only required syntax is: 
 

| FROM <dataset> 
 


This simple search returns all of the data in the dataset. That might be a lot of data. Most of the time you will want to add a 
filter to your search to either narrow the results down to what you are looking for, or to exclude the data that you don't 
 


To show you how this works, let's start with an event index called main that contains events with HTTP status codes. You 
want to find all of the events with a status code of 200. 
 

You can search the main index using a simple search like this: 
 

| FROM main WHERE status=200 
 




265 
 
You can use the WHERE clause to filter data by specifying a field-value pair or specifying a time-range. 
 

Specifying field-value pairs 
 

When you specify a field-value pair, if the value is a <string> it must be enclosed in double quotation marks. For example, 
the following search looks for a specific value linux_secure1 in the sourcetype field. The value must be enclosed in 
double quotation marks. 
 

| FROM main WHERE sourcetype="linux_secure1" 
 


Likewise, numbers that are interpreted as string values must also be enclosed in double quotation marks. For example:�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7e4d4825-e9ff-46da-bf0d-b86d8234ba87�h+)�}�(h}�(h/X�double quotation marks. 
 

| FROM main WHERE sourcetype="linux_secure1" 
 


Likewise, numbers that are interpreted as string values must also be enclosed in double quotation marks. For example: 
 

| FROM main WHERE clientip="192.0.2.14" 
 

Specifying a time range 
 

You can use a Time Range Picker to specify a time range or you can specify a time range directly in your search syntax. 
 

To specify a time range directly in your search, you use the earliest and latest time modifiers in the WHERE clause. You 
can specify an exact time such as earliest="10/5/2019:20:00:00", or a relative time such as starting with the previous 
hour earliest=-h. 
 

Here's an example that specifies both a field-value pair and a beginning time range which goes back in time 1 hour. 
 

| FROM main WHERE clientip="192.0.2.14" AND earliest=-1h 
 

When a search doesn't specify an ending time range using latest, the current time now() is used. 
 

For more information about specifying time modifiers, see Time modifiers in the SPL2 Search Manual. 
 

Snap-to time 
 

You can specify that your search time range starts at the beginning of a time unit, such as the beginning of a day or hour. 
This is referred to as a snap-to time. 
 

Here's an example of using a time range in a search that is going back 5 minutes, snapping to the beginning of the 
minute. The end of the time range is the beginning of the current minute. 
 

FROM main WHERE earliest=-5m@m AND latest=@m 
 

To learn more about using a snap-to time, see Specifying relative time in the SPL2 Search Manual. 
 

Other clauses 
 

There are many clauses that you can use with the from command. 
 

For information about the hierarchy of commands, see from command usage. 
 

See from command examples for a range of examples using the from command clauses. 
 



266 
 
See also 
 

from command 
 

from command usage 
from command examples 
 


from command syntax details 
 
For overview information about the SPL2  from command, see from command overview.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0049fa09-8c98-4600-96d1-9ad77a44e885�h+)�}�(h}�(h/X<266 
 
See also 
 

from command 
 

from command usage 
from command examples 
 


from command syntax details 
 
For overview information about the SPL2  from command, see from command overview. 
For examples using the SPL2 from command, see from command examples. 
 

Syntax 
 

The SPL2 from command has a flexible syntax, which enables you to start a search with either the FROM clause or the 
SELECT clause. 
 

• If you start a search with the FROM clause, you only need to specify a <dataset>. 
 


For more information about this flexible syntax, see from command usage. 
 

The required syntax is in bold. 
 

FROM <dataset> [ AS <alias>] 
 

[ WHERE ( <predicate-expression> [<logical-operator> <predicate-expression>] ) ... ] 
 

) | <field> span=( [<int>]<timescale> ) ] 
 

[ HAVING <expression> ] 
 

[ LIMIT <integer> ] 
 


Required arguments 
 

dataset 
 


Syntax <dataset> [ AS <alias> [ <JOIN-TYPE> ] ] 
 

You can specify more than one dataset. Use the indexes dataset function if all of the datasets are indexes. See 
indexes dataset function. Use the union command if the datasets are a mixture of dataset types. See union 
command overview. 
 

default join type is INNER. The supported join types are: INNER and LEFT. 
 

Optional arguments 
 




267 
 
JOIN clause 
 

JOIN 
 


Syntax: ( <join-type> ) <dataset> AS <alias> ON <join-condition> [AND <join-condition>]... )... 
Description: You can enrich a dataset specified in the FROM clause with data from one or more datasets 
 

The aliases are used to help identify the fields in each of the datasets. 
 

A maximum of 50000 rows from the dataset that you specify in the JOIN clause, sometimes referred to as the 
right-hand side dataset, can be joined with the dataset specified in the FROM clause. This maximum is set to limit 
the impact of the JOIN clause on performance and resource consumption. 
 

You have the option of specifying a join type. The default join type is INNER JOIN. You can also specify LEFT 
JOIN. Valid join types are described in the following table: 
 

Join 
type 
 


Valid keywords 
 


Notes�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ec1b331f-226c-4631-93eb-2add6e0aeac9�h+)�}�(h}�(h/X�JOIN. Valid join types are described in the following table: 
 

Join 
type 
 


Valid keywords 
 


Notes 
 

Inner join 
 

INNER JOIN or JOIN 
 
You can specify the keywords in lowercase. The keywords are shown in uppercase for 
readability. 
 

Left join 
 
LEFT JOIN or LEFT OUTER 
JOIN 
 
You can specify the keywords in lowercase. The keywords are shown in uppercase for 
readability. 
 
Right join 
 
A right join is not supported at this time. 
 










The <join-condition> specifies the key fields that each dataset has in common, such as a product ID or supplier 
ID. The syntax for the <join-condition> is <left-alias>.<left-field>=<right-alias>.<right-field>. The alias is a unique 
string you use in the search to identify the dataset. For example, if the dataset is orders you could use the alias o. 
If the orders dataset contains the field productID, the syntax to identify this field is o.productID. 
 

You can specify multiple join conditions by using the AND operator between each condition. For example, ON 
o.productID=p.pid AND o.supplierID=p.sid. 
 

You can specify multiple JOIN clauses in a search. See from command examples. 
 



Default: None. You must specify a join type. 
 

WHERE clause 
 

WHERE 
 

Description: Use predicate expressions to filter your data. When specifying multiple predicate expressions, you 
 


268 
 
must specify a logical operator between the expressions. For information about and examples of the types of 
predicate expressions you can specify, see Predicate expressions in the SPL2 Search Manual. 
 

Use the WHERE clause to filter your data before using other clauses that contain aggregations. For example, the 
following search contains an aggregation in the SELECT clause. The WHERE clause filters the data by narrowing 
down the events based on a time range. The filtered data is then passed to the SELECT clause: 
 

FROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host SELECT sum(bytes) AS sum, host HAVING sum 
> 1024*1024�h1h2h3}�h5Kuh�(h3h/�h}�ub�$86c7eac3-0900-4769-b2fb-4b1aab0cb1ed�h+)�}�(h}�(h/XQFROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host SELECT sum(bytes) AS sum, host HAVING sum 
> 1024*1024 
 

The WHERE clause supports using wildcards in the <predicate-expression> only with the like function. For more 
information, see Conditional and comparison functions. 
 

Default: None 
 

GROUP BY clause 
 

GROUP BY 
 

[<int>]<timescale> ) | <field> span=( [<int>]<timescale> ) 
 

expression such as first_name + last_name or upper(first_name). See Types of expressions in the SPL2 
Search Manual. 
 

◊ When specifying a field that contains UNIX time, you can also specify a time span. 
 

field separately. 
 


If the GROUP BY clause is specified, the SELECT clause must also be specified. For examples, see the SELECT clause 
section Dependencies between SELECT and GROUP BY. 
 

Using a time span 
 

There are multiple ways to use a span: 
 

Span type 
 

Syntax 
 

Description and Examples 
 
The span is calculated automatically based on the time 
range in the Time Range Picker. 
 

Auto span 
 

span (<field>) 
 
Example: 
 
◊ span(_time) 
 
Span using the default time unit.   span (<field>, <timescale>) 
 
You can specify a timescale, such as m for minute and h 
for hour, without specify a time unit. The default time 
 

There are two syntaxes 
you can use. 
 


<field> span=<timescale> 
 



Examples: 
 



269 
 
Span type 
 
Syntax 
 
Description and Examples 
 
◊ span(_time, m), which defaults to a span of 
	1 minute. 
 
hour. 
 
You can specify a timescale with a time unit. 
 
Span with a specified time unit. 
 
span (<field>, 
<int><timescale>) 
 


Examples: 
 
There are two syntaxes 
you can use. 
 


<field> span=<int><timescale> 
 
◊ span (_time, 3h), which specifies a span 
	of 3 hours. 
 
hours. 
 

For more information about specifying span, see Specifying time spans in the SPL2 Search Manual. 
 

Default: If no GROUP BY clause is specified, the from command returns all of the rows, based on the WHERE clause. 
 

SELECT clause 
 

SELECT 
 

Description: Use the SELECT clause to retrieve specific fields and perform an aggregate function that specifies a�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3c136a4f-8125-406a-add5-7b1103436d2f�h+)�}�(h}�(h/X�SELECT clause 
 

SELECT 
 

Description: Use the SELECT clause to retrieve specific fields and perform an aggregate function that specifies a 
field, such as max(delay). Use SELECT DISTINCT to retrieve unique combinations of the selected field values. If 
multiple rows contain the same combination of field values, only one row is returned. 
 

◊ The <expression> can be any expression. See Types of expressions in the SPL2 Search Manual. 
 

multiple fields, such as 'host*'. The syntax with the asterisk must be enclosed in single quotation marks. 
For information about when quotation marks are required, see Quotations in the SPL2 Search Manual. 
 

incoming result set. 
 

word. For a list of the reserved words, see Reserved words. 
 

when specifying field names in the SELECT clause. 
 

Supported hierarchies 
 

other hierarchy starts with the SELECT clause. See from command usage. 
 

◊ FROM clause hierarchy: When the GROUP BY clause is specified, the SELECT clause must also be 
	specified. The expressions in the SELECT clause must be field names or aggregate functions. For 
	examples, see the section Dependencies between SELECT and GROUP BY. 
 

required. 
 

Dependencies between SELECT and GROUP BY 
 

specify in the SELECT clause must also be specified in the GROUP BY clause, unless the field in the SELECT clause is 
 


270 
 
used in an aggregate function. 
 

The following table includes several examples that show the dependency between the SELECT and the GROUP BY 
clauses: 
 

Description 
 

Example 
 


The SELECT clause has count(), an aggregate function, and the fields host and 
_time. The GROUP BY clause must include both the host and _time fields. 
 

FROM main 

GROUP BY host, _time 
 



The SELECT clause has count(), an aggregate function, the host field, and 
latest(_time) AS _time aggregate function expression. The GROUP BY clause 
must include the host field. 
 


FROM main 

GROUP BY host 
 
latest(_time) AS _time 
 

Default: None 
 

ORDER BY clause 
 

ORDER BY�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0eece533-446c-4c73-9066-2b1d5c726e71�h+)�}�(h}�(h/X�latest(_time) AS _time aggregate function expression. The GROUP BY clause 
must include the host field. 
 


FROM main 

GROUP BY host 
 
latest(_time) AS _time 
 

Default: None 
 

ORDER BY clause 
 

ORDER BY 
 

Description: One or more expressions to order the results by. See Types of expressions in the SPL2 Search 
Manual. 
 

upper(first_name). Separate multiple expressions with commas. 
 

similar names. You must specify each field separately. You can specify either ascending or descending 
order. 
 

sum(bytes), you can either enclose the field name in single quotation marks, because it contains special 
characters, or rename the field before using the ORDER BY clause. 
 

Lexicographical order in the SPL2 Search Manual. 
 

HAVING clause 
 

HAVING 
 

Description: Use the HAVING clause as a filter on the data. The expression you specify must result in either true 
or false. If the expression is a string, it must be enclosed in double quotation marks. See Predicate expressions in 
the SPL2 Search Manual. 
 

Traditionally you use the HAVING clause to filter data after clauses with aggregations. For example, this search 
contains an aggregation in the SELECT clause. The WHERE clause is used to filter the data before the aggregation in 
the SELECT clause. 
 

FROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host SELECT sum(bytes) AS sum, host HAVING sum 
> 1024*1024 
 


271 
 
Default: None 
 

LIMIT clause 
 

LIMIT 
 


Syntax: LIMIT <integer> 
 

Default: None 
 

OFFSET clause 
 

OFFSET 
 

Description: Use to skip past a number of matches. For example if you specify OFFSET 15, the 16th result is the 
first result that is returned. The OFFSET clause is often used in conjunction with the LIMIT clause. 
 


See also 
 

from command 
 

from command usage 
from command examples 
 


from command usage 
 
The from command is a generating command, which means that it generates events or reports from one or more 
datasets without transforming the events.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$619bbb00-ddc2-4f7c-87ec-d10197e6929f�h+)�}�(h}�(h/Xfrom command examples 
 


from command usage 
 
The from command is a generating command, which means that it generates events or reports from one or more 
datasets without transforming the events. 
 

Generating commands use a leading pipe character and should be the first command in a search. A unique feature of the 
from command is that you can start a search with the FROM clause or the SELECT clause. 
 

Hierarchy of clauses 
 

There is a hierarchy to the from command clauses. You can skip clauses, but the clauses you use in your search must 
follow the hierarchy. 
 

The hierarchy depends on whether you start the FROM clause or the SELECT clause. 
 

FROM clause hierarchy 
 

SELECT clause hierarchy 
 

• FROM 
 


♦ JOIN 
 

• SELECT | SELECT 
	DISTINCT 
 
⋅ GROUP 
	BY 
 
◊ JOIN 
 

⋅ WHERE 
	• 
 


GROUP 
BY 
 
DISTINCT 
 


272 
 
FROM clause hierarchy 
 
SELECT clause hierarchy 
 
♦ HAVING 
 


BY 
 



⋅ LIMIT 
 




• OFFSET 
 
◊ ORDER 
	BY 
 



• OFFSET 
 
If you have a search that only has the FROM and ORDER BY clauses, you can add any of the clauses lower in the hierarchy 
after ORDER BY to your search. 
 

You cannot add any of the clauses higher in the hierarchy than ORDER BY to the end of your search. To include a clause 
higher in the hierarchy, you must insert the clause in its proper order. 
 

For example, suppose you have this search: 
 

|FROM <dataset> ORDER BY <field> DESC 
 

You can add the LIMIT or OFFSET clause after the ORDER BY. However, to add the WHERE clause, you must insert it between 
the FROM clause and the ORDER BY clause in your search. 
 

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


$from_example = 
 

WHERE host="www2" 
GROUP BY action 
 

ORDER BY action DESC 
 

$select_example = 
 

FROM sample_data_index 
WHERE host="www2" 
 

ORDER BY action DESC 
 
Using dataset literals 
 

A dataset literal is a temporary dataset that you type into your search criteria.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$48a93bbf-2250-456e-8c08-3671c50654ff�h+)�}�(h}�(h/X8$select_example = 
 

FROM sample_data_index 
WHERE host="www2" 
 

ORDER BY action DESC 
 
Using dataset literals 
 

A dataset literal is a temporary dataset that you type into your search criteria. 
 

You can use a dataset literal anywhere you specify a dataset name, such as in generating commands like from and union. 
 

Here's an example of using a dataset literal with the from command: 
 

FROM [ { "state": "Washington", "abbreviation": "WA", "population": 7535591 }, { "state": "California", 
"abbreviation": "CA", "population": 39557045 }, { "state": "Oregon", "abbreviation": "OR", "population": 
4190714 } ] | eval _time = now() 
 

This search returns these results: 
 

_time 
 

abbreviation 
 

population 
 

state 
 
3:47:52 PM 14 May 2022 
 
WA 
 
7535591 
 
Washington 
 



273 
 
_time 
 
abbreviation 
 
population 
 
state 
 
3:47:52 PM 14 May 2022 
 
CA 
 
39557045 
 
California 
 
3:47:52 PM 14 May 2022 
 
OR 
 
4190714 
 
Oregon 
 
For more information see Dataset literals in the SPL2 Search Manual. 
 

Using the repeat() dataset function 
 

You use the repeat() function with the from command to create events in a temporary dataset. The repeat() function is 
often used to create events for testing. For example, you can create a dataset with empty events, events with hourly or 
daily timestamps, or events with field-value pairs. 
 

For more information and examples, see repeat dataset function 
 

Using expressions in clauses 
 

You can use expressions in many of the from command clauses. 
 

Expressions produce a value and can be composed of field names, literals, functions, parameters, comparisons and other 
expressions. 
 

Here are some examples: 
 

Clause 
 

Description 
 

Example 
 
WHERE 
 
avg(bytes/1024) 
 
GROUP BY 
 
This expression uses the upper function and the first_name field. 
 
...GROUP BY upper(first_name) 
 
SELECT 
 
avg(bytes/1024) 
 
HAVING 
 
avg(bytes/1024) 
 
ORDER BY 
 
avg(bytes/1024) 
 


For more information and examples, see Types of expressions in the SPL2 Search Manual. 
 

Aliases do not appear in search results�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4b90673c-1ff3-4472-b8f3-32bae929120e�h+)�}�(h}�(h/X:avg(bytes/1024) 
 
HAVING 
 
avg(bytes/1024) 
 
ORDER BY 
 
avg(bytes/1024) 
 


For more information and examples, see Types of expressions in the SPL2 Search Manual. 
 

Aliases do not appear in search results 
 

When you use the JOIN clause, the aliases you specify in the search are not propagated to the search results. For 
example, consider this search: 
 

| SELECT m.srcip, m._time, m.bytes, user.department, user.username FROM main AS m JOIN users AS user ON 
m.uid = user.id 
 

Because the aliases are not preserved, the fields returned are srcip, _time, bytes, department, and username. 
 

Lexicographical order 
 

The ORDER BY clause in the from command uses lexicographical order. Lexicographical order sorts items based on the 
values used to encode the items in computer memory. In Splunk software, this is almost always UTF-8 encoding, which is 
 


274 
 
• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or 
	after letters. 
 

For examples of how lexicographical order is different than alphanumeric order, see Lexicographical order in the SPL2 
Search Manual. 
 

Differences between SPL and SPL2 
 

The from command in SPL2 is substantially different than the from command in SPL. 
 

Datasets no longer need to be qualified 
 

Version 
 

Example 1 
 

Example 2 
 
SPL 
 
| from savedsearch:my_search 
 
Not supported 
 
SPL2 
 
| from my_search 
 
| from main (where main is an index) 
 
Datasets can be filtered 
 

Datasets can be filtered using the where clause. 
 

Version 
 

Example 
 
SPL 
 
Not supported. You would need add the the where command to the search to accomplish this. 
 
SPL2 
 
| from my_search where field="value" 
 
Datasets can be sorted 
 

Datasets can be sorted using the ORDER BY clause. 
 

Version 
 

Example 
 
SPL 
 
Not supported. You would need add the sort command to the search to sort the dataset.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$db207c29-2a79-4536-b003-c22097a93103�h+)�}�(h}�(h/X+Datasets can be sorted 
 

Datasets can be sorted using the ORDER BY clause. 
 

Version 
 

Example 
 
SPL 
 
Not supported. You would need add the sort command to the search to sort the dataset. 
 
| from 1559332447_548 order by DESC status 
 
SPL2 
 
(This is a dataset generated from a search ID (sid). 
 
Datasets can be projected 
 

Datasets can be projected using the GROUP BY clause. 
 

Version 
 

Example 
 

SPL 
 
Not supported. You would need add a command that includes a BY clause to the search to accomplish 
this. 
 
SPL2 
 
| FROM main GROUP BY host 
 






275 
 
See also 
 

from command 
 

from command syntax details 
from command examples 
 


from command examples 
 
The following are examples for using the SPL2 from command. To learn more about the from command, see How the 
from command works. 
 

You can specify the clauses in the from command in uppercase or lowercase. These examples use uppercase for 
readability. 
 

Some of these examples start with the SELECT clause and others start with the FROM clause. Both of these clauses 
are valid syntax for the from command. 
 

1. Specify string values in quotations 
 

The following search shows that string values in field-value pairs must be enclosed in double quotation marks. 
 

FROM my_index sourcetype="syslog" ... 
 

Because string values must be enclosed in double quotation marks, you can reverse the order of field-value pairs. For 
example, the previous search can also be specified this way: 
 

FROM my_index "syslog"=sourcetype ... 
 

2. Search a metric index 
 

The following search looks for data in the _metrics index: 
 

SELECT earliest_time(_value), metric_name FROM _metrics WHERE like(metric_name, "deploy%") GROUP BY 
metric_name 
 

To use a wildcard in the WHERE clause, you cannot use the asterisk ( * ) wildcard character. You must use the like 
function. See Comparison and Conditional functions. 
 

3. Search multiple indexes 
 

The following search looks for data in the EMEA and APAC indexes: 
 

FROM indexes(EMEA, APAC) WHERE count(orders) > 1000 GROUP BY country�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6f17bdff-d63f-48f0-9bba-2708658c96a1�h+)�}�(h}�(h/X�3. Search multiple indexes 
 

The following search looks for data in the EMEA and APAC indexes: 
 

FROM indexes(EMEA, APAC) WHERE count(orders) > 1000 GROUP BY country 
 

4. Search using wildcards 
 

You can use a wildcard character ( * ) in the SELECT clause to search for similar field names. You must enclose the 
wildcard syntax in single quotation marks. For example: 
 

276 
 
SELECT 'host*' FROM main ... 
 


You can use a wildcard to search for only internal fields, which begin with an underscore ( _ ) character . For example: 
 

FROM main SELECT '_*' 
 


The WHERE clause does not support the wildcard character ( * ). However you can use the like function to perform a 
wildcard search. For example: 
 

FROM main WHERE ipaddress LIKE "198.%"... 
 

The like function supports several syntaxes, see Comparison and Conditional functions. 
 

5. Specify multiple expressions in the WHERE clause 
 

Use the WHERE clause to filter the data by specifying one or more expressions. You need to separate multiple 
expressions using logical operators, such as AND and OR. 
 

FROM index=_internal WHERE like(source, "%license%") AND type="usage" | stats sum(b) BY idx 
 

The WHERE clause uses the like function to perform a search with wildcard. The WHERE clause does not support the 
asterisk ( * ) wildcard character. For more information about the like function, see Comparison and Conditional functions. 
 

For more information about logical operators, see Predicate expressions in the SPL2 Search Manual. 
 

6. Search for multiple terms in events 
 

You can search for multiple terms in your events by using a search literal in the WHERE clause. An AND operator is 
implied between the terms specified in the search literal. To specify a search literal, you enclose the list of terms in 
backtick characters ( ` ). 
 

The following search looks for the terms invalid AND user AND sshd[5258] and returns the events that contain all three 
terms: 
 

SELECT _time, source FROM main WHERE `invalid user sshd[5258]`�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8de2b43f-fc32-4cca-ba2b-28c7705159b4�h+)�}�(h}�(h/X The following search looks for the terms invalid AND user AND sshd[5258] and returns the events that contain all three 
terms: 
 

SELECT _time, source FROM main WHERE `invalid user sshd[5258]` 
 

For more information, see Search literals in expressions in the SPL2 Search Manual. 
 

7. Specify a single field in the GROUP BY clause 
 

You can specify one or more fields to group by. In this example a single field, host, is specified. 
 

When using the from command, if the GROUP BY clause is specified, the SELECT clause must also be specified. The 
SELECT clause must contain either an aggregation or the fields in the GROUP BY clause. In this example, the SELECT 
clause contains the aggregation avg(cpu_usage): 
 

SELECT avg(cpu_usage) AS 'Avg Usage' FROM my_index WHERE sourcetype="syslog" GROUP BY host 
 





277 
 
8. Specify a time span in the GROUP BY clause 
 

You can arrange search results in groups using a time span. 
 

When using the from command, if the GROUP BY clause is specified, the SELECT clause must also be specified. 
 

The following search returns web access error information, grouped by host in 5 minute time spans. 
 

SELECT count(), host, _time FROM index WHERE sourcetype="webaccess" AND `ERROR` GROUP BY host, span(_time, 
5m) 
 

There are several ways to specify a time span with the GROUP BY clause, see from command syntax details. 
 

9. Sorting search results using the ORDER BY clause 
 

Suppose you use the following search to return count of the actions taken, grouped by the productId field. 
 

FROM sample_data_index WHERE status=200 AND host="www4" GROUP BY productId SELECT count(action), productId 
 

The results look something like this: 
 

productId 
 

count(action) 
 
DC-SG-G02 
 
12 
 
FS-SG-G03 
 
10 
 
MB-AG-G07 
 
17 
 
PZ-SG-G05 
 
4 
 
SF-BVS-G01 
 
11 
 
SF-BVS-T01 
 
6 
 
WC-SH-G04 
 
2 
 
WC-SH-T02 
 
15 
 
By default the results are sorted on the GROUP BY field, productId. 
 

You want to sort the results in descending order based on the count. However, the name of the count field in the output is�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c8eab9f6-ac20-4237-af49-692d3db6b731�h+)�}�(h}�(h/X�15 
 
By default the results are sorted on the GROUP BY field, productId. 
 

You want to sort the results in descending order based on the count. However, the name of the count field in the output is 
the name of the aggregation specified in the SELECT clause, count(action). The ORDER BY clause will not sort on a 
field name that is an aggregation because it contains special characters, the parenthesis. You have two options, you can 
 

field name in single quotations, such as ORDER BY 'count(action)' DESC. 
 

Here's the updated search using the rename option: 
 

FROM sample_data_index WHERE status=200 AND host="www4" GROUP BY productId SELECT count(action) AS Count, 
productId ORDER BY Count DESC 
 

The results look something like this: 
 

productId 
 

Count 
 
MB-AG-G07 
 
17 
 

278 
 
productId 
 
Count 
 

WC-SH-T02 
 

15 
 
DC-SG-G02 
 
12 
 
SF-BVS-G01 
 
11 
 
FS-SG-G03 
 
10 
 
SF-BVS-T01 
 
6 
 
PZ-SG-G05 
 
4 
 
WC-SH-G04 
 
2 
 
10. Enrich event data with a lookup dataset using the JOIN clause 
 

Consider the following data from a set of events with login information: 
 

_time 
 

action 
 

userID 
 

host 
 

port 
 
8:00 AM 29 Nov 2021 
 
Failed password 
 
patel 
 
yangtze.buttercupgames.com 
 
3390 
 
7:15 AM 29 Nov 2021 
 
Failed password 
 
zhang 
 
nile.example.net 
 
1851 
 
9:30 PM 15 Nov 2021 
 
Session opened 
 
dubois 
 
danube.sample.com 
 
1260 
 
6:11 AM 14 Nov 2021 
 
Failed password 
 
sullivan 
 
volga.example.com 
 
2766 
 
11:20 AM 15 Nov 2021 
 
Failed password 
 
martin 
 
volga.example.com 
 
3622 
 
08:13 AM 31 Oct 2021 
 
Failed password 
 
mayer 
 
ganger.example.com 
 
3658 
 
11:59 PM 23 Oct 2021 
 
Failed password 
 
patel 
 
yangtze.buttercupgames.com 
 
1214 
 
You want to enrich the event data with information from the host_info lookup dataset, which contains information about 
known hosts: 
 

hostname 
 

kind 
 

status 
 

host_contact 
 
mekong.buttercupgames.com 
 
internal 
 
allowed 
 
alex@buttercupgames.com 
 
yangtze.buttercupgames.com 
 
internal 
 
allowed 
 
claudia@buttercupgames.com 
 
danube.sample.com 
 
supplier 
 
allowed 
 
martin@sample.com 
 
ganger.example.com 
 
external 
 
allowed�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cbacbb43-71d2-4da1-bda9-c0a358833225�h+)�}�(h}�(h/XBalex@buttercupgames.com 
 
yangtze.buttercupgames.com 
 
internal 
 
allowed 
 
claudia@buttercupgames.com 
 
danube.sample.com 
 
supplier 
 
allowed 
 
martin@sample.com 
 
ganger.example.com 
 
external 
 
allowed 
 
david@example.com 
 
volga.example.com 
 
external 
 
banned 
 
Specifically, you want every event that matches the search criteria to appear in the search results. If there is a match 
between an event and the host_info lookup dataset, you want to display the kind and status from the host_info lookup 
dataset with each event. This is referred to as a left join, which is shown in the following image. 
 











279 
 
The A circle represents the event dataset and the B circle represents the host_info lookup dataset. 
 

The following example enriches data in the main event dataset with data from the host_info lookup dataset, where there 
is a matching host name. An alias for each dataset is created using the AS clause. The WHERE clause filters out events 
where the host kind is not internal. The SELECT clause specifies which fields to return. The results are organized by the 
host field. 
 

FROM main AS m LEFT JOIN host_info AS h ON m.host=h.hostname WHERE h.kind!="internal" SELECT m.host, 
m.action, m.userID, h.kind, h.status GROUP BY m.host 
 

When you use the JOIN clause, the aliases you specify in the search are not propagated to the search results. For 
example, in this search you specified m.host, but the search results display host. 
 

The results of this search are shown in the following table. As you can see, the events that have a host with a kind of 
internal, the buttercupgames.com hosts, have been removed. The results also show that there is no host information for 
the nile.example.net host. 
 

host 
 

action 
 

userID 
 

kind 
 

status 
 
danube.sample.com 
 
Session opened 
 
dubois 
 
supplier 
 
allowed 
 
ganger.example.com 
 
Failed password 
 
mayer 
 
external 
 
allowed 
 
nile.example.net 
 
Failed password 
 
zhang 
 
volga.example.com 
 
Failed password 
 
sullivan 
 
external 
 
banned 
 
volga.example.com 
 
Failed password�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d260d03f-f144-41a2-9c42-00c77ad72437�h+)�}�(h}�(h/X�Failed password 
 
mayer 
 
external 
 
allowed 
 
nile.example.net 
 
Failed password 
 
zhang 
 
volga.example.com 
 
Failed password 
 
sullivan 
 
external 
 
banned 
 
volga.example.com 
 
Failed password 
 
martin 
 
external 
 
banned 
 
11. Use consecutive JOIN clauses to return data from multiple datasets 
 

You can create a stacked join search that uses multiple JOIN clauses to return data from multiple datasets. 
 

Consider the following data from a set of events in the orders dataset: 
 

_time 
 

clientip 
 

action 
 

pid 
 

quantity 
 
12:00:01 PM 20 Jan 2022 
 
192.0.2.0 
 
purchase 
 
DC-SG-G02 
 
1 
 
10:13:34 AM 20 Jan 2022 
 
203.0.113.255 
 
addtochart 
 
MB-AG-G07 
 
3 
 
9:55:51 AM 20 Jan 2022 
 
203.0.113.0 
 
purchase 
 
WC-SH-A01 
 
1 
 
9:21:25 AM 20 Jan 2022 
 
198.51.100.255 
 
changequantity 
 
PZ-SG-G05 
 
2 
 
9:14:17 AM 20 Jan 2022 
 
192.0.2.0 
 
purchase 
 
SF-BVS-01 
 
1 
 
8:42:23 AM 20 Jan 2022 
 
198.51.100.0 
 
purchase 
 
SF-BVS-G01 
 
1 
 
8:30:45 AM 20 Jan 2022 
 
192.0.2.0 
 
purchase 
 
WC-SH-T02 
 
2 
 
7:57:14 AM 20 Jan 2022 
 
198.51.100.0 
 
purchase 
 
PZ-SG-G05 
 
1 
 
You want to enrich the orders event data with information from the products lookup dataset, which contains product and 
price information. Here is an example of the data in the products dataset: 
 

productId 
 

product_name 
 

price 
 

sale_price 
 

supplierId 
 


280 
 
DC-SG-G02 
 
Dream Crusher 
 
39.99 
 
24.99 
 
1238 
 
FS-SG-G03 
 
Final Sequel 
 
24.99 
 
16.99 
 
5017 
 
WC-SH-G04 
 
World of Cheese 
 
24.99 
 
19.99 
 
7024 
 
WC-SH-T02 
 
World of Cheese Tee 
 
19.99 
 
16.99 
 
7024 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
4.99 
 
3.99 
 
7045 
 
MB-AG-G07 
 
Manganiello Bros. 
 
38.99 
 
27.99 
 
4111 
 
SF-BVS-G01 
 
Grand Theft Scooter 
 
26.99 
 
21.99 
 
5007 
 
SF-BVS-01 
 
Pony Run 
 
49.99 
 
41.99 
 
5007 
 
You want to display the product names instead of the product IDs in your search results. 
 

You want every order event that matches the search criteria to appear in the results, even if the item ordered does not 
have a matching entry in the products lookup dataset. Notice that the third order contains the product ID WC-SH-A01, which�

h1h2h3}�h5Kuh�(h3h/�h}�ub�$de0ece64-6daa-4c17-932f-3a5f3870f2b6�h+)�}�(h}�(h/Xjhave a matching entry in the products lookup dataset. Notice that the third order contains the product ID WC-SH-A01, which 
 


You can display the product names in the search results by including a JOIN clause to your search that enriches the 
orders dataset with the data from the products dataset. Specifically, you need to use a LEFT JOIN to accomplish this 
result. The datasets are joined on the field that the datasets have in common, which is the product ID field. 
 

Here is the search you can use to add the product names to the orders events: 
 

FROM orders AS o LEFT JOIN products AS p ON o.pid=p.productId SELECT o._time, o.pid, p.product_name, 
o.quantity 
 

The results look like this: 
 

_time 
 

pid 
 

product_name 
 

quantity 
 
12:00:01 PM 20 Jan 2022 
 
DC-SG-G02 
 
Dream Crusher 
 
1 
 
10:13:34 AM 20 Jan 2022 
 
MB-AG-G07 
 
Manganiello Bros. 
 
3 
 
9:55:51 AM 20 Jan 2022 
 
WC-SH-A01 
 
1 
 
9:21:25 AM 20 Jan 2022 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
2 
 
9:14:17 AM 20 Jan 2022 
 
SF-BVS-01 
 
Pony Run 
 
1 
 
8:42:23 AM 20 Jan 2022 
 
SF-BVS-G01 
 
Grand Theft Scooter 
 
1 
 
8:30:45 AM 20 Jan 2022 
 
WC-SH-T02 
 
World of Cheese Tee 
 
2 
 
7:57:14 AM 20 Jan 2022 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
1 
 
Because there is no matching product ID for WC-SH-A01 in the products dataset, there is no product name in the search 
results. Using a LEFT JOIN is a way to highlight missing information from the second, or right-side, dataset. 
 

Now you want to find out the name and city of the supplier that provides each product. You can enrich the search results 
data with information from the suppliers lookup dataset, based on the supplier ID. 
 

Here is an example of the data in the suppliers dataset: 
 

281 
 
supplier_id 
 
supplier_name 
 
city 
 
state/province 
 
country 
 
1009 
 
Mile High Games 
 
Denver 
 
Colorado 
 
United States 
 
1237 
 
Area 51 Games 
 
Roswell 
 
New Mexico 
 
United States 
 
4111 
 
Isthmus Pastimes 
 
Panama City 
 
Panama 
 
Panama 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
5017 
 
Der Kriegsspiel 
 
Cologne 
 
North Rhine-Westphalia�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1fba0d5a-23bf-4516-9a82-4ebb7fd8c97f�h+)�}�(h}�(h/XeNew Mexico 
 
United States 
 
4111 
 
Isthmus Pastimes 
 
Panama City 
 
Panama 
 
Panama 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
5017 
 
Der Kriegsspiel 
 
Cologne 
 
North Rhine-Westphalia 
 
Germany 
 
7024 
 
Happy Fun Games 
 
Kyoto 
 
Kyoto 
 
Japan 
 
7045 
 
Kiwi Game Warehouse 
 
Auckland 
 
Auckland 
 
New Zealand 
 
To display the supplier names and city in your search results you need to add another JOIN clause to your search. 
Because you want every product in the search results returned, whether or not there is a corresponding supplier, you will 
use a LEFT JOIN. The products and suppliers datasets can be joined on the supplier ID field. 
 

Looking back at the products dataset, the Dream Crusher product has a supplier ID of 1238, which does not appear in the 
suppliers dataset. The LEFT JOIN will highlight the absence of this information. 
 

Here is the updated search: 
 

FROM orders AS o LEFT JOIN products AS p ON o.pid=p.productId LEFT JOIN suppliers AS s ON 
p.supplierId=s.supplier_id SELECT o._time, o.pid, p.product_name, p.supplierId, s.supplier_name, o.quantity 
 

The results of the search look like this: 
 

_time 
 

pid 
 

product_name 
 

supplierId 
 

supplier_name 
 

quantity 
 
12:00:01 PM 20 Jan 2022 
 
DC-SG-G02 
 
Dream Crusher 
 
1 
 
10:13:34 AM 20 Jan 2022 
 
MB-AG-G07 
 
Manganiello Bros. 
 
4111 
 
Isthmus Pastimes 
 
3 
 
9:55:51 AM 20 Jan 2022 
 
WC-SH-A01 
 
1 
 
9:21:25 AM 20 Jan 2022 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
7045 
 
Kiwi Game Warehouse 
 
2 
 
9:14:17 AM 20 Jan 2022 
 
SF-BVS-01 
 
Pony Run 
 
5007 
 
EuroToys 
 
1 
 
8:42:23 AM 20 Jan 2022 
 
SF-BVS-G01 
 
Grand Theft Scooter 
 
5007 
 
EuroToys 
 
1 
 
8:30:45 AM 20 Jan 2022 
 
WC-SH-T02 
 
World of Cheese Tee 
 
7024 
 
Happy Fun Games 
 
2 
 
7:57:14 AM 20 Jan 2022 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
7045 
 
Kiwi Game Warehouse 
 
1 
 
12. Return data from a view 
 

This search returns the timestamp and client IP fields from a view called mysecurityview. 
 

FROM mysecurityview | fields _time, clientip ... 
 

13. Use the HAVING clause to filter after aggregations�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dae2677b-3783-4a18-a99a-d30f207697d9�h+)�}�(h}�(h/XThis search returns the timestamp and client IP fields from a view called mysecurityview. 
 

FROM mysecurityview | fields _time, clientip ... 
 

13. Use the HAVING clause to filter after aggregations 
 

The following example calculate the sum of the bytes field in the main index from events that occurred in the last 5 
minutes. The results are grouped by the host field. The sum and the host fields are returned, where the sum of the bytes is 
greater than I MB. 
 


282 
 
SELECT sum(bytes) AS sum, host FROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host HAVING sum > 
1024*1024 
 

14. Specify offsets and limits 
 

The following search returns web access error information, grouped by host and 5 minute time spans, that have a count 
greater than 10. The LIMIT clause is used to return up to 50 results. The OFFSET clause is used to skip the first 20 
results, starting with the 21st result. 
 

SELECT count(), host, _time FROM index WHERE sourcetype="webaccess" AND `ERROR` GROUP BY host, span(_time, 
5m) HAVING count > 10 ORDER BY count desc LIMIT 50 OFFSET 20 
 

See also 
 

from command 
 

from command syntax details 
from command usage 
 

Related information 
 








































283 
 
head command 
 


head command overview 
 
Returns the first search results, in search order, based on the <limit> specified. For historical searches, returns the most 
recent events. For real-time searches, searches the first captured events. 
 

If no options are explicitly specified, the head command returns the first 10 results. 
 

Syntax 
 

The required syntax is in bold. 
 

head 
 

[while "("<boolean-expression>")"] 
[<limit>] 
 

How the head command works 
 

The head command returns the top <limit> results. If your search returns events, the most recent events are returned first. 
Here is an example of some search results: 
 

Time 
 

Event 
 
00:15:07 AM 17 Sep 
2021 
 
Thu Sep 17 2021 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 
194.8.74.23 port 3351 ssh2 
 
11:59:07 PM 16 Sep 
2021�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aea62227-6e6b-4833-a2ae-dba00af01b3a�h+)�}�(h}�(h/XTime 
 

Event 
 
00:15:07 AM 17 Sep 
2021 
 
Thu Sep 17 2021 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 
194.8.74.23 port 3351 ssh2 
 
11:59:07 PM 16 Sep 
2021 
 
Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 
194.8.74.23 port 3626 ssh2 
 
11:12:33 PM 16 Sep 
2021 
 
Wed Sep 16 2021 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user 
sullivan by (uid=0) 
 
10:19:07 PM 16 Sep 
2021 
 
Wed Sep 16 2021 22:19:07 mailsv1 sshd[3760]: Failed password for invalid user dubois from 
194.8.74.23 port 2472 ssh2 
 
8:59:24 PM 16 Sep 
2021 
 
Wed Sep 16 2021 20:59:24 mailsv1 sshd[5801]: Failed password for invalid user patel from 
194.8.74.23 port 2285 ssh2 
 
8:42:07 PM 16 Sep 
2021 
 
Wed Sep 16 2021 20:42:07 mailsv1 sshd[3759]: Failed password for martin from 194.8.74.23 port 
3769 ssh2 
 
7:49:13 PM 16 Sep 
2021 
 
Wed Sep 16 2021 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 
194.8.74.23 port 3417 ssh2 
 
To see the first 3 events, you specify this: 
 

... | head 3 
 

You would see this set of events: 
 



284 
 
Time 
 
Event 
 
00:15:07 AM 17 Sep 
2021 
 
Thu Sep 17 2021 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 
194.8.74.23 port 3351 ssh2 
 
11:59:07 PM 16 Sep 
2021 
 
Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 
194.8.74.23 port 3626 ssh2 
 
11:12:33 PM 16 Sep 
2021 
 
Wed Sep 16 2021 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user 
sullivan by (uid=0) 
 
Specifying a filter with the head command 
 

Instead of returning just the top <limit> events, you can filter which events are returned by using the while argument. In 
this example is looking for events where the user is garcia and returns at most 5 events. The while argument is a 
<boolean-expression> that must be enclosed in parenthesis. 
 

...| head while (user=garcia) 5 
 

Here are the results: 
 

Time 
 

Event 
 
11:59:07 PM 16 Sep 
2021�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5f92c55c-e7a7-4851-9f54-e35fcc3c6264�h+)�}�(h}�(h/X�<boolean-expression> that must be enclosed in parenthesis. 
 

...| head while (user=garcia) 5 
 

Here are the results: 
 

Time 
 

Event 
 
11:59:07 PM 16 Sep 
2021 
 
Wed Sep 16 2021 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 
194.8.74.23 port 3626 ssh2 
 
7:49:13 PM 16 Sep 
2021 
 
Wed Sep 16 2021 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 
194.8.74.23 port 3417 ssh2 
 
To learn about the other arguments you can specify with the head command, see head command syntax details. 
 

Using the command on transformed data 
 

In the previous examples we show examples with search results that are events. You can also use the head command 
after the events have been summarized using a transforming command like stats. 
 

Consider these results: 
 

status 
 

host 
 

count 
 
200 
 
www1 
 
11835 
 
200 
 
www2 
 
11186 
 
200 
 
www3 
 
11261 
 
400 
 
www1 
 
233 
 
400 
 
www2 
 
257 
 
400 
 
www3 
 
211 
 
403 
 
www2 
 
228 
 
404 
 
www1 
 
244 
 
404 
 
www2 
 
209 
 


285 
 
status 
 
host 
 
count 
 

These results are sorted by the status field. If you specify something like ...| head 4 the first 4 results are returned: 
 

status 
 

host 
 

count 
 
200 
 
www1 
 
11835 
 
200 
 
www2 
 
11186 
 
200 
 
www3 
 
11261 
 
400 
 
www1 
 
233 
 
If you want return the top 4 results based on the count field, you must first sort the results by that field before you run the 
head command. For example: 
 

...| sort count | head 4 
 




status 
 




host 
 




count 
 
200 
 
www1 
 
11835 
 
200 
 
www2 
 
11186 
 
200 
 
www3 
 
11261 
 
400 
 
www2 
 
257 
 
Compare the last result (257) with the last result in previous example (233) to see the difference. 
 

Here is another example. 
 

You want to group the results by host. When you sort on the host field and return the top 4 results, you get this: 
 

status 
 

host 
 

count 
 
200 
 
www1 
 
11835 
 
400 
 
www1 
 
233 
 
404 
 
www1 
 
244 
 
200 
 
www2 
 
11186 
 
See also 
 

head command 
 

head command usage 
head command examples 
 






286 
 
head command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

head 
 

[while "("<boolean-expression>")"] 
[<limit>]�h1h2h3}�h5Kuh�(h3h/�h}�ub�$98761de5-eadd-4c83-a4b0-0c491734c43c�h+)�}�(h}�(h/XZ11186 
 
See also 
 

head command 
 

head command usage 
head command examples 
 






286 
 
head command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

head 
 

[while "("<boolean-expression>")"] 
[<limit>] 
 

Required arguments 
 

None. If no options are specified, the head command returns the first 10 results. 
 

Optional arguments 
 

keeplast 
 

Description: Use in conjunction with the while argument to determine whether the last result in the result set is 
retained. The last result returned is the result that caused the <boolean-expression> to evaluate to false or NULL. 
Set keeplast=true to retain the last result in the result set. Set keeplast=false to discard the last result. 
 


limit 
 



Syntax: <integer> 
 

Default: 10 
 

while 
 


Syntax: while "("<boolean-expression>")" 
 

statistical functions in the expression. 
Default: false 
 

See also 
 

head command 
 

head command usage 
head command examples 
 


head command usage 
 

Differences between SPL and SPL2 
 






287 
 
Command options must be specified before command arguments 
 

Version 
 

Example 
 
SPL 
 
...head limit=10 (x>10) keeplast=true 
 
SPL2 
 
...head keeplast=true while (x>10) 10 
 
New while keyword 
 

SPL2 uses the while keyword to indicate that the head command accumulates events until the while condition is not met. 
 

Version 
 

Example 
 
SPL 
 
...head limit=20 (x>10) 
 
SPL2 
 
...head while (x>10) 20 
 


The limit keyword is not supported in SPL2 
 

The syntax has been simplified and the limit keyword is no longer necessary. 
 

Version 
 

Example 
 
SPL 
 
...head limit=10 
 
SPL2 
 
...head 10 
 


The null argument is not supported in SPL2 
 

The null=<boolean> argument is not supported. To handle fields with null values, you must use the isnull() or isnotnull() 
function. 
 

Version 
 

Example 
 

Example 
 
SPL 
 
...head null=true 
 
...head null=false 
 
SPL2 
 
...head while (isnotnull(host)) 
 
...head while (isnull(host) OR host="localhost") 
 
See also 
 

head command 
 

head command syntax details 
head command examples 
 


head command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6fbb767b-7010-4d48-8210-b41236f60c59�h+)�}�(h}�(h/XSPL2 
 
...head while (isnotnull(host)) 
 
...head while (isnull(host) OR host="localhost") 
 
See also 
 

head command 
 

head command syntax details 
head command examples 
 


head command examples 
 
The following are examples for using the SPL2 head command. To learn more about the head command, see How the 
head command works. 
 




288 
 
1. Include the first non-matching event in the results 
 

This example shows how the keeplast argument works. 
 

This example specifies to keep the last result that is evaluated, even when that result returns false for the while clause. A 
maximum of 123 results are returned. The while clause looks for events where the timestamp field value is greater than 
2020 and the error field value is equal to 1.2. When either of those conditions are not true, no further results are returned, 
except the last result evaluated. 
 

...| head keeplast=true 123 while (timestamp>2020 AND error==1.2) 
 

2. Returning results when data contains null values 
 

This example shows how to specify a condition with a <boolean-expression> in the while clause. 
 

This example returns up to 50 results even when a null value is encountered in the host field. 
 

...| head while (isnull(host) OR host="localhost") 50 
 

3. Return results for a specific time span 
 

This example returns results until the time span of the data is >= 100 seconds. 
 

This example uses the streamstats command to calculate a time range. Returns up to 10 results, which is the default 
number, or until the time span of the data is >= 100 seconds. 
 

... | streamstats range(_time) AS timerange | head (timerange<100) 
 

See also 
 

head command 
 

head command syntax details 
head command usage 
 






















289 
 
into command 
 


into command overview 
 
Appends to or replaces the contents of a dataset in the search data pipeline. The dataset must be a writeable dataset, 
also referred to as a dataset sink. 
 

Syntax 
 

The required syntax is in bold. 
 

into 
 

<dataset> 
 

How the into command works�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e1c38c3c-7c8b-4001-86b7-78c5d1089a04�h+)�}�(h}�(h/Xalso referred to as a dataset sink. 
 

Syntax 
 

The required syntax is in bold. 
 

into 
 

<dataset> 
 

How the into command works 
 

The into command does not return any results, so it must the last command in your search. 
 

Let's start with this search: 
 

FROM main WHERE earliest=-5m@m AND latest=@m GROUP BY host SELECT sum(bytes) AS sum, host HAVING sum > 
1024*1024 | into bytesUsage 
 

The following table describes what each command and clause is doing in the search: 
 

Command or 
	clause 
 


Description 
 
FROM command 
 
Searches the main dataset. 
 

WHERE clause 
 
Specifies to search only the last 5 minutes, starting at the beginning of the minute and stop at the beginning of the 
current minute. 
 
GROUP BY clause 
 
Organizes the results by the host field. 
 

SELECT clause 
 
Uses a calculation to sum the data in the bytes field and place the results in a field called sum. In addition, returns 
the host field. 
 
HAVING clause 
 
Filters the aggregated results to return only the sum of the bytes that are greater than 1 MB. 
 
into command 
 
Appends the results to the bytesUsage dataset. 
 
By default, the into command appends search results to a lookup or splv1sink dataset that you have write access to. The 
mode argument is only valid when the dataset is a lookup kind of dataset. See Dataset kinds in the SPL2 Search Manual. 
 

See also 
 

into command 
 

into command usage 
into command examples 
 



290 
 
Related commands 
 

thru command overview 
 

Related information 
 



into command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

into 
 

<dataset> 
 

Required arguments 
 

dataset 
 


Syntax: <dataset> 
 

created or a dataset that you are authorized to use. 
 

Optional arguments 
 

mode 
 


Syntax: mode=( append | replace ) 
 

applies to lookups. The mode is not used with datasets where the kind of dataset is spl1sink. 
Default: append 
 

See also 
 

into command 
 

into command usage 
into command examples 
 

Related information 
 



into command usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aab4d1cf-6f1b-4b9f-a809-450558f37130�h+)�}�(h}�(h/XODefault: append 
 

See also 
 

into command 
 

into command usage 
into command examples 
 

Related information 
 



into command usage 
 
The into command is a new command in SPL2. The into command is a terminating command; a command that does not 
return any results. Use the thru command if you want search results returned. See thru command overview. 
 




291 
 
You can use the into command to pipe data into different kinds of datasets. For example, you can pipe data into a lookup 
table dataset or splv1sink dataset, such as ingest.events which is globally accessible for use with Data Stream 
Processor (DSP). 
 



See also 
 

into command 
 

into command syntax details 
into command examples 
 


into command examples 
 
The following are examples for using the SPL2 into command. To learn more about the into command, see How the into 
command works. 
 

1. Append search results to a dataset 
 

Append the search results to the mytable dataset, which is a lookup kind of dataset. 
 

... | into mode=append mytable 
 

See also 
 

into command 
 

into command syntax details 
into command usage 
 

























292 
 
join command 
 


join command overview 
 
Use the join command to combine the left-side dataset with the right-side dataset, by using one or more common fields. 
The left-side dataset is the set of results from a search that is piped into the join command. The left-side dataset is 
sometimes referred to as the source data. The right-side dataset can be either a saved dataset or a subsearch. 
 

A maximum of 50000 rows in the right-side dataset can be joined with the left-side dataset. This maximum is set to limit 
the impact of the join command on performance and resource consumption. 
 

The simplest join possible looks like this: 
 


<left-dataset> | join left=L right=R 
where L.pid = R.pid <right-dataset> 
 
This joins the source data from the search pipeline with the right-side dataset. Rows from each dataset are merged into a 
single row if the where predicate is satisfied. 
 

Syntax 
 

The required syntax is in bold. 
 

join 
(<join-options>...)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aa69f172-fb4d-4338-bd0b-66a233349365�h+)�}�(h}�(h/X�single row if the where predicate is satisfied. 
 

Syntax 
 

The required syntax is in bold. 
 

join 
(<join-options>...) 
left=<left-alias> 
right=<right-alias> 
 

[ AND <left-alias>.<left-field>=<right-alias>.<right-field> ]... 
<right-dataset> 
 

You can specify the aliases and fields in where clause on either side of the equal sign. For example you can 
specify:where <left-alias>.<left-field>=<right-alias>.<right-field> or where 
<right-alias>.<right-field>=<left-alias>.<left-field> 
 




See also 
 

join command 
 

join command usage 
join command examples 
 


join command syntax details 
 
The required syntax is in bold. 
 

293 
 
Syntax 
 

join 
(<join-options>...) 
left=<left-alias> 
right=<right-alias> 
 

<right-dataset> 
 

Required arguments 
 

left 
 


Syntax: left=<left-alias> 
 


right 
 



Syntax: right=<right-alias> 
 


where 
 



Syntax: where <left-alias>.<left-field>=<right-alias>.<right-field> ... 
 

You must specify the alias and the field name. For example: L.host=R.user. To join on multiple fields, you must 
specify AND operator between each set of fields. For example: L.host=R.user AND L.clientip=R.clientip. 
 

You can specify the aliases and fields in where clause on either side of the equal sign. 
For example, you can specify: 
 
where <left-alias>.<left-field>=<right-alias>.<right-field> 
 
or 
 
where <right-alias>.<right-field>=<left-alias>.<left-field> 
 

right-dataset 
 

Description: The name of the right-side dataset or the subsearch that you want to use to join with the source 
data. If you specify a dataset, it must be a dataset that you created or are authorized to use. If you specify a 
subsearch, it must be enclosed in square brackets. A maximum of 50000 rows in the right-side dataset can be 
joined with the left-side dataset. 
 

Optional arguments 
 

join-options 
 

Description: Specify the type of join to perform and the maximum number of rows to join on. You can specify one 
or more <join-options>. 
 

type 
 


Syntax: type=<inner | outer | left>�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ff0b90dc-2fed-421e-ae7f-2b55b28bcb2e�h+)�}�(h}�(h/Xjoin-options 
 

Description: Specify the type of join to perform and the maximum number of rows to join on. You can specify one 
or more <join-options>. 
 

type 
 


Syntax: type=<inner | outer | left> 
 

the rows are treated in the left-side dataset that do not match any of the rows in the right-side dataset. In both 
inner and left joins, rows that match are joined. The results of an inner join do not include rows from the left-side 
 



294 
 
in the left-side dataset and only those values in the right-side dataset have matching field values. 
Default: inner 
 

max 
 


Syntax: max=<int> 
 

dataset can join with. The default setting means that 1 row in the right-side dataset can join with just 1 row in the 
left-side dataset. If set to max=0, multiple rows in the right-side dataset join with 1 row in the left-side dataset. 
Default: 1 
 

See also 
 

join command 
 

join command usage 
join command examples 
 


join command usage 
 
The join command is a centralized streaming command, which means that rows are processed one by one. If you are 
joining two large datasets, the join command can consume a lot of resources. 
 

For flexibility and performance, consider using one of the following commands if you do not require join semantics: 
 

• lookup command. Use this command when one of the datasets remains static or rarely changes. You can use KV 
	store lookups with SPL2. For example, a file from an external system such as a CSV file. 
 

and then use the stats command to perform the grouping operation on the events. 
 

determine the average duration of events by host name. To use stats, the field must have a unique identifier. 
 


The simplest join possible looks like this: 
 


<source> | join left=L right=R 
 

This joins the source, or left-side dataset, with the right-side dataset. Rows from each dataset are merged into a single 
row if the where predicate is satisfied. 
 

If you're familiar with SQL, the above example is shorthand for this: 
 


<left-side dataset> | join left=L right=R 
type=inner max=1�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d53760f9-6d9c-431d-946d-d63d6172b8ba�h+)�}�(h}�(h/X�row if the where predicate is satisfied. 
 

If you're familiar with SQL, the above example is shorthand for this: 
 


<left-side dataset> | join left=L right=R 
type=inner max=1 
 

One-to-many and many-to-many relationships 
 

To return matches for one-to-many, many-to-one, or many-to-many relationships, include the max argument in your join 
syntax and set the value to 0. By default max=1, which means that the <dataset> returns only the first result from the 
<dataset>. Setting the value to a higher number or to 0, which is unlimited, returns multiple results from the <dataset>. 
 

295 
 
Differences between SPL and SPL2 
 

There are significant differences in the join command between SPL and SPL2. 
 

The SPL2 join command performs very much like a SQL join and has similar syntax to a SQL join. With SPL you are 
actively encouraged to use other commands instead of the join command because in SPL the join command does not 
perform like a SQL join. 
 

With SPL2, the only arguments in the syntax that are not required are the <join-options>. Some of the SPL <join-options> 
are not supported in SPL2. Specifically the usetime, earlier, and overwrite join options are not supported. 
 

SPL2 uses a very different syntax 
 

The syntax for the join command is completely different. You must specify field aliases. Field names are required. 
 

Version 
 

Syntax 
 
SPL 
 
[join-options...][field-list] subsearch 
 
join 
 



SPL2 
 

(<join-options>...) 
left=<left-alias> 
right=<right-alias> 
 

[ AND <left-alias>.<left-field>=<right-alias>.<right-field> ]... 
<right dataset> 
 


Field names to join on can be different 
 

Field names do not have to be renamed so that you can join on the key fields. This example joins the incoming search 
results with the products dataset. 
 

Version 
 

Example 
 
SPL 
 
rename vid AS vendor_id] 
 
SPL2 
 
... join left=L right=R where L.vendorID=R.vid products 
 
See also 
 

join command 
 

join command syntax details 
join command examples 
 


join command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9ea8207c-35cd-43d9-822c-40954239b03d�h+)�}�(h}�(h/X�SPL 
 
rename vid AS vendor_id] 
 
SPL2 
 
... join left=L right=R where L.vendorID=R.vid products 
 
See also 
 

join command 
 

join command syntax details 
join command examples 
 


join command examples 
 
The following are examples for using the SPL2 join command. To learn more about the join command, see How the join 
command works. 
 


296 
 
1. Join datasets on fields that have the same name 
 

Combine the results from a search with the vendors dataset. The data is joined on the product_id field, which is common 
to both datasets. 
 

... | join left=L right=R where L.product_id=R.product_id vendors 
 

2. Join datasets on fields that have different names 
 

Combine the results from a search with the vendors dataset. The data is joined on a product ID field, which have different 
names. The field in the left-side dataset is product_id. The field in the right-side dataset is pid. 
 

... | join left=L right=R where L.product_id=R.pid vendors 
 

3. Use words instead of letters as aliases 
 

You can use words for the aliases to help identify the datasets involved in the join. This example uses products and 
vendors for the aliases. 
 

... | join left=products right=vendors where products.product_id=vendors.pid vendors 
 

4. Return all matching rows in the right-side dataset 
 

By default, only the first row of the right-side dataset that matches a row of the source data is returned. To return all of the 
matching right-side dataset rows, include the max=<int> argument and set the value to 0. This example joins each 
matching right-side dataset row with the corresponding source data row. This example uses products, which is a saved 
dataset, for the right-side dataset. In this example the field names in the left-side dataset and the right-side dataset are 
different. 
 

... | join max=0 left=L right=R where L.vendor_id=R.vid products 
 

5. Return all matching rows in a subsearch 
 

This example uses a subsearch for the right-side dataset.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a4db9a76-095e-4509-a25e-e36f63400862�h+)�}�(h}�(h/Xrdifferent. 
 

... | join max=0 left=L right=R where L.vendor_id=R.vid products 
 

5. Return all matching rows in a subsearch 
 

This example uses a subsearch for the right-side dataset. 
 

... | join left=vendor right=products where vendor.vendor_id=products.vid [ <subsearch> ] 
 

See also 
 

join command 
 

join command syntax details 
join command usage 
 











297 
 
lookup command 
 


lookup command overview 
 
Use the lookup command to enrich your source data with related information that is in a lookup dataset. Field-value pairs 
in your source data are matched with field-value pairs in a lookup dataset. You can either append to or replace the values 
in the source data with the values in the lookup dataset. 
 

Syntax 
 

The required syntax is in bold. 
 

lookup <lookup-dataset> (<lookup-field> [AS <event-field>] )... 
 


How the lookup command works 
 

The following lookup dataset, named products, contains product information and prices for a set of board and card 
games. For example: 
 

product_id 
 

product_name 
 

price 
 
DB-SG-G01 
 
Mediocre Kingdoms 
 
24.99 
 
DC-SG-G02 
 
Dream Crusher 
 
39.99 
 
FS-SG-G03 
 
Final Sequel 
 
24.99 
 
WC-SH-G04 
 
World of Cheese 
 
24.99 
 
The events contain the field productID. A search was run to summarize the total number of purchase transactions, the 
total number of products purchased, and the product IDs. The results are organized by ipaddress. 
 

This is a sample of the search results. The products are identified by the productID. 
 

ipaddress 
 

total_purchases 
 

total_products 
 

productID 
 
DB-SG-G01 
 
107.3.146.207 
 
72 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 

128.241.220.82 
 

95 
 

2 
 
DB-SG-G01 

DC-SG-G02 
 
DB-SG-G01 
 

194.215.205.19 
 

60 
 

4 
 

DC-SG-G02 
FS-SG-G03 
WC-SH-G04 
 


298 
 
ipaddress 
 
total_purchases 
 
total_products 
 
productID 
 

211.166.11.101 
 

91 
 

2 
 
DB-SG-G01 

WC-SH-G04 
 
DC-SG-G02 
 
87.194.216.51 
 
134 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 
You can use the lookup command to lookup the product_id in the products dataset, match that with the productID in the 
events, and return the product_name.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$aa15a21d-1a50-43a6-97bc-04fdaf93b8f5�h+)�}�(h}�(h/XM87.194.216.51 
 
134 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 
You can use the lookup command to lookup the product_id in the products dataset, match that with the productID in the 
events, and return the product_name. 
 

...| lookup products product_id AS productID OUTPUT product_name 
 

The results would look like this: 
 

ipaddress 
 

total_purchases 
 

total_products 
 

productID 
 

product_name 
 
DB-SG-G01 
 
Dream Crusher 
 
107.3.146.207 
 
72 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 

Final Sequel 
World of Cheese 
 

128.241.220.82 
 

95 
 

2 
 
DB-SG-G01 

DC-SG-G02 
 
Mediocre Kingdoms 

Dream Crusher 
 
DB-SG-G01 
 
Mediocre Kingdoms 
 

194.215.205.19 
 

60 
 

4 
 

DC-SG-G02 
FS-SG-G03 
WC-SH-G04 
 

Dream Crusher 
Final Sequel 
World of Cheese 
 

211.166.11.101 
 

91 
 

2 
 
DB-SG-G01 

WC-SH-G04 
 
Mediocre Kingdoms 

World of Cheese 
 
DC-SG-G02 
 
Dream Crusher 
 
87.194.216.51 
 
134 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 

Final Sequel 
World of Cheese 
 
See also 
 

lookup command 
 

lookup command usage 
lookup command examples 
 







299 
 
lookup command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

lookup <lookup-dataset> (<lookup-field> [AS <event-field>] )... 
 


The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can 
specify this keyword in uppercase or lowercase. 
 

Required arguments 
 

lookup-dataset 
 

Description: The name of the lookup table that is defined as a dataset in the Metadata Catalog. 
 

lookup-field 
 

Description: A field in the lookup dataset to match against the search results. You can specify multiple 
<lookup-field> values. 
 

Optional arguments 
 

event-field 
 

Description: A field in the incoming search results to match with a field in the <lookup-dataset>. You don't need 
to specify the <event-field> if the name of the <event-field> is the same as the name of the <lookup-field>. You 
can specify multiple <event-field> values. 
 


OUTPUT | OUTPUTNEW 
 

Description: Specifies whether to replace or append values from the lookup dataset to the search results.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f39ca205-c7ca-43fb-b9bc-249dec6b4a81�h+)�}�(h}�(h/X�can specify multiple <event-field> values. 
 


OUTPUT | OUTPUTNEW 
 

Description: Specifies whether to replace or append values from the lookup dataset to the search results. 
OUTPUT replaces values in existing search results fields with values from the lookup dataset. Where there is no 
value in a field, OUTPUT adds values from the lookup dataset to the search results fields. OUTPUTNEW 
 

fields specified in <lookup-field>, the OUTPUTNEW argument only fills in missing values in those fields. OUTPUT 
and OUTPUTNEW must be specified in uppercase. 
 


lookup-destfield 
 

Description: A field in the lookup table to be applied to the search results. You can specify multiple 
<lookup-destfield> values. Used with OUTPUT | OUTPUTNEW to replace or append field values. 
Default: All fields are applied to the search results if no fields are specified. 
 

event-destfield 
 


300 
 
Description: A field in the search results. You can specify multiple <event-destfield> values. If the name of the 
<event-destfield> is the same as the <lookup-destfield>, you don't need to specify the <event-destfield>. The 
name of the <lookup-destfield> is used. Used with OUTPUT | OUTPUTNEW to replace or append field values. 
Default: The value of <lookup-destfield>. 
 

See also 
 

lookup command 
 

lookup command usage 
lookup command examples 
 


lookup command usage 
 
If an OUTPUT or OUTPUTNEW clause is not specified, all of the fields in the lookup table that are not the match field are 
used as output fields. 
 

If the OUTPUT clause is specified, the output lookup fields overwrite existing fields with the same name. 
 

If the OUTPUTNEW clause is specified, the lookup is not performed for events in which the output fields already exist. 
 

Optimization 
 

Whenever possible, perform lookups after transforming commands like stats and timechart. 
 

A transforming command acts like a filter. Running the transforming command before the lookup can minimize the work�h1h2h3}�h5Kuh�(h3h/�h}�ub�$16ed67fc-5ffa-4654-b71f-4e3c545308de�h+)�}�(h}�(h/X,A transforming command acts like a filter. Running the transforming command before the lookup can minimize the work 
that the lookup command must do, if the field needed for the lookup is retained by the transforming command. 
 

Here's an example of an optimized search. The transforming command stats is before the lookup command. The stats 
command retains the status field, which is the field needed for the lookup. 
 

from <dataset> where sourcetype=access_* | stats count() by status | lookup status_desc status OUTPUT 
description 
 

Here's the same search, but it is not optimized. The lookup is before the transforming command stats. In this example 
 

field. There is no optimization advantage to running the stats command before the lookup. 
 

from <dataset> where sourcetype=access_* | lookup status_desc status OUTPUT description | stats count() by 
description 
 

The lookup in the first search is faster because it only needs to match the results of the stats command and not all the 
Web access events. 
 

Differences between SPL and SPL2 
 

The command options have been removed 
 

The command options local and update are not supported in SPL2. 
 



301 
 
Version 
 
Example 
 
SPL 
 
... lookup [local=<bool>] update=<bool> <lookup-dataset>... 
 
SPL2 
 
Not supported 
 
The list of lookup fields must be comma-delimited 
 

Version 
 

Example 
 
SPL 
 
... lookup lookupDataset key1 AS field1 key2 AS field2 
 
SPL2 
 
... lookup lookupDataset key1 AS field1, key2 AS field2 
 
The list of output fields must be comma-delimited 
 

Version 
 

Example 
 
SPL 
 
... lookup lookupDataset key1 AS field1 OUTPUT out1 AS event1 out2 AS event2 
 
SPL2 
 
... lookup lookupDataset key1 AS field1 OUTPUT out1 AS event1, out2 AS event2 
 
See also 
 

lookup command 
 

lookup command syntax usage 
lookup command examples 
 


lookup command examples 
 
The following are examples for using the SPL2 lookup command. To learn more about the lookup command, see How the 
lookup command works. 
 

1. Put corresponding information from a lookup dataset into your events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0b802927-28c4-410e-9984-a10712555356�h+)�}�(h}�(h/X\lookup command works. 
 

1. Put corresponding information from a lookup dataset into your events 
 

This example appends the data returned from your search results with the data in the users lookup dataset using the uid 
field. 
 

The users lookup dataset contains this data: 
 

uid 
 

username 
 

department 
 
1066 
 
Claudia Garcia 
 
Engineering 
 
1690 
 
Rutherford Sullivan 
 
Engineering 
 
1815 
 
Vanya Patel 
 
IT 
 
1862 
 
Wei Zhang 
 
Engineering 
 
1916 
 
Alex Martin 
 
Personnel 
 
The events look something like this: 
 

_time 
 

host 
 

action 
 

department 
 

uid 
 


302 
 
1:02:45 PM 13 Apr 2022 
 
mailsv2 
 
Failed password 
 
Engineering 
 
1066 
 
10:52:41 AM 13 Apr 2022 
 
mailsv1 
 
Failed password 
 
IT 
 
1815 
 
6:23:48 AM 13 Apr 2022 
 
mailsv3 
 
Session closed 
 
1916 
 
6:23:48 AM 13 Apr 2022 
 
mailsv3 
 
Failed password 
 
8:18:36 PM 12 Apr 2022 
 
mailsv1 
 
Session closed 
 
Engineering 
 
1690 
 
The third event is missing the department. The fourth event is missing the department and the uid. 
 

When you run the following search, for search results that contains a uid field, the value in that field are matched with the 
uid field in the users lookup dataset. 
 

... | lookup users uid OUTPUTNEW username, department 
 

The username and department fields from the users lookup dataset are appended to each search result. If the search 
results already have the username and department fields, the OUTPUTNEW argument only fills in missing values in those 
 


_time 
 


host 
 


action 
 


department 
 


uid 
 


username 
 
1:02:45 PM 13 Apr 2022 
 
mailsv2 
 
Failed password 
 
Engineering 
 
1066 
 
Claudia Garcia 
 
10:52:41 AM 13 Apr 2022 
 
mailsv1 
 
Failed password 
 
IT 
 
1815 
 
Vanya Patel 
 
6:23:48 AM 13 Apr 2022 
 
mailsv3 
 
Session closed 
 
Personnel 
 
1916 
 
Alex Martin 
 
6:23:48 AM 13 Apr 2022 
 
mailsv3 
 
Failed password 
 
8:18:36 PM 12 Apr 2022 
 
mailsv1 
 
Session closed 
 
Engineering 
 
1690 
 
Rutherford Sullivan 
 
Because the third event was missing the department, the department name is added to the search results. The fourth�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8b993dd7-4af3-45eb-badb-91a3b8fff805�h+)�}�(h}�(h/Xpmailsv1 
 
Session closed 
 
Engineering 
 
1690 
 
Rutherford Sullivan 
 
Because the third event was missing the department, the department name is added to the search results. The fourth 
event was missing the department and the uid. Because there is no uid to match on, there are no changes to the search 
results for that event. 
 

2. Replace data in your events with data from a lookup dataset 
 

This example replaces the data returned from the search results with data in the addresses lookup dataset. It maps each 
value in the CustID field in the lookup dataset with the matching value in the cid field in the search results. Find the 
corresponding CustAddress value and use the address in the lookup dataset to replace the cAddress in the search results. 
 

...| lookup addresses CustID AS cid OUTPUT CustAddress AS cAddress 
 

3. Lookup users and return the corresponding group the user belongs to 
 

There is a KV store lookup dataset called usertogroup. The dataset contains multiple fields, including user and group. The 
values in the user field in the lookup dataset are mapped to the corresponding value of the field local_user in the search 
results. For any entries that match, the value of the group field in the lookup dataset is written to the field user_group in 
 


... | lookup usertogroup user AS local_user OUTPUTNEW group 
 




303 
 
See also 
 

lookup command 
 

lookup command syntax details 
lookup command usage 
 
























































304 
 
mvexpand command 
 


mvexpand command overview 
 
Expands the values in a multivalue field into separate events, one event for each value in the multivalue field. 
 

Syntax 
 

The required syntax is in bold. 
 

mvexpand 
[limit=<int>] 
<field> 
 

How the mvexpand command works 
 

The mvexpand command creates individual events, or rows, for each value in a multivalue field. For example, the following 
search results contain the field productId which has multiple values. 
 

ipaddress 
 

total_purchases 
 

total_products 
 

productId 
 
DB-SG-G01 
 
107.3.146.207 
 
72 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 

128.241.220.82 
 

95�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0f0f96a5-050e-474e-aef7-2a4f5ad5bd3b�h+)�}�(h}�(h/X�search results contain the field productId which has multiple values. 
 

ipaddress 
 

total_purchases 
 

total_products 
 

productId 
 
DB-SG-G01 
 
107.3.146.207 
 
72 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 

128.241.220.82 
 

95 
 

2 
 
DB-SG-G01 

DC-SG-G02 
 
DB-SG-G01 
 

194.215.205.19 
 

60 
 

4 
 

DC-SG-G02 
FS-SG-G03 
WC-SH-G04 
 

211.166.11.101 
 

91 
 

2 
 
DB-SG-G01 

WC-SH-G04 
 
DC-SG-G02 
 
87.194.216.51 
 
134 
 
3 
 

FS-SG-G03 
WC-SH-G04 
 
If you add ... | mvexpand productId to your search, a new row is created for each product ID. The multivalued fields are 
expanded into individual search results. The other fields are unchanged. 
 

The results look something like this: 
 

ipaddress 
 

total_purchases 
 

total_products 
 

productId 
 

305 
 
107.3.146.207 
 
72 
 
3 
 
DB-SG-G01 
 
107.3.146.207 
 
72 
 
3 
 
FS-SG-G03 
 
107.3.146.207 
 
72 
 
3 
 
WC-SH-G04 
 
128.241.220.82 
 
95 
 
2 
 
DB-SG-G01 
 
128.241.220.82 
 
95 
 
2 
 
DC-SG-G02 
 
194.215.205.19 
 
60 
 
4 
 
DB-SG-G01 
 
194.215.205.19 
 
60 
 
4 
 
DC-SG-G02 
 
194.215.205.19 
 
60 
 
4 
 
FS-SG-G03 
 
194.215.205.19 
 
60 
 
4 
 
WC-SH-G04 
 
See also 
 

mvexpand command 
 

mvexpand command usage 
mvexpand command examples 
 


mvexpand command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

mvexpand 
[limit=<int>] 
<field> 
 

Required arguments 
 

field 
 


Syntax: <field> 
 




Optional arguments 
 

limit 
 


Syntax: limit=<int> 
 

values in the array those values are dropped. If omitted limit defaults to 0, which means there is no limit and all 
values are expanded. 
 




306 
 
See also 
 

mvexpand command 
 

mvexpand command usage 
mvexpand command examples 
 


mvexpand command usage 
 
You can use evaluation functions and statistical functions on multivalue fields or to create multivalue fields. 
 

• See Overview of SPL2 eval functions 
 


Differences between SPL and SPL2 
 

Command options must be specified before command arguments 
 

Version 
 

Example 
 
SPL 
 
...mvexpand myfield limit=10 
 
SPL2 
 
...mvexpand limit=10 myfield 
 


See also 
 

mvexpand command 
 

mvexpand command syntax details 
mvexpand command examples 
 


mvexpand command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8cbdae30-05ac-473d-a473-9f681b52eaef�h+)�}�(h}�(h/X=Example 
 
SPL 
 
...mvexpand myfield limit=10 
 
SPL2 
 
...mvexpand limit=10 myfield 
 


See also 
 

mvexpand command 
 

mvexpand command syntax details 
mvexpand command examples 
 


mvexpand command examples 
 
The following are examples for using the SPL2 mvexpand command. To learn more about the mvexpand command, see 
How the mvexpand command works. 
 

1. Expand the values in a specific field 
 

Suppose you have the fields a, b, and c. Each field has the following corresponding values: 
 

a 
 

b 
 

c 
 
1 
 
x 
 
V1, V2, V3 
 
2 
 
y 
 
V4, V5 
 

You run the mvexpand command and specify the c field. 
 


307 
 
... | mvexpand c 
 

This example takes each row from the incoming search results and then create a new row with for each value in the c 
field.The other fields will have duplicate values, while the c field will have each value from the multivalue field in a 
separate row. 
 

a 
 

b 
 

c 
 
1 
 
x 
 
V1 
 
1 
 
x 
 
V2 
 
1 
 
x 
 
V3 
 
2 
 
y 
 
V4 
 
2 
 
y 
 
V5 
 
2. Limit the number of values from the multivalue field to expand 
 

Limit the number of values to expand to 10. Any remaining values are dropped. 
 

... | mvexpand limit=10 my_mvfield 
 

See also 
 

mvexpand command 
 

mvexpand command syntax details 
mvexpand command usage 
 































308 
 
rename command 
 


rename command overview 
 
Use the rename command to rename one or more fields. This command is useful for giving fields more meaningful names, 
such as Product ID instead of pid. If you want to rename fields with similar names, you can use a wildcard character. 
 

Syntax 
 

The required syntax is in bold. 
 

rename 
 


How the rename command works 
 

Use the rename command to rename a field in your search results. 
 

Sometimes a field name in your data is an abbreviation and it's useful to rename the field so that others clearly 
understand what data the field shows. 
 

Suppose you have a field called dpt, which could an abbreviation for all sorts of things like: 
 

• Dollar per Transaction 
• Days Prior To 
 

• Double Plays Turned�h1h2h3}�h5Kuh�(h3h/�h}�ub�$74543180-c805-4172-a773-c0b99d9df767�h+)�}�(h}�(h/X
understand what data the field shows. 
 

Suppose you have a field called dpt, which could an abbreviation for all sorts of things like: 
 

• Dollar per Transaction 
• Days Prior To 
 

• Double Plays Turned 
 

You can make the field name clearer to anyone viewing the search results by renaming the field: 
 

... | rename dpt AS department 
 

Field names with special characters 
 

When you rename a field and specify a name that has a space, you need to enclose the name in single quotation marks. 
Here's an example: 
 

... | rename productName AS 'Product Name' 
 

You must use single quotation marks on field names that include special characters, spaces, dashes, and wildcards. See 
Quotation marks in the SPL2 Search Manual. 
 

Commands and clauses with built-in renaming options 
 

Some commands, such as stats, have a built-in rename option using the AS keyword. When you use a statistical 
function, the field that the stats command creates in the search results includes the function name. For example, your 
search calculates the average of the bytes field: 
 

... | stats avg(bytes) 
 


309 
 
The field in the output is named avg(bytes) by default. You can rename the field using the AS keyword: 
 

... | stats avg(bytes) AS 'average bytes' 
 

Similarly, you can specify an expression in the SELECT clause in the from command that includes a rename. For 
example: 
 

SELECT count(action) AS 'Action Count'... 
 

See also 
 

rename command 
 

rename command usage 
rename command examples 
 


rename command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

rename 
 


The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can 
specify the AS keyword in uppercase or lowercase. 
 

Required arguments 
 

source-field 
 

Description: The name of a field in your search results to rename. You can use a wild card character in the field 
name. Names with anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in�h1h2h3}�h5Kuh�(h3h/�h}�ub�$459b2ecb-561e-450f-b919-5037f130df24�h+)�}�(h}�(h/XZname. Names with anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be enclosed in 
single-quotation marks. This includes the wildcard character ( * ). 
 

target-field 
 

Description: The name you want to use as the replacement name for the field. You can use a wild card character 
in the field name. Names with anything other than a-z, A-Z, 0-9, or the underscore ( _ ) character must be 
enclosed in single-quotation marks. This includes the wildcard character ( * ). 
 

The replacement name you specify for the field can't be a reserved word. For a list of the reserved words, see 
Reserved words. 
 

See also 
 

rename command 
 


310 
 
rename command usage 
rename command examples 
 


rename command usage 
 

Differences between SPL and SPL2 
 

Renames must be comma-delimited 
 

Each pair of rename fields must be separated by a comma. Otherwise a parsing error is returned. 
 

Version 
 

Example 
 
SPL 
 
rename pid AS ProductID cid AS CustomerID 
 
SPL2 
 
rename pid AS ProductID, cid AS CustomerID 
 
Certain renames are invalid 
 

Renames of the same field is not allowed. 
 

Version 
 

Example 
 
SPL 
 
...rename A as B, A as C 
 
SPL2 
 
Not supported 
 
Merging multiple fields is invalid 
 

Attempting to merge multiple fields with a rename is not allowed. 
 

Version 
 

Example 
 
SPL 
 
... rename A as B, C as B 
 
SPL2 
 
Not supported 
 
Chained or circular renaming is invalid 
 

Using transitive renames that result in chained renaming or circular naming is not allowed. 
 

Version 
 

Example 1 
 

Example 2 
 
SPL 
 
... rename A as B, B as C 
 
... rename A as B, C as A 
 
SPL2 
 
Not supported 
 
Not supported 
 
See also 
 

rename command 
 

rename command syntax details 
rename command examples 
 





311 
 
rename command examples 
 
The following are examples for using the SPL2 rename command. To learn more about the rename command, see How the 
rename command works. 
 

The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can specify 
the AS keyword in uppercase or lowercase in your searches.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$a4ce3f3a-5d62-4daf-9522-316ec4688db3�h+)�}�(h}�(h/X9The AS keyword is displayed in uppercase in the syntax and examples to make the syntax easier to read. You can specify 
the AS keyword in uppercase or lowercase in your searches. 
 

1. Rename one field 
 

Rename the usr field to username. 
 

...| rename usr AS username 
 

2. Rename a field with special characters 
 

Rename the ip-add field to IPAddress. Field names that contain anything other than a-z, A-Z, 0-9, or "_", need 
single-quotation marks. 
 

... | rename 'ip-add' AS IPAddress 
 

3. Specify multiple fields to rename 
 

Use a comma-separated list of renames that you want to perform. This example renames usr to username and dpt to 
department. Renames are processed in the order that you specify, left to right. 
 

...| rename usr AS username, dpt AS department 
 

4. Rename multiple similarly named fields using wildcards 
 

This example renames any field that starts with u to start with user. Because wildcard characters are used, the field 
names must be enclosed in single quotation marks. 
 

...| rename 'u*' AS 'user*' 
 

5. Rename a field with a phrase 
 

This example renames a field with a string phrase. Because the phrase includes spaces, the field name must be enclosed 
in single quotation marks. 
 

... | rename count AS 'Count of Events' 
 

6. Rename a field to remove the JSON path information 
 

Suppose you have fields with the following names: 
 

games.cooperative.Forbidden 
	Island 
 


games.cooperative.Pandemic 
 

games.cooperative.Sherlock Holmes: 
	Consulting Detective 
 
In stock 
 
in stock 
 
out of stock 
 



312 
 
You can use the rename command with a wildcard to remove the path information from the field names. The following 
search identifies the path information that you want to remove and returns only the information that remains. In this 
example, the remaining information are the names of the games: 
 

...| rename 'games.cooperative.*' AS '*' 
 

The results look like this: 
 

Forbidden Island 
 

Pandemic 
 

Sherlock Holmes: Consulting Detective 
 
In stock 
 
in stock 
 
out of stock 
 
See also 
 

rename command�h1h2h3}�h5Kuh�(h3h/�h}�ub�$33896521-1fa2-44b2-80ca-c8b1633d3126�h+)�}�(h}�(h/X	...| rename 'games.cooperative.*' AS '*' 
 

The results look like this: 
 

Forbidden Island 
 

Pandemic 
 

Sherlock Holmes: Consulting Detective 
 
In stock 
 
in stock 
 
out of stock 
 
See also 
 

rename command 
 

rename command syntax details 
rename command usage 
 










































313 
 
reverse command 
 


reverse command overview 
 
Reverses the order of the search results. 
 

Syntax 
 

The required syntax is in bold. 
 

reverse 
 

How the reverse command works 
 

The reverse command reverses the rows in the search results. 
 

For example, suppose you have a search that calculate aggregate statistics for the magnitudes of earthquakes in and 
around California. You use statistical functions to calculate the count, minimum, maximum, range (the difference between 
the min and max), and average magnitudes of the recent earthquakes. You list the values by magnitude type magType. 
 

source=all_month.csv place=*California* | stats count, max(mag), min(mag), range(mag), avg(mag) BY magType 
 

The results look something like this: 
 

magType 
 

count 
 

max(mag) 
 

min(mag) 
 

range(mag) 
 

avg(mag) 
 
H 
 
123 
 
2.8 
 
0.0 
 
2.8 
 
0.549593 
 
MbLg 
 
1 
 
0 
 
0 
 
0 
 
0.0000000 
 
Md 
 
1565 
 
3.2 
 
0.1 
 
3.1 
 
1.056486 
 
Me 
 
2 
 
2.0 
 
1.6 
 
.04 
 
1.800000 
 
Ml 
 
1202 
 
4.3 
 
-0.4 
 
4.7 
 
1.226622 
 
Mw 
 
6 
 
4.9 
 
3.0 
 
1.9 
 
3.650000 
 
ml 
 
10 
 
1.56 
 
0.19 
 
1.37 
 
0.934000 
 
Because the search uses a BY clause, the results are sorted by magnitude type magType. 
 

Notice the last magType value. The default sort order used is Lexicographical sort order, where uppercase letters come 
before lowercase letters. 
 

If you add the reverse command to the end of the search the rows of the results are reversed. 
 

source=all_month.csv place=*California* | stats count, max(mag), min(mag), range(mag), avg(mag) BY magType | 
reverse 
 

magType 
 

count 
 

max(mag) 
 

min(mag) 
 

range(mag) 
 

avg(mag) 
 
ml 
 
10 
 
1.56 
 
0.19 
 
1.37 
 
0.934000 
 

314 
 
magType 
 
count 
 
max(mag) 
 
min(mag) 
 
range(mag) 
 
avg(mag) 
 

Mw 
 

6 
 

4.9 
 

3.0 
 

1.9 
 

3.650000 
 
Ml 
 
1202 
 
4.3 
 
-0.4 
 
4.7 
 
1.226622 
 
Me 
 
2 
 
2.0 
 
1.6 
 
.04 
 
1.800000 
 
Md 
 
1565 
 
3.2 
 
0.1�h1h2h3}�h5Kuh�(h3h/�h}�ub�$51d6dc49-f8e8-446a-ab53-4b0c8ac01aeb�h+)�}�(h}�(h/Xx1.37 
 
0.934000 
 

314 
 
magType 
 
count 
 
max(mag) 
 
min(mag) 
 
range(mag) 
 
avg(mag) 
 

Mw 
 

6 
 

4.9 
 

3.0 
 

1.9 
 

3.650000 
 
Ml 
 
1202 
 
4.3 
 
-0.4 
 
4.7 
 
1.226622 
 
Me 
 
2 
 
2.0 
 
1.6 
 
.04 
 
1.800000 
 
Md 
 
1565 
 
3.2 
 
0.1 
 
3.1 
 
1.056486 
 
MbLg 
 
1 
 
0 
 
0 
 
0 
 
0.0000000 
 
H 
 
123 
 
2.8 
 
0.0 
 
2.8 
 
0.549593 
 
See also 
 

reverse command 
 

reverse command usage 
reverse command examples 
 


reverse command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

reverse 
 

Required arguments 
 


Syntax: reverse 
 


See also 
 

Reverse command 
 

reverse command usage 
reverse command examples 
 


reverse command usage 
 
The reverse command does not affect which events are returned by the search, only the order in which the results are 
displayed. 
 

Very large result sets 
 

Using the reverse command on very large search result sets might result in the search being prematurely cancelled. Very 
large search result sets, such as sets with millions of results or more, can consume a vast quantity of processing 
 

315 
 
resources. 
 

To avoid this issue, try to reduce the number of results returned before you use the reverse command. 
 

Use sort to order results by a specific field 
 

The reverse command reverses the order of the rows in your search results. The reverse command does not change the 
order of the rows based on the values in a particular field. 
 

The sort command sorts the search results based on the values in the field you specify. Use the sort command if you 
want to change the order of the search results based on a particular field. 
 

Multivalue fields 
 

If the results contain a multivalue field, the results in that field remain unchanged. The reverse command does not impact 
the order of the values in the multivalue field. 
 

See also 
 

reverse command 
 

reverse command syntax details 
reverse command examples 
 

Other commands 
 



reverse command examples 
 
The following are examples for using the SPL2 reverse command. To learn more about the reverse command, see How 
the reverse command works. 
 

1. Reverse events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$222d0902-00b0-4d83-9efc-a967226423e4�h+)�}�(h}�(h/X�reverse command examples 
 
The following are examples for using the SPL2 reverse command. To learn more about the reverse command, see How 
the reverse command works. 
 

1. Reverse events 
 

This example shows a set of events returned from a search. By default, events are returned with the most recent event 
first. 
 

Time 
 

Event 
 

17 Sep 2021 
6:20:54.000 
PM 
 
182.236.164.11 - - [17/Sep/2021:18:20:54] "POST 
/cart/success.do?JSESSIONID=SD6SL8FF10ADFF53101 HTTP 1.1" 200 356 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-6" "Mozilla/5.0 (Macintosh; Intel 
Mac OS X 10_7_4) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 Safari/536.5" 220 
 

17 Sep 2021 
6:18:59.000 
PM 
 
198.35.1.75 - - [17/Sep/2021:18:18:59] "POST /cart/success.do?JSESSIONID=SD10SL2FF4ADFF53099 
HTTP 1.1" 200 2568 "http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-16" 
"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 
Safari/536.5" 386 
 



316 
 
Time 
 
Event 
 
17 Sep 2021 
6:16:23.000 
PM 
 
221.204.246.72 - - [17/Sep/2021:18:16:23] "POST 
/cart/success.do?JSESSIONID=SD9SL7FF3ADFF53096 HTTP 1.1" 200 1206 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-18" "Mozilla/5.0 (Macintosh; Intel 
Mac OS X 10_6_8) AppleWebKit/534.55.3 (KHTML, like Gecko) Version/5.1.5 Safari/534.55.3" 596 
 

17 Sep 2021 
6:13:34.000 
PM 
 
91.205.189.15 - - [17/Sep/2021:18:13:34] "POST 
/cart/success.do?JSESSIONID=SD10SL4FF1ADFF53066 HTTP 1.1" 200 3129 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-21" "Mozilla/5.0 (Macintosh; Intel 
Mac OS X 10_7_4) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 Safari/536.5" 591 
 
When you add the reverse command to the end of your search, the rows are reversed showing the oldest event first. 
 

Time 
 

Event 
 

17 Sep 2021 
6:13:34.000 
 
91.205.189.15 - - [17/Sep/2021:18:13:34] "POST 
/cart/success.do?JSESSIONID=SD10SL4FF1ADFF53066 HTTP 1.1" 200 3129�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dc335978-adc3-444e-9367-0fe7831cc1a6�h+)�}�(h}�(h/X?Time 
 

Event 
 

17 Sep 2021 
6:13:34.000 
 
91.205.189.15 - - [17/Sep/2021:18:13:34] "POST 
/cart/success.do?JSESSIONID=SD10SL4FF1ADFF53066 HTTP 1.1" 200 3129 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-21" "Mozilla/5.0 (Macintosh; Intel 
 


17 Sep 2021 
6:16:23.000 
PM 
 

221.204.246.72 - - [17/Sep/2021:18:16:23] "POST 
/cart/success.do?JSESSIONID=SD9SL7FF3ADFF53096 HTTP 1.1" 200 1206 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-18" "Mozilla/5.0 (Macintosh; Intel 
Mac OS X 10_6_8) AppleWebKit/534.55.3 (KHTML, like Gecko) Version/5.1.5 Safari/534.55.3" 596 
 

17 Sep 2021 
6:18:59.000 
PM 
 
198.35.1.75 - - [17/Sep/2021:18:18:59] "POST /cart/success.do?JSESSIONID=SD10SL2FF4ADFF53099 
HTTP 1.1" 200 2568 "http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-16" 
"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 
Safari/536.5" 386 
 

17 Sep 2021 
6:20:54.000 
PM 
 
182.236.164.11 - - [17/Sep/2021:18:20:54] "POST 
/cart/success.do?JSESSIONID=SD6SL8FF10ADFF53101 HTTP 1.1" 200 356 
"http://www.buttercupgames.com/cart.do?action=purchase&itemId=EST-6" "Mozilla/5.0 (Macintosh; Intel 
Mac OS X 10_7_4) AppleWebKit/536.5 (KHTML, like Gecko) Chrome/19.0.1084.46 Safari/536.5" 220 
 
2. Reverse aggregated results 
 

The following search uses the stats command to determine the number of different page requests, GET and POST, that 
occurred for each Web server. 
 

FROM main WHERE sourcetype=access_* | stats count(eval(method="GET")) AS GET, count(eval(method="POST")) AS 
POST BY host 
 

The results look something like this: 
 

host 
 

GET 
 

POST 
 
www1 
 
8431 
 
5197 
 
www2 
 
8097 
 
4815 
 
www3 
 
8338 
 
4654 
 
Add the reverse command to the end of the search. 
 



317 
 
FROM main WHERE sourcetype=access_* | stats count(eval(method="GET")) AS GET, count(eval(method="POST")) AS 
POST BY host | reverse 
 

The rows in the results are reversed. 
 

host 
 

GET 
 

POST 
 
www3 
 
8338 
 
4654 
 
www2 
 
8097 
 
4815 
 
www1 
 
8431 
 
5197 
 
See also 
 

reverse command�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4209ac8b-a061-43a5-895c-1c7f65eb57d2�h+)�}�(h}�(h/XpPOST BY host | reverse 
 

The rows in the results are reversed. 
 

host 
 

GET 
 

POST 
 
www3 
 
8338 
 
4654 
 
www2 
 
8097 
 
4815 
 
www1 
 
8431 
 
5197 
 
See also 
 

reverse command 
 

reverse command syntax details 
reverse command usage 
 











































318 
 
rex command 
 


rex command overview 
 
Use to either extract fields using regular expression named groups, or replace or substitute characters in a field using sed 
expressions. 
 

The rex command matches the value of the specified field against the unanchored regular expression and extracts the 
named groups into fields of the corresponding names. 
 

When mode=sed, the given sed expression used to replace or substitute characters is applied to the value of the chosen 
field. This sed-syntax is also used to mask sensitive data at index-time. 
 

If a field is not specified, the regular expression or sed expression is applied to the _raw field. Running the rex 
command against the _raw field might have a performance impact. 
 

Use the rex command for search-time field extraction or string replacement and character substitution. 
 

Syntax 
 

The required syntax is in bold. 
 

rex 
 

( <regex-expression> | mode=sed <sed-expression> ) 
 



See also 
 

rex command 
 

rex command usage 
 



rex command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

rex 
 

( <regex-expression> | mode=sed <sed-expression> ) 
 




319 
 
Required arguments 
 

You must specify either <regex-expression> or mode=sed <sed-expression> when you use the rex command. 
 

regex-expression 
	Syntax: <string> 
 

the information to match and extract from the specified field. Quotation marks are required. 
 
The Edge Processor solution supports Regular Expression 2 (RE2) syntax instead of PCRE syntax. In 
 

Edge Processor pipelines in Use Edge Processors. 
 

mode 
 


Syntax: mode=sed 
 


sed-expression 
 

Description: When mode=sed, specify whether to replace strings (s) or substitute characters (y) in the matching 
regular expression. No other sed commands are implemented. Quotation marks are required. Sed mode supports�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6ea77d3c-066b-4b60-a7c9-f16a3c9f3d2b�h+)�}�(h}�(h/X
regular expression. No other sed commands are implemented. Quotation marks are required. Sed mode supports 
the following flags: global (g) and Nth occurrence (N), where N is a number that is the character location in the 
string. 
 

Optional arguments 
 

field 
 


Syntax: field=<field> 
 

Default: _raw 
 

max_match 
 

Description: Controls the number of times the regular expression is matched. If greater than 1, the resulting 
fields are multivalued fields. You can use 0 for unlimited matches. 
 


offset_field 
 

Description: If provided, a field is created with the name specified by <string>. The value of this field has the 
endpoints of the match in terms of zero-offset characters into the matched field. For example, if the rex 
expression is (?<tenchars>.{10}), this matches the first ten characters of the field, and the offset_field 
contents is 0-9. 
 


See also 
 

rex command 
 

rex command usage 
 


320 
 
rex command usage 
 
SPL2 supports perl-compatible regular expressions (PCRE) for regular expressions. 
 

The Edge Processor solution, which uses the rex command, supports Regular Expression 2 (RE2) syntax instead of 
PCRE syntax. See rex command syntax details. 
 

Pipe characters 
 

A pipe character ( | ) is used in regular expressions to specify an OR condition. For example, A or B is expressed as A | B. 
 

Because pipe characters are used to separate commands in SPL2, you must enclose a regular expression that uses the 
pipe character in double quotation marks. For example: 
 

...| rex "expression | with pipe" 
 

This is interpreted by SPL2 as a search for the text "expression" OR "with pipe". 
 

Escaping characters with backslashes 
 

The backslash ( \ ) character is used to ignore, or escape, most special characters in regular expressions. 
 

Character classes and string expressions 
 

Regular expressions that include a character class, such as \d or \w, can be specified using one of two methods. The 
following table describes the methods and shows an example: 
 

Description 
 

Example�
h1h2h3}�h5Kuh�(h3h/�h}�ub�$b8b1df2c-da10-46d2-909c-c837293b1e0a�h+)�}�(h}�(h/XRegular expressions that include a character class, such as \d or \w, can be specified using one of two methods. The 
following table describes the methods and shows an example: 
 

Description 
 

Example 
 
Enclose the string expression in quotation marks and escape the backslash character in the 
character class. 
 
...rex field=clientip 
"(?<ipclass>\\d+)" 
 
Enclose the string expression in forward ( / ) slashes. You don't need to escape the backslash 
character in the character class. 
 
...rex field=clientip 
/(?<ipclass>\d+)/ 
 
Period characters 
 

The period ( . ) character is used in a regular expression to match any character, except a line break character. If you 
want to match a period character, you must escape the period character by specifying \. in your regular expression. 
 

Asterisk characters 
 

The asterisk ( * ) character is a reserved character in SPL2 and can't be escaped. SPL2 uses the asterisk as a wildcard 
character. 
 

Double backslash characters 
 

When a search includes a regular expression that contains a double backslash, for example to represent a file path like 
c:\\temp, the search interprets the first backslash as an escape character. The file path is interpreted as c:\temp. One of 
the backslashes is removed. 
 

You must escape both backslash characters in a file path by specifying 4 consecutive backslashes for the root portion of 
the file path. For example: c:\\\\temp. For a longer file path, such as c:\\temp\example, you would specify 
 

321 
 
c:\\\\temp\\example in your regular expression. 
 

Sed expression 
 

When using the rex command in sed mode, you have two options: replace (s) or character substitution (y). 
 

The syntax for using sed to replace (s) text in your data is: s/<regex>/<replacement>/<flags> 
 

• <regex> is a PCRE regular expression, which can include capturing groups. 
 

• <flags> can be either: g to replace all matches, or a number to replace a specified match. 
 

The syntax for using sed to substitute characters is: y/<string1>/<string2>/�h1h2h3}�h5Kuh�(h3h/�h}�ub�$51d32f51-8b18-4e68-996d-26051177871f�h+)�}�(h}�(h/X�• <flags> can be either: g to replace all matches, or a number to replace a specified match. 
 

The syntax for using sed to substitute characters is: y/<string1>/<string2>/ 
 

• This substitutes the characters that match <string1> with the characters in <string2>. 
 

Differences between SPL and SPL2 
 

Support for raw string literals 
 

New in SPL2 is support for raw string literals. 
 

Options must be specified before the expressions 
 

The field option must be specified before the <regex-expression> or <sed-expression> argument. 
 

Version 
 

Example 
 

Example 
 
SPL 
 
...rex "From: (?<from>.*) To: (?<to>.*)" field=myfield 
 
...rex "From: (?<from>.*) To: (?<to>.*)" max_match=10 offset_field=newofield 
 
SPL2 
 
...rex field=myfield "From: (?<from>.*) To: (?<to>.*)" 
 
...rex max_match=10 offset_field=newofield "From: (?<from>.*) To: (?<to>.*)" 
 
The max_match and offset_field options must be specified before the <regex-expression> argument. 
 

Version 
 

Example 
 
SPL 
 
...rex "From: (?<from>.*) To: (?<to>.*)" max_match=10 offset_field=newofield 
 
SPL2 
 
...rex max_match=10 offset_field=newofield "From: (?<from>.*) To: (?<to>.*)" 
 
See also 
 

rex command 
 

rex command syntax details 
rex command examples 
 


rex command examples 
 
The following are examples for using the SPL2 rex command. To learn more about the rex command, see How the rex 
command works. 
 



322 
 
1. Use a <sed-expression> to mask values 
 

Use a <sed-expression> to match the regex to a series of numbers and replace the numbers with an anonymized string to 
preserve privacy. In this example the first 3 sets of numbers for a credit card are masked. The \d must be escaped in the 
expression using a back slash ( \ ) character. 
 

... | rex field=ccnumber mode=sed "s/(\\d{4}-){3}/XXXX-XXXX-XXXX-/g" 
 

2. Regular expressions with character classes 
 

In this example, the clientip field contains IP addresses. You want to extract the IP class from the IP address. However,�h1h2h3}�h5Kuh�(h3h/�h}�ub�$808ebe00-b57a-420b-8026-8cad1c237154�h+)�}�(h}�(h/X�2. Regular expressions with character classes 
 

In this example, the clientip field contains IP addresses. You want to extract the IP class from the IP address. However, 
the expression uses the character class \d. You can specify the expression in one of two ways. 
 

You can escape the backslash character by adding another backslash, as shown in this example: 
 

... | rex field=clientip "(?<ipclass>\\d+)" 
 

You can use a forward slash ( / ), instead of quotation marks, to enclose the expression that contains a character class. 
Here's an example: 
 

... | rex field=clientip /(?<ipclass>\d+)/ 
 

Either method returns a field called ipclass that contains the class portion of the IP address. 
 

See also 
 

rex command 
 

rex command syntax details 
rex command usage 
 



























323 
 
search command 
 


search command overview 
 
Use the search command to retrieve events from one or more index datasets, or to filter search results that are already in 
memory. 
 

You can retrieve events from your datasets using keywords, quoted phrases, wildcards, and field-value expressions. 
When the search command is not the first command in the pipeline, it is used to filter the results of the previous 
command. 
 

Syntax 
 

The required syntax is in bold. 
 

search <search-expression> 
 

How the search command works 
 

You specify a search expression, such as a keyword or a field-value pair, when you use the search> command. 
 

Keyword searches are searches for literal values, terms or phrases, that appear in your events. Use the search command 
to perform keyword searches against events in your indexes, similar to searching the internet using a web browser. For 
example, you can search for a literal value such as buttercupgames or itemId. 
 

Keyword searches are not case sensitive. The following search returns any event that contains the term itemId, including 
all variations of the capitalization of that term, such as itemID, ITEMID, and itemid. 
 

| search itemId�h1h2h3}�h5Kuh�(h3h/�h}�ub�$730d2cdb-5f98-4b94-a0f4-810aa30e9811�h+)�}�(h}�(h/X�all variations of the capitalization of that term, such as itemID, ITEMID, and itemid. 
 

| search itemId 
 

To search for a phrase, enclose the phrase in double quotations. For example, this search returns only those events 
where the term Windows is immediately followed by a space and the number 10: 
 

| search "Windows 10" 
 

You also use double quotations for terms that contain punctuation, for example: 
 

| search "SC-MG-G10" 
 

Search using field-value pairs 
 

When you are looking for a specific value in a field, identify the field in your search using a field-value pair. 
 

The field name is case sensitive, the field value is not case sensitive. 
 

For example, to search the categoryId field for the value sports, use this search: 
 

| search categoryId=sports 
 


324 
 
Searching for multiple keywords 
 

When you specify multiple terms to search for, there is an implied AND operator between each term. In the following 
example, the search looks only for events where the term www2 exists and the categoryId field contains sports: 
 

| search www2 categoryId=sports 
 

This is the same as if you explicitly included the AND operator in your search, such as: 
 

| search www2 AND categoryId=sports 
 

Search expressions 
 

The search command, along with the from command, is one of the most powerful commands in SPL2. 
 

There are a wide variety of search expressions that you can specify with the search command. To learn more about how 
you can use the search command, see search command syntax details and search command usage for examples of 
common search expressions. 
 

For a complete description of the types of expressions that you can use in SPL2, see Types of expressions in the SPL2 
Search Manual. 
 

See also 
 

search command 
 

search command usage 
search command examples 
 


search command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

search <search-expression> 
 

Required arguments 
 

search-expression�h1h2h3}�h5Kuh�(h3h/�h}�ub�$7a9197c5-6efc-41a0-a23f-af97305c93f6�h+)�}�(h}�(h/X�search command usage 
search command examples 
 


search command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

search <search-expression> 
 

Required arguments 
 

search-expression 
 

Description: The <search-expression> can be a word or phrase, a field-value comparison, a list of values, or a 
group of search expressions. You can use logical expressions by using IN, AND, OR, or NOT comparisons in 
your <search-expression>. 
 

You can use Boolean operators to specify more than one <search-expression>. The supported operators are AND, OR, 
and NOT. Examples of how you can use these operators are: 
 

• <search-expression> AND <search-expression> 
• <search-expression> OR <search-expression> 
 

325 
 
• NOT <search-expression> 
 

Literal expression 
 

literal-expression 
 

Description: You can search for string values, number values, or phrases in your data. For example you can 
specify a word such as error, a number such as 404, or a phrase such as "time limit". If the string, number, or 
phrase contains any characters like periods ( . ) or spaces, you must enclose the word or phrase in double 
quotation marks. 
 

Comparison expression 
 

comparison-expression 
 

Description: You can specify a field name and a comparison operator, such as equal to ( = ) or greater than ( > ), 
followed by the literal number or string value of a field. You can also specify field name and the IN keyword 
followed by a list of values enclosed in parentheses. For example, you can specify categoryID="accessories" or 
 


You can use comparison operators when searching for field/value pairs. Comparison expressions with the equal ( 
= ) or not equal ( != ) operator compare string values. For example, "1" does not match "1.0". Comparisons with 
greater than or less than operators, including <= and >= numerically compare two numbers and lexicographically 
compare other values. Valid comparison operators are: =, !=, <, <=, >, and >=. See search command usage.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9e3010f7-73d0-4c8f-b286-2a53d6856443�h+)�}�(h}�(h/Xcompare other values. Valid comparison operators are: =, !=, <, <=, >, and >=. See search command usage. 
 

You can use the CASE() or TERM() directives to perform an exact match for a term. 
 

field 
 


Syntax: <string> 
 


value 
 



Syntax: <literal-value> 
 


value-list 
 

Description: Used with the IN operator to specify two or more values. For example use error IN (400, 402, 
404, 406) instead of error=400 OR error=402 OR error=404 OR error=406. 
 

CASE 
 


Syntax: CASE(<term>) 
 

such as Error, error, and ERROR. Use the CASE directive to perform case-sensitive matches for terms and field 
values. CASE(error) will return only that specific case of the term. 
 

TERM 
 


Syntax: TERM(<term>) 
 

segmenters between terms. Use the TERM directive to ignore the minor segmenters and match whatever is 
inside the parentheses as a single term. The <term> must have been bound by major segmenters, such as 
 


326 
 
segmenter. If you search for the IP address using | search 127.0.0.1 the search is converted into | search 127 
AND 0 AND 1 which returns events that contain those numbers anywhere in the event. If you search using | 
search TERM(127.0.0.1) the search treats the IP address as a single term, instead of individual numbers. 
 

Time expression 
 

time-expression 
 

Description: Describes the format of the start and end time of the search. Use the <timeformat> to set the time 
format. The <timeformat> is optional, and if not specified the default format is %m/%d/%Y:%H:%M:%S. Use the 
<time-modifier> to specify start and end times using absolute or relative times. 
 

• An absolute time range uses specific dates and times, for example, from 12 A.M. July 1, 2019 to 12 A.M. July 13, 
	2019. 
 

60 minutes ago. If the current time is 3 P.M., the search returns events from the last 60 minutes, or 2 P.M. to 3 
P.M. today. 
 


Use the earliest and latest modifiers to specify custom and relative time ranges. You can specify an exact time such as 
earliest="10/5/2016:20:00:00", or a relative time such as earliest=-h or latest=@w6.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5399ae93-8bad-40b9-804a-540ab2872cb0�h+)�}�(h}�(h/Xearliest="10/5/2016:20:00:00", or a relative time such as earliest=-h or latest=@w6. 
 

Time modifier 
 

Description 
 

Examples 
 
Events must be later or equal to this time. 
 
starttime=<string> 
 
starttime="%d-%b-%Y %H:%M:%S" 
 
Times must match the <timeformat>. 
 
All events must be earlier or equal to this time. 
 
endtime=<string> 
 
endtime="%d-%b-%Y %H:%M:%S 
 
Times must match the <timeformat>. 
 
Events must be later or equal to this time. 
 
earliest=4/27/2019:00:00:00 
 
earliest=<time_modifier> 
 

You can specify an absolute or relative time, including a 
snap-to time. 
 

earliest=-h@h 
earliest=-mon@mon 
 

All events must be earlier or equal to this time. 
 
latest=7/16/2019:00:00:00 
 
latest=<time_modifier> 
 

You can specify an absolute or relative time, including a 
snap-to time. 
 
latest=now() 
latest=+7d@w6 
 
Index expression 
 

index-expression 
 

Description: Use to describe the events you want to retrieve from the index using literal strings and search 
modifiers. 
 

string 
 


Syntax: "<string>" 
 

anything that is not a search modifier, the _raw field is searched for the matching events or results. 
 

327 
 
search-modifier 
 

<savedsplunk-specifier> | <eventtype-specifier> | <eventtypetag-specifier> | <splunk_server-specifier> 
Description: Search for events from specified fields or field tags. For example, search for one or a combination of 
hosts, sources, source types, saved searches, and event types. Also, search for the field tag, with the format: 
tag::<field>=<string>. 
 

sourcetype-specifier 
 

Description: Search for events from the specified sourcetype field. 
 

host-specifier 
 

Description: Search for events from the specified host field. 
 

hosttag-specifier 
 

Description: Search for events that have hosts that are tagged by the string. 
 

eventtype-specifier 
 

Description: Search for events that match the specified event type. 
 

eventtypetag-specifier 
 

Description: Search for events that would match all eventtypes tagged by the string. 
 

savedsplunk-specifier�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ba2959d0-fcb5-4bfb-b8a4-e1a231d70de7�h+)�}�(h}�(h/X�eventtypetag-specifier 
 

Description: Search for events that would match all eventtypes tagged by the string. 
 

savedsplunk-specifier 
 

Description: Search for events that would be found by the specified saved search. 
 

source-specifier 
 

Description: Search for events from the specified source field. 
 

splunk_server-specifier 
 

Description: Search for events from a specific server. Use "local" to refer to the search head. 
 

See also 
 

search command 
 

search command usage 
search command examples 
 


search command usage 
 
The search command is an generating command when it is the first command in the search. The command generates 
events from the dataset specified in the search. However it is also possible to pipe incoming search results into the search 
 

328 
 
command. The <search-expression> is applied to the data in memory. For example, the following search puts data from 
the main dataset into memory and then filters out events that do not contain the term 500. 
 

from main | search 500 
 

Searching for terms in your data 
 

The search command can look for events that contain simple text terms, or character sequences, like this: 
 

| search "UserNotFound" 
 

The _raw field is searched in all of the indexes that are visible to the current user in the current module for events that 
contain the text UserNotFound. 
 

Searching for phrases 
 

With the search command, while quotation marks are not required to search for a term, if term that you are looking for 
contains spaces then quotation marks are required. If you omit the quotation marks, there is no guarantee the 'words' in 
 


Search 
 


Description 
 
This is the same as search User AND Not AND Found. 
 
| search User Not Found 
 

There is an implied AND condition between each word. Each word can appear anywhere in an 
event. 
 
| search "User Not 
Found" 
 

This search finds the events that contain the phrase User Not Found. 
 
Searching for field values�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6b95c265-f026-4bbf-93fb-af358d0ac1e3�h+)�}�(h}�(h/Xevent. 
 
| search "User Not 
Found" 
 

This search finds the events that contain the phrase User Not Found. 
 
Searching for field values 
 

The search command also allows for more precise searches, such as looking for a value in a particular field. For example 
this search: 
 

| search host=localhost 
 

This search finds events that contain the string localhost in the host field. The field must always be on the left side of the 
comparison operator. Because of this strict ordering, no quoting is required to distinguish between field references and 
string literals. 
 

To find all events in a particular field, use the wildcard character ( * ). For example: 
 

| search status=* 
 

This example returns only events that contain a status field. You can also use the other comparison operators, such as: 
!=, <, <=, >, and >=. 
 

Searching with wildcard characters 
 

You can look for terms that contain a similar sequence of characters by using a wildcard character ( * ). Wildcard 
characters can be used both in text searches and in searching for field values. For example: 
 



329 
 
| search ccnumber="4232*1232" H*l*o 
 

This search returns events that meet both of the conditions specified. Events must have the ccnumber field with values that 
start with 4232 and end with 1232. The events must also have a word that starts with H followed later by l and ends with 
 


For information about best practices for using wildcards and when to avoid using wildcards, see Wildcards in the SPL2 
Search Manual. 
 

Indexed fields in search 
 

When searching for a <field>=<value> or <field>="<value>", events that contain the value are searched for. For every 
matching event, a field extraction is run. Finally an in memory filter is applied for <field>=<value> to remove false 
positives. 
 

However, if the field is known to be an indexed field you can take advantage of how index fields are stored in the index by 
looking for <field>::<value> instead of simply <value>. This is often much faster as it avoids reading and enriching events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$99021af5-ebad-4640-bbdf-67110106fb76�h+)�}�(h}�(h/X�looking for <field>::<value> instead of simply <value>. This is often much faster as it avoids reading and enriching events 
 


Searching with boolean operators 
 

The search command also allows for the construction of conjunctions and disjunctions which are both just more complex 
predicates. 
 

AND Operator 
 

Conjunctions can be explicitly specified using the AND operator, or can are implicitly inferred when two or more conditions 
are present, for example these two searches are identical: 
 

| search host=localhost UserNotFound 
 

| search host=localhost AND UserNotFound 
 

Both examples match events that contain both UserNotFound in the _raw field and localhost in the host field. 
 

OR Operator 
 

Disjunctions must be explicitly specified using the OR operator: 
 

| search host=localhost OR UserNotFound 
 

Grouping Operator 
 

Arbitrarily complicated combinations of conjunctions and disjunctions, or compound predicates, can be constructed by 
using the grouping operator, the parenthesis ( ). For example: 
 

| search host=localhost ( UserNotFound OR sourcetype=webaccess ) 
 

Matches events that have host equal to localhost and either contain UserNotFound or have sourcetype equal to 
webaccess. 
 




330 
 
NOT Operator 
 

It is possible to search for events that have a field that is not equal to a particular value using the != operator, like this: 
 

| search src!="127.0.0.1" 
 

However this only returns events that actually have a src field. To also return events without a src field use the NOT 
operator instead: 
 

| search NOT src="127.0.0.1" 
 

This will return all events where either the src field is not found or where src is not "127.0.0.1". You can also use the NOT 
operator with simple keyword searches like this: 
 

search NOT error 
 

This search return all events not containing "error". 
 

Implicit Grouping 
 

The search command supports implicit tiebreaking between AND and OR operators. To illustrate, these are both valid: 
 

| search A AND B OR C 
 

| search A B OR C�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b588e641-c9a6-46fd-8379-88e681ebfe13�h+)�}�(h}�(h/X!Implicit Grouping 
 

The search command supports implicit tiebreaking between AND and OR operators. To illustrate, these are both valid: 
 

| search A AND B OR C 
 

| search A B OR C 
 

And are both processed as if written like this: 
 

| search A AND (B OR C) 
 


The rule is that OR bind its operands with higher precedence than AND, but this can be overridden using the explicit 
grouping operator. These searches product the same results: 
 

| search (A AND B) OR C 
 

| search (A B) OR C 
 

IN Operator 
 

The search command supports the IN operator: 
 

search status IN (401, 403) 
 

Which finds events where the value of the status field is either 401 or 403. 
 

Running case-sensitive searches 
 

By default string searches are case insensitive. Using the CASE directive, it is possible to do a case-sensitive match. For 
example: 
 

search host=CASE(LOCALHOST) 
 


331 
 
This search only matches events that contain localhost in uppercase in the host field. 
 

TERM directive 
 

The TERM directive is useful for more efficiently finding terms, when you are searching for a term that: 
 

• Contains minor breakers 
 

• Does not contain major breakers 
 

To illustrate, imagine looking for 127.0.0.1. This term contains minor breakers, the period character ( . ). If we know that 
127.0.0.1 is bound on either side by major breakers like a comma ( , ) or space (" "), it is more efficient to search using 
TERM(127.0.0.1) than simply 127.0.0.1. For example, suppose the _raw field looks like this: 
 

_time=1549931073,127.0.0.1,test,foo,bar 
 

Because 127.0.0.1 is bound on either side by a major breaker, a comma ( , ), using TERM(127.0.0.1) will match. However 
if the _raw field looked like this: 
 

_time=1549931073,host=127.0.0.1,test,foo,bar 
 

This event would not be found because the full term after splitting on major breakers is host=127.0.0.1 not 127.0.0.1. 
 

Major differences between search and other commands 
 

There are major differences between predicates in the search command and predicates in the where and from commands�h1h2h3}�h5Kuh�(h3h/�h}�ub�$552fc300-efca-4912-bf1d-a168a3b5fe28�h+)�}�(h}�(h/X�Major differences between search and other commands 
 

There are major differences between predicates in the search command and predicates in the where and from commands 
and elsewhere in the language, including: 
 

Search command 
 

Where command 
 
A subset of the where command 
functionality 
 

Full functionality 
 

Has a rudimentary expression language 
 
A powerful expression language with full access to an exhaustive list of scalar functions, arithmetic 
operators, parameters, navigation properties and literal constructs like array literals, verbatim 
strings, regex literals. 
 
Comparison operators are always 
interpreted as <field><operator><value> 
 
The left operands and right operands are interpreted based on syntax rules for each kind of 
operand. For example it is possible to perform <field><operator><field>. 
 
The AND operator is implied 
 
The AND operator must be explicitly specified. 
 
Grouping precedence rules are implied. 
 
The grouping operator () must be explicitly used. 
 
Can search for a specific sequence of 
characters anywhere in an event. 
 
Must be more explicit to find characters. For example use ...where _raw=*sequence* or 
where searchmatch(<search-predicate>) 
 
Indexes in scope 
 

In SPL2 when using the search command, indexes are either those explicitly mentioned in the search predicate, or a 
default index. For example: 
 

Search 
 

Description 
 
search index=main 
ERROR 
 
This search is explicitly scoped to the main index. 
 


332 
 
Search 
 
Description 
 

This search picks up the indexes that are implicitly in scope. 
 
search ERROR 
 

Which means all of the indexes visible to the current user in the module that the search is run 
in. 
 
Using time modifiers 
 

Specify absolute time ranges 
 

For exact time ranges, the syntax for the time modifiers is %m/%d/%Y:%H:%M:%S. For example, the following search specifies 
a time range from 12 A.M. July 13, 2021 to 12 A.M. July 16, 2021. 
 

earliest=7/13/2021:00:00:00 latest=7/16/2021:00:00:00 
 

Time modifiers�h1h2h3}�h5Kuh�(h3h/�h}�ub�$dee2afe9-ce73-43e2-8d45-d1d0cc44896c�h+)�}�(h}�(h/X/a time range from 12 A.M. July 13, 2021 to 12 A.M. July 16, 2021. 
 

earliest=7/13/2021:00:00:00 latest=7/16/2021:00:00:00 
 

Time modifiers 
 

If you specify only the earliest time , the latest time is set to the current time Now by default. If you specify the latest 
time, you must also specify the earliest time. 
 

For more information on using time modifiers see Time modifiers in the SPL2 Search Manual. 
 

Differences between SPL and SPL2 
 

Different requirements for fields that must be quoted 
 

If a field name must be quoted, SPL2 uses single quotation marks. For example, if a field name contains a space, the field 
name must be single quoted. SPL uses double quotation marks. 
 

Version 
 

Example 
 
SPL 
 
search "my field"=10 
 
SPL2 
 
search 'my field'=10 
 
Different requirements for quoting values 
 

The search command is designed to be backward compatible with SPL. String values do not need to be double quoted in 
SPL2 when you use the search command. When using any other SPL2 command, string values must be double quoted. 
 

Version 
 

Example 
 
SPL 
 
search host!="localhost" 
 
SPL2 
 
search host!=localhost 
 
See also 
 

search command 
 

search command syntax details 
search command examples 
 



333 
 
search command examples 
 
The following are examples for using the SPL2 search command. To learn more about the search command, see How the 
search command works. 
 

1. Field-value pair matching 
 

This example shows field-value pair matching for specific values of source IP (src) and destination IP (dst). 
 

search src="10.9.165.*" OR dst="10.9.165.8" 
 

2. Using boolean and comparison operators 
 

This example shows field-value pair matching with boolean and comparison operators. This example searches for events 
with code values of either 10, 29, or 43 and any host that is not "localhost", and an xqp value that is greater than 5. 
 

search (code=10 OR code=29 OR code=43) host!="localhost" xqp>5 
 


An alternative is to use the IN operator, because you are specifying multiple field-value pairs on the same field. The�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1cf08366-7a6b-4a3c-92a8-bf2dffc1045c�h+)�}�(h}�(h/X2search (code=10 OR code=29 OR code=43) host!="localhost" xqp>5 
 


An alternative is to use the IN operator, because you are specifying multiple field-value pairs on the same field. The 
revised search is: 
 

search code IN(10, 29, 43) host!="localhost" xqp>5 
 

3. Using wildcards 
 

This example shows field-value pair matching with wildcards. This example searches for events from all of the web 
servers that have an HTTP client and server error status. 
 

search host=webserver* (status=4* OR status=5*) 
 


An alternative is to use the IN operator, because you are specifying two field-value pairs on the same field. The revised 
search is: 
 

search host=webserver* status IN(4*, 5*) 
 

4. Using the IN operator 
 

This example shows how to use the IN operator to specify a list of field-value pair matchings. In the events from an 
access.log file, search the action field for the values addtocart or purchase. 
 

search sourcetype=access_combined_wcookie action IN (addtocart, purchase) 
 

5. Using the NOT or != comparisons 
 

Searching with the boolean "NOT" comparison operator is not the same as using the "!=" comparison. 
 

The following search returns everything except fieldA="value2", including all other fields. 
 

search NOT fieldA="value2" 
 


334 
 
The following search returns events where fieldA exists and does not have the value "value2". 
 

search fieldA!="value2" 
 

If you use a wildcard for the value, NOT fieldA=* returns events where fieldA is null or undefined, and fieldA!=* never 
returns any events. 
 

See also 
 

search command 
 

search command syntax details 
search command usage 
 
















































335 
 
sort command 
 


sort command overview 
 
The sort command sorts all of the results by the specified fields. Results missing a given field are treated as having the 
smallest possible value of that field if descending or largest possible value of that field if ascending. 
 

Syntax 
 

The required syntax is in bold. 
 

sort 
[<count>] 
[<sort-order>] 
 

<field> 
 

How the sort command works�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3ae83c94-1271-4227-888d-c7ebea667282�h+)�}�(h}�(h/X	Syntax 
 

The required syntax is in bold. 
 

sort 
[<count>] 
[<sort-order>] 
 

<field> 
 

How the sort command works 
 

The sort command is most often used at the end of your search, either as the last command or the next to the last 
command. 
 

Here is an example of some data returned by a search: 
 

supplier_id 
 

supplier_name 
 

city 
 

state/province 
 

country 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
1009 
 
Mile High Games 
 
Denver 
 
Colorado 
 
United States 
 
7024 
 
Happy Fun Games 
 
Kyoto 
 
Kyoto 
 
Japan 
 
1237 
 
Area 51 Games 
 
Roswell 
 
New Mexico 
 
United States 
 
4111 
 
Isthmus Pastimes 
 
Panama City 
 
Panama 
 
Panama 
 
5017 
 
Der Kriegsspiel 
 
Cologne 
 
North Rhine-Westphalia 
 
Germany 
 
7045 
 
Kiwi Game Warehouse 
 
Auckland 
 
Auckland 
 
New Zealand 
 
1080 
 
EuroToys 
 
Dublin 
 
Ireland 
 
You want to sort the data type supplier ID: 
 

... | sort supplier_id 
 

The results look like this: 
 

supplier_id 
 

supplier_name 
 

city 
 

state/province 
 

country 
 
1009 
 
Mile High Games 
 
Denver 
 
Colorado 
 
United States 
 
1080 
 
EuroToys 
 
Dublin 
 
Ireland 
 
1237 
 
Area 51 Games 
 
Roswell 
 
New Mexico 
 
United States 
 

336 
 
supplier_id 
 
supplier_name 
 
city 
 
state/province 
 
country 
 

4111 
 

Isthmus Pastimes 
 

Panama City 
 

Panama 
 

Panama 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
5017 
 
Der Kriegsspiel 
 
Cologne 
 
North Rhine-Westphalia 
 
Germany 
 
7024 
 
Happy Fun Games 
 
Kyoto 
 
Kyoto 
 
Japan 
 
7045 
 
Kiwi Game Warehouse 
 
Auckland 
 
Auckland 
 
New Zealand 
 
To sort by Supplier Name and then Supplier ID, specify a comma between the field names when you add the sort 
command to your search: 
 

... | sort supplier_name, supplier_id 
 


The results look like this: 
 

supplier_id 
 

supplier_name 
 

city 
 

state/province 
 

country 
 
1237 
 
Area 51 Games 
 
Roswell 
 
New Mexico 
 
United States 
 
5017 
 
Der Kriegsspiel 
 
Cologne 
 
North Rhine-Westphalia 
 
Germany 
 
1080 
 
EuroToys 
 
Dublin 
 
Ireland 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
7024 
 
Happy Fun Games 
 
Kyoto 
 
Kyoto 
 
Japan 
 
4111 
 
Isthmus Pastimes 
 
Panama City 
 
Panama 
 
Panama 
 
7045�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ce09af21-927e-4a3b-9875-d1ed65b5c820�h+)�}�(h}�(h/X�1080 
 
EuroToys 
 
Dublin 
 
Ireland 
 
5007 
 
EuroToys 
 
Prague 
 
Central Bohemia 
 
Czech Republic 
 
7024 
 
Happy Fun Games 
 
Kyoto 
 
Kyoto 
 
Japan 
 
4111 
 
Isthmus Pastimes 
 
Panama City 
 
Panama 
 
Panama 
 
7045 
 
Kiwi Game Warehouse 
 
Auckland 
 
Auckland 
 
New Zealand 
 
1009 
 
Mile High Games 
 
Denver 
 
Colorado 
 
United States 
 
Notice that both of the EuroToys suppliers are listed together and that those are in ascending order. The default sort order 
is ascending order. To specify descending order, add a minus ( - ) sign before the field name. 
 

To learn how alphanumeric strings and punctuation are sorted, see sort command usage. 
 

See also 
 

sort command 
 

sort command usage 
sort command examples 
 

Related information in the SPL2 Search Manual 
	Commands that sort results 
	Lexicographical order 
 






337 
 
sort command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

sort 
[<count>] 
[<sort-order>] 
 

<field> 
 

Required arguments 
 

<field> 
 


Syntax: <field> [,<field>]... 
 

commas. 
 

Optional arguments 
 

count 
 


Syntax: <integer> 
 

count before specifying the fields. If no count is specified, the default limit of 10000 is used. If 0 is specified, all of 
the results are returned. 
 

Using sort 0 might have a negative impact performance, depending on how many results are returned. Try to 
filter the results to minimize the number of results before using the sort command. 
 

<sort-order> 
 

Description: Use a minus sign ( - ) for descending order and a plus sign ( + ) for ascending order. 
Default: Ascending ( + ) 
 

<sort-option> 
 

Description: Options you can specify with <field>. The default sort option is auto. See sort command examples. 
 

sort option 
 

Description 
 
auto 
 
Determine the type of field value automatically. This is the default sort option. 
 
ip 
 
Interpret the values of the field as IP addresses. 
 
num 
 
Interpret the values of the field as numbers. 
 
str 
 
Interpret the values of the field as strings and order the values alphabetically. 
 






338 
 
See also 
 

sort command 
 

sort command usage 
sort command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b7450650-02d4-4603-ae97-b12a430bfbaa�h+)�}�(h}�(h/X"str 
 
Interpret the values of the field as strings and order the values alphabetically. 
 






338 
 
See also 
 

sort command 
 

sort command usage 
sort command examples 
 


sort command usage 
 
By default, the sort command tries to automatically determine what it is sorting. If the field contains numeric values, the 
collating sequence is numeric. If the field contains IP address values, the collating sequence is for IP addresses. 
Otherwise, the collating sequence is in lexicographical order. 
 

How data is interpreted and sorted 
 

• Punctuation strings are sorted lexicographically. 
 

descending. 
 

	the string is sorted numerically based on that number alone. Otherwise, strings are sorted lexicographically. 
• Strings that are a combination of alphanumeric and punctuation characters are sorted the same way as 
 


The sort order is determined between each pair of values that are compared at any one time. This means that for some 
pairs of values, the order might be lexicographical, while for other pairs the order might be numerical. 
 

Results in descending order 
 

Description 
 
10.1 
 
This set of values are sorted numerically because the values are all numeric. 
 
9.1 
 
9.1.a 
 
This set of values are sorted lexicographically because the values are alphanumeric strings. 
 
10.1.a 
 
Lexicographical order 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or 
	after letters. 
 

You can specify a custom sort order that overrides the lexicographical order. See the blog Order Up! Custom Sort Orders. 
 





339 
 
Differences between SPL and SPL2 
 

Some field names require single quotation marks�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0c1accff-e748-4f9c-beb8-cade94806cfa�h+)�}�(h}�(h/XY339 
 
Differences between SPL and SPL2 
 

Some field names require single quotation marks 
 

Field names that contain anything other than [a-z][A-Z][0-9] or "_", need single quotation marks. In this example the field 
name is host-123 and because it contains a dash, it must be enclosed in single quotation marks. 
 

Version 
 

Example 
 
SPL 
 
...sort host-123 
 
SPL2 
 
...sort 'host-123' 
 


See also 
 

sort command 
 

sort command syntax details 
sort command examples 
 


sort command examples 
 
The following are examples for using the SPL2 sort command. To learn more about the sort command, see How the sort 
command works. 
 

1. Specify different sort orders for each field 
 

This example sorts the results first by the lastname field in ascending order and then by the firstname field in descending 
order. Because ascending is the default sort order, you don't need to specify it unless you want to be explicit. 
 

... | sort lastname, -firstname 
 

2. Specify the number of sorted results to return 
 

This example sorts the results and returns a maximum of 100 of the sorted results. The results are sorted first by the size 
field in descending order. If there are duplicate values in the size field, the results are sorted by the source field in 
 


... | sort 100 -size, +source 
 

3. Use the sort options to specify field types 
 

Sort the results by the ipaddress field in ascending order and then sort by the url field in descending order. 
 

... | sort num(ipaddress), -str(url) 
 






340 
 
See also 
 

sort command 
 

sort command syntax details 
sort command usage 
 
























































341 
 
spl1 command 
 


spl1 command overview 
 
Use the spl1 command to embed all or part of an SPL search into an SPL2 search. There are some limitations using this 
command. See spl1 command usage. 
 

Syntax 
 

The spl1 command supports two syntaxes. 
 

Backtick character syntax 
 


`<SPL-search>` 
 

Explicit spl1 command syntax 
 


spl1 "<SPL-search>" 
 

How the spl1 command works 
 

Use the spl1 command when a commands is not supported in SPL2.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0799be3c-4e11-4310-af28-b64d5207de15�h+)�}�(h}�(h/X�Backtick character syntax 
 


`<SPL-search>` 
 

Explicit spl1 command syntax 
 


spl1 "<SPL-search>" 
 

How the spl1 command works 
 

Use the spl1 command when a commands is not supported in SPL2. 
 

For example, while the makeresults command is not supported in SPL2 you can use the spl1 command to run a search 
with the makeresults command: 
 

Version 
 

Example 
 

SPL search 
 

makeresults count=3 
 


This search uses the spl1 command backtick ( ` ) character syntax. 
 


This search uses the explicit spl1 command syntax. 
 
In SPL, the default index is main and when you run a search, the search is run against the main index. However, there is 
no default index in SPL2. To run a search against a specific index, you must specify that index. 
 

Here's an example: 
 

Version 
 

Example 
 


This search looks for the term error and the field-value pair http_code=404 in the default index, main. 
 


342 
 
Version 
 
Example 
 

SPL2 
search 
 

$error1 = from main | `search error OR http_code=404` 
There is no default dataset with SPL2. The easiest way to identify the dataset is with the SPL2 from 
command. This search uses the spl1 command backtick ( ` ) character syntax. 
 

SPL2 
search 
 

$error2 = from main | spl1 "search error OR http_code=404" 
This is the same search using the explicit spl1 command syntax.|- 
 

SPL2 
search 
 

$error3 = `search index=main error OR http_code=404` 
Alternatively, you can add the index to the search command. 
 
See also 
 

spl1 command 
 

spl1 command usage 
spl1 command examples 
 

Related information 
 



spl1 command syntax details 
 
For overview information about the spl1 command, see spl1 command overview. 
For examples using the spl1 command, see spl1 command examples. 
 

Syntax 
 

The spl1 command supports two syntaxes. 
 

Backtick character syntax 
 


`<SPL-search>` 
 

Explicit spl1 command syntax 
 


spl1 "<SPL-search>" 
 

See also 
 

spl1 command 
 

spl1 command usage 
spl1 command examples 
 




343 
 
spl1 command usage�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d8645e14-5525-4708-ba74-e132a36271dd�h+)�}�(h}�(h/X�Backtick character syntax 
 


`<SPL-search>` 
 

Explicit spl1 command syntax 
 


spl1 "<SPL-search>" 
 

See also 
 

spl1 command 
 

spl1 command usage 
spl1 command examples 
 




343 
 
spl1 command usage 
 
You use the spl1 command to include SPL searches, or parts of searches, in your SPL2 searches. The spl1 command 
enables you to use SPL commands that are not directly supported with SPL2. 
 

SPL commands supported with the spl1 command 
 

In SPL2 searches, you can use the following SPL commands with the spl1 command: 
 

Commands 
 
• actions 
• addinfo 
• append 
• apply 
• bin 
• convert 
• dedup 
 
• fields 
• fillnull 
• fit 


• iplocation 
• join 
 
• metadata 
• mstats 
• mvexpand 
• multireport 
• noop 
• regex 
 
• savedsearch 
• selfjoin 
• sistats 


	streamstats 
• table 
 

• timeliner 
• timewrap 
• tstats 
• tojson 
• top 
• untable 
• union 
 
• eventsingest 
• eventstats 
 
• makeresults 
• mcatalog 
 
• reverse 
• rex 
 
• xyseries 
 
Searches that use the implied search command 
 

For some SPL searches, you must add the search command when you use the spl1 command. 
 

In the SPL, the search command is implied at the beginning of some searches, such as searches that start with a keyword 
or a field-value pair. Unless your SPL search begins with a generating command like inputlookup, makeresults, mstats, 
 


When to include the index in your search 
 

In an SPL2 search, there is no default index. You must specify the index that you want to search either before or within 
the spl1 command portion of the search. See spl1 command examples. 
 

Searches that contain quotation marks 
 

When your SPL search contains quotation marks, it is easier to use the spl1 command backtick ( ` ) character syntax. 
When you use the explicit spl1 command syntax, you must escape the quotation marks. See spl1 command examples. 
 

Searches with macros or subsearches 
 

You can't use the spl1 command with SPL searches that contain macros or subsearches. 
 

See also 
 

spl1 command 
 

spl1 command syntax details 
spl1 command examples 
 


344 
 
spl1 command examples�h1h2h3}�h5Kuh�(h3h/�h}�ub�$cf43feb8-9115-4945-b6aa-ec036a142d64�h+)�}�(h}�(h/XYou can't use the spl1 command with SPL searches that contain macros or subsearches. 
 

See also 
 

spl1 command 
 

spl1 command syntax details 
spl1 command examples 
 


344 
 
spl1 command examples 
 
The following are examples for using the SPL2 spl1 command. To learn more about the spl1 command, see How the 
spl1 command works. 
 



Searches that use the implied search command 
 

In the SPL, the search command is implied at the beginning of some searches, such as searches that start with a keyword 
or a field-value pair. In SPL2 the search command must be explicitly specified. 
 

Unless your SPL search begins with a generating command like inputlookup, makeresults, mstats, or tstats, you must 
include the search command when you use the spl1 command. 
 

Here's an example: 
 

Version 
 

Example 
 


This SPL search starts with the implied search command and is comprised of two field-value pairs. 
 

SPL2 
search 
 

$example1= | `search index=sample_data_index action=purchase` 
In this SPL2 search, the search command is explicitly added to the SPL search and the search uses the 
backtick ( ` ) character syntax. 
 

SPL2 
search 
 

$example2 = | spl1 "search index=main action=purchase" 
In this SPL2 search, the search command is explicitly added to the SPL search and the search uses the 
explicit spl1 command syntax. 
 
Using the spl1 command with only the unsupported portion of the SPL search 
 

For many SPL searches, you can convert most of the search to SPL2. For the portion of the SPL search that you can't 
convert you can use the spl1 command. 
 

The following example shows how to convert an SPL search into SPL2 and how to use the spl1 command for the addinfo 
command, which is not supported in SPL2. 
 

Version 
 

Example 
 

SPL search 
 

index=sample_data_index | stats sum(bytes) BY host | addinfo 
 


SPL2 search 
 

$example1 = from sample_data_index | stats sum(bytes) BY host | `addinfo`  
In this SPL2 search, the portion of the search not supported by SPL2 uses the backtick ( ` ) character 
syntax. 
 
SPL2 search�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1d20f1e7-ebb9-4fd3-81f2-d9d84d1e7f8a�h+)�}�(h}�(h/X�$example1 = from sample_data_index | stats sum(bytes) BY host | `addinfo`  
In this SPL2 search, the portion of the search not supported by SPL2 uses the backtick ( ` ) character 
syntax. 
 
SPL2 search 
 
$example2 = from sample_data_index | stats sum(bytes) BY host | spl1 "addinfo" 
 
In this SPL2 search, the portion of the search not supported by SPL2 uses the explicit spl1 command 
syntax. 
 

345 
 
Version 
 
Example 
 

When to include the index in your search 
 

In the SPL2 search, there is no default index. You must specify the index either before or within the spl1 command 
portion of the search. Where you specify the index depends on the search you are using with the spl1 command: 
 

• If the SPL search starts with non-generating command, such as search, you can specify the index either before or 
	within the spl1 command portion of the search. 
 

portion of the search. 
 

In the following example, the SPL search assumes that you want to search the default index, main. To use this search in 
SPL2, you can specify the index either before or within the spl1 command portion of the search. 
 

Version 
 

Example 
 

SPL search      status=200 action=purchase 
 
| stats count BY clientip 
 

SPL2 search    $before_spl1 = from sample_data_index | `search status=200 action=purchase 
 
| stats count BY clientip ` 
 

SPL2 search    $within_spl1 = | `search index=sample_data_index status=200 action=purchase 
 
| stats count BY clientip` 
 
Some generating commands, such as tstats and mstats, include the ability to specify the index within the command 
syntax. 
 

In the following example, the SPL search assumes that you want to search the default index, main. In the SPL2 search, 
there is no default index. You must specify the index in the spl1 command portion of the search. 
 

Version 
 

Example 
 

SPL search 
 

| tstats prestats=t count  BY _time span=1d | timechart span=1d count 
 

SPL2 search   $tstats1 = `| tstats prestats=t count where index=main BY _time span=1d | timechart span=1d 
 
count`�h1h2h3}�h5Kuh�(h3h/�h}�ub�$87b5236a-5676-4b39-8219-e08a03a0191b�h+)�}�(h}�(h/XrSPL search 
 

| tstats prestats=t count  BY _time span=1d | timechart span=1d count 
 

SPL2 search   $tstats1 = `| tstats prestats=t count where index=main BY _time span=1d | timechart span=1d 
 
count` 
 
Searches that contain quotation marks 
 

When your SPL search contains quotation marks, it is easier to use the spl1 command backtick ( ` ) character syntax. 
When you use the explicit spl1 command syntax, you must escape the quotation marks. 
 

The following example shows the difference between the backtick ( ` ) character syntax and the explicit spl1 command 
syntax: 
 

Version 
 

Example 
 
SPL search 
 
|status=200 action=purchase | stats count AS "Total Purchased" 
 


346 
 
Version 
 
Example 
 


$quotes1 = from sample_data_index 
 
SPL2 search 
 

| stats count AS "Total Purchased" ` 
 
In this SPL2 search, the search uses the backtick ( ` ) character syntax. 
 

$quotes2 = from sample_data_index 
 
SPL2 search 
 

| stats count AS \"Total Purchased\" " 
 
In this SPL2 search, you must escape the quotation marks because the explicit spl1 command syntax is 
used. 
 


See also 
 

spl1 command 
 

spl1 command syntax details 
spl1 command usage 
 






































347 
 
stats command 
 


stats command overview 
 
Calculates aggregate statistics, such as average, count, and sum, over the incoming search results set. This is similar to 
SQL aggregation. 
 

If the stats command is used without a BY clause, only one row is returned, which is the aggregation over the entire 
incoming result set. If a BY clause is used, one row is returned for each distinct value in the field specified in the BY 
clause. 
 

Syntax 
 

The required syntax is in bold. 
 

stats 
 

<aggregation> ... 
 


How the stats command works 
 

What's important to remember about the stats command is that the command returns only the fields used in the 
aggregation. 
 

Suppose these are some of the events in your dataset: 
 

_time 
 

host 
 

action 
 

quantity 
 

productId 
 

method 
 
6 Apr 2022 9:39:48.000 PM 
 
www2 
 
purchase 
 
1 
 
PZ-SG-G05 
 
POST 
 
6 Apr 2022 9:34:10.000 PM 
 
www1 
 
view 
 
1 
 
GET�h1h2h3}�h5Kuh�(h3h/�h}�ub�$e1d7f4b2-7068-4aad-ba86-1a6379f0a0eb�h+)�}�(h}�(h/X�_time 
 

host 
 

action 
 

quantity 
 

productId 
 

method 
 
6 Apr 2022 9:39:48.000 PM 
 
www2 
 
purchase 
 
1 
 
PZ-SG-G05 
 
POST 
 
6 Apr 2022 9:34:10.000 PM 
 
www1 
 
view 
 
1 
 
GET 
 
6 Apr 2022 9:34:02.000 PM 
 
www3 
 
purchase 
 
2 
 
SC-MG-G10 
 
POST 
 
6 Apr 2022 9:34:01.000 PM 
 
www2 
 
remove 
 
1 
 
CU-PG-G06 
 
GET 
 
6 Apr 2022 9:34:01.000 PM 
 
www1 
 
purchase 
 
3 
 
POST 
 
6 Apr 2022 9:29:55.000 PM 
 
www3 
 
addtocart 
 
2 
 
SC-MG-G10 
 
GET 
 
6 Apr 2022 9:20:51.000 PM 
 
www1 
 
addtocart 
 
DB-SG-G01 
 
GET 
 
6 Apr 2022 9:12:56.000 PM 
 
www2 
 
changequantity 
 
2 
 
FS-SG-G03 
 
GET 
 
6 Apr 2022 9:12:53.000 PM 
 
www1 
 
1 
 
DB-SG-G01 
 
GET 
 
Using functions 
 

You can use a wide range of statistical functions that you can use with the stats command. See SPL2 Stats and Charting 
Functions Quick Reference. 
 

The following search performs several aggregate calculations. When you perform more than one aggregation, separate 
each aggregation with a comma. 
 


348 
 
...| stats count(productId), sum(quantity), max(quantity), min(quantity) 
 

The results look like this: 
 

count(productId) 
 

sum(quantity) 
 

max(quantity) 
 

min(quantity) 
 
7 
 
13 
 
3 
 
1 
 
Grouping results 
 

Use a BY clause when you want to group search results by a specific field. 
 

The following search groups the results by the action field: 
 

...| stats count(action) BY action 
 

The results look like this: 
 

action 
 

count(action) 
 
addtocart 
 
2 
 
changequantity 
 
1 
 
purchase 
 
3 
 
remove 
 
1 
 
view 
 
1 
 
You can perform an aggregation on one field and group the results by another field. The following search groups the 
results by the host field: 
 

...| stats count(productId) BY host 
 

The results look like this: 
 

host 
 

count(productId) 
 
www1 
 
4 
 
www2 
 
3 
 
www3 
 
2 
 
Renaming fields 
 

Use the AS clause to rename a field. The following search renames the count(action) field to count: 
 

...| stats count(action) AS count BY action 
 

The results look like this: 
 

action 
 

count 
 
addtocart 
 
2 
 
changequantity 
 
1 
 



349 
 
action 
 
count 
 
purchase 
 
3 
 
remove 
 
1 
 
view 
 
1 
 
For additional examples, see stats command examples.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$d7d2c99c-ef73-4c28-9987-9d4887a767ed�h+)�}�(h}�(h/XEThe results look like this: 
 

action 
 

count 
 
addtocart 
 
2 
 
changequantity 
 
1 
 



349 
 
action 
 
count 
 
purchase 
 
3 
 
remove 
 
1 
 
view 
 
1 
 
For additional examples, see stats command examples. 
 

You can also use the from command to specify aggregate functions, group by a field, and rename a field. See stats 
command usage for examples. 
 

See also 
 

stats command 
 

stats command usage 
stats command examples 
 

Functions 
 

SPL2 Stats and Charting Functions Quick Reference 
 


stats command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

stats 
 

<aggregation> ... 
 


The AS and BY keywords are displayed in uppercase in the syntax and examples to make the syntax easier to read. 
You can specify these keywords in uppercase or lowercase. 
 

Required arguments 
 

aggregation 
 

Description: A statistical aggregation function. The function can be applied to an eval expression, or to one or 
more fields. By default, the name of the field used in the output is the same as your aggregate function. For 
example, if your search is ... | stats sum(bytes) the field name in the output is sum(bytes). Use the AS clause 
to place the result into a new field with a name that you specify, for example ... | stats sum(bytes) AS 'sum of 
bytes'. 
 




350 
 
Optional arguments 
 

allnum 
 


Syntax: allnum=<boolean> 
 

are numerical. 
Default: false 
 

by-clause 
 

Description: The name of one or more fields to group the results by. You can specify a time span to apply to the 
grouping. The <by-clause> returns one row for each distinct value in the <by-clause> fields. You cannot use the 
wildcard character to specify multiple fields with similar names. You must specify each field separately. 
 

the entire incoming result set. 
 

delim 
 


Syntax: delim=<string> 
 

Default: A single space 
 

partitions 
 

Description: If specified, partitions the incoming search results based on the <by-clause> fields for multithreaded 
reduce. The partitions argument runs the reduce step (in parallel reduce processing) with multiple threads in the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$8900709f-3f81-495a-9157-e24f34898fe7�h+)�}�(h}�(h/Xjreduce. The partitions argument runs the reduce step (in parallel reduce processing) with multiple threads in the 
same search process on the same machine. Compare that with parallel reduce that runs the reduce step in 
parallel on multiple machines. 
 


See also 
 

stats command 
 

stats command usage 
stats command examples 
 


stats command usage 
 

Using the from command instead 
 

Most of the things you can do with the stats command are also possible using the from command. 
 

For example, if your search is ...| stats count() BY host, the following searches return the same results: 
 

from command alternatives 
 
| FROM <dataset> GROUP BY host SELECT count(), host 
 
| SELECT count(), host FROM <dataset> GROUP BY host 
 
For more information, see from command overview. 
 

351 
 
Aggregating multivalue fields 
 

When you perform an aggregation over a multivalue field, each of the values in the field is included in the aggregation. 
Suppose that you have this set of data: 
 

fieldX 
 

fieldY 
 
A 
 
1 
 
A 
 
[2,3,4] 
 
B 
 
[5,6,7,8,9] 
 
When you run this stats command ...| stats count, count(fieldY), sum(fieldY) BY fieldX, these results are 
returned: 
 

fieldX 
 

count 
 

count(fieldY) 
 

sum(fieldY) 
 
A 
 
2 
 
4 
 
10 
 
B 
 
1 
 
5 
 
35 
 


• The results are grouped first by the fieldX. 
 

• The count(fieldY) aggregation counts the rows for the fields in the fieldY column that contain a single value. 
	However, if a field is a multivalue field, the aggregation counts the number of values in the fields. 
 


Grouping by multivalue fields 
 

When grouping by a multivalue field, the stats command produces one row for each value in the field. For example, 
suppose the incoming result set is this: 
 

fieldA 
 

fieldB 
 

fieldC 
 
1 
 
x 
 
V1, V2, V3 
 
2 
 
y 
 
V4, V5 
 
3 
 
z 
 
V2, V5 
 
If you specify the fieldC in the <by-clause>, such as ...| stats sum(fieldA) BY fieldC, the results are: 
 

fieldC 
 

sum(fieldA) 
 
V1 
 
1 
 
V2 
 
4 
 
V3 
 
1 
 
V4 
 
2 
 
V5 
 
5 
 





352 
 
Differences between SPL and SPL2 
 

Command options must be specified before command arguments�h1h2h3}�h5Kuh�(h3h/�h}�ub�$35b14157-da5c-45dd-a7f7-6e88ed3322e2�h+)�}�(h}�(h/XgfieldC 
 

sum(fieldA) 
 
V1 
 
1 
 
V2 
 
4 
 
V3 
 
1 
 
V4 
 
2 
 
V5 
 
5 
 





352 
 
Differences between SPL and SPL2 
 

Command options must be specified before command arguments 
 

The <stats-options> are: 
 

• allnum = <boolean> 
• delim = <"string"> 
 




New span option added to the <by-clause> 
 

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

Version 
 

Example 
 
SPL 
 
Not supported. The SPL equivalent is ...| bin _time span=5m | stats count (error) BY _time 
 
SPL2 
 
...| stats count(error) BY _time span=5m 
 
This example returns the count of events in 5 minute intervals. 
 

You can accomplish that same results using the from command. Here are several examples: 
 

from command alternatives 
 
| FROM <dataset> GROUP BY span(_time, 5m) SELECT count(error), _time 
 
| SELECT count(error), _time FROM <spl> GROUP BY span(_time, 5m) 
 
All functions require parentheses 
 

In SPL, the count function could be specified without parentheses. In SPL2, the parentheses are required when you use 
the count function. For all other functions, you must specify a field inside the parentheses or BY clause. 
 

Version 
 

Example 
 
SPL 
 
...| stats count 
 
SPL2 
 
...| stats count () 
 
Field lists must be comma-delimited 
 

If you specify a list of fields in the <by-clause>, the list must be comma-delimited. Otherwise a parsing error is returned. 
 

Version 
 

Example 
 
SPL 
 
...| stats count BY host source 
 
SPL2 
 
...| stats count () BY host, source 
 






353 
 
Aggregations must be comma-delimited 
 

If you specify multiple aggregations, the aggregations must be comma-delimited. Otherwise a parsing error is returned. 
 

Version 
 

Example 
 
SPL 
 
...| stats avg (fieldX) max (fieldY) BY host 
 
SPL2 
 
...| stats avg (fieldX), max (fieldY) BY host 
 
See also 
 

stats command 
 

stats command syntax details 
stats command examples 
 


stats command examples 
 
The following are examples for using the SPL2 stats command. To learn more about the stats command, see How the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5aea9845-54ad-42ff-82db-efc3a4017c08�h+)�}�(h}�(h/X�stats command syntax details 
stats command examples 
 


stats command examples 
 
The following are examples for using the SPL2 stats command. To learn more about the stats command, see How the 
stats command works. 
 

Many of these examples use the statistical functions. See Overview of SPL2 stats and chart functions. 
 

The AS and BY keywords are displayed in uppercase in the syntax and examples to make the syntax easier to read. You 
can specify the AS and BY keywords in uppercase or lowercase in your searches. 
 

1. Calculate the sum of a field 
 

If you just want a simple calculation, you can specify the aggregation without any other arguments. For example: 
 

... | stats sum(bytes) 
 

This search summarizes the bytes for all of the incoming results. One row is returned with one column. The name of the 
column is the name of the aggregation. For example: 
 

sum(bytes) 
 
3195256256 
 
2. Group the results by a field 
 

This example takes the incoming result set and calculates the sum of the bytes field and groups the sums by the values in 
the host field. 
 

... | stats sum(bytes) BY host 
 

The results contain as many rows as there are distinct host values. There are two columns returned: host and 
sum(bytes). If you don't specify a name for the results using the `AS <field> syntax, then the names of the columns are 
the name of the <by-clause> field and the name of the aggregation. 
 

If there are two distinct hosts, the results are returned as a table similar to this: 
 


354 
 
host 
 
sum(bytes) 
 
host1 
 
3123124124 
 
host2 
 
72132132 
 
3. Specifying multiple aggregations and multiple by-clause fields 
 

You can also specify more than one aggregation and <by-clause> with the stats command. You can rename the output 
fields using the AS <field> clause. For example: 
 

...| stats sum(bytes) AS 'Sum of bytes', avg(bytes) AS Average BY host, sourcetype 
 

This search organizes the incoming search results into groups based on the combination of host and sourcetype. It�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f01ef2c1-9782-4abd-a7dd-67d02a3919b9�h+)�}�(h}�(h/X...| stats sum(bytes) AS 'Sum of bytes', avg(bytes) AS Average BY host, sourcetype 
 

This search organizes the incoming search results into groups based on the combination of host and sourcetype. It 
returns the sum of the bytes in the Sum of bytes field and the average bytes in the Average field for each group. If there 
are two distinct hosts and two distinct sourcetypes, the search will produce results similar to this: 
 

host 
 

sourcetype 
 

Sum of bytes 
 

Average 
 
host1 
 
webaccess 
 
3123124124 
 
3782 
 
host2 
 
webaccess 
 
72132132 
 
3742 
 
host1 
 
json 
 
32132 
 
3213 
 
4. Specifying a time span in the BY clause 
 

This example counts the values in the action field and organized the results into 30 minute time spans. When you use the 
span argument, the field you use in the <by-clause> must be either the _time field, or another field with values in UNIX 
time. For example: 
 

...| stats count(action) AS count BY _time span=30m 
 

See also 
 

stats command 
 

stats command syntax details 
stats command usage 
 




















355 
 
streamstats command 
 


streamstats command overview 
 
The streamstats command adds a cumulative statistical value to each search result as each result is processed. For 
example, you can calculate the running total for a particular field, or compare a value in a search result with a the 
cumulative value, such as a running average. The streamstats command includes options for resetting the aggregates. 
 

Syntax 
 

The required syntax is in bold. 
 

streamstats 
[<by-clause>] 
[current=<bool>] 
[<reset-clause>] 
[window=<int>] 
<aggregation> ... 
 

How the streamstats command works 
 

Suppose that you have the following data: 
 

host 
 

action 
 

bytes 
 
x 
 
LOGON 
 
100 
 
y 
 
APP_START 
 
200 
 
x 
 
FILE_DOWNLOAD 
 
400 
 
x 
 
REBOOT 
 
50 
 
y 
 
LOGON 
 
150 
 
x 
 
LOGON 
 
100 
 
You can use the streamstats command to calculate and add various statistics to the search results. 
 

Compute a moving average over a series of events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$5e04f91f-aaaa-43a1-8f2c-0054b812f56a�h+)�}�(h}�(h/X�400 
 
x 
 
REBOOT 
 
50 
 
y 
 
LOGON 
 
150 
 
x 
 
LOGON 
 
100 
 
You can use the streamstats command to calculate and add various statistics to the search results. 
 

Compute a moving average over a series of events 
 

For each event, you can compute the average of the bytes field over the last 3 events, including the current event. Here's 
the search to use: 
 

... | streamstats window=3 avg(bytes) 
 


The output looks like this: 
 

host 
 

action 
 

bytes 
 

avg(bytes) 
 
x 
 
LOGON 
 
100 
 
100 
 

356 
 
host 
 
action 
 
bytes 
 
avg(bytes) 
 

y 
 

APP_START 
 

200 
 

150 
 
x 
 
FILE_DOWNLOAD 
 
400 
 
233.33 
 
x 
 
REBOOT 
 
50 
 
216.66 
 
y 
 
LOGON 
 
150 
 
200 
 
x 
 
LOGON 
 
100 
 
100 
 

• For the first event, there are no previous events. The value for the bytes field is returned. 
• For the second event, the average is returned from the sum of first and second events. 
 


Calculate a value until a trigger resets the calculation 
 

Suppose you want to calculate a running total of the bytes for each host. However, when the system reboots you want the 
calculation for the total bytes to begin again. You can use the reset after argument to accomplish this. Here's the search 
to use: 
 

...| streamstats sum(bytes) AS total_bytes BY host reset after action="REBOOT" 
 

Because the value in the action field is a string literal, the value needs to be enclosed in double quotation marks. 
 

The running total appears in the total_bytes field. The running total resets each time an event satisfies the 
action="REBOOT"criteria. 
 

The results look like this: 
 

host 
 

action 
 

bytes 
 

total_bytes 
 
x 
 
LOGON 
 
100 
 
100 
 
y 
 
APP_START 
 
200 
 
200 
 
x 
 
FILE_DOWNLOAD 
 
400 
 
500 
 
x 
 
REBOOT 
 
50 
 
550 
 
y 
 
LOGON 
 
150 
 
150 
 
x 
 
LOGON 
 
100 
 
100 
 
The total_bytes field accumulates a sum of the bytes so far for each host. When the reset after clause action="REBOOT" 
occurs in the 4th event, that event shows the sum for the x host, including the bytes for the REBOOT action. The sum of 
the bytes is reset for both the y and x hosts in the next events. 
 

Applying a count to each event�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9226ecf7-a24f-44dc-8271-9a9ef1768cb6�h+)�}�(h}�(h/Xathe bytes is reset for both the y and x hosts in the next events. 
 

Applying a count to each event 
 

You can apply a running count to your search results, which is useful when combined with other commands. 
 

...| streamstats count() 
 



357 
 
The output looks like this: 
 

host 
 

action 
 

bytes 
 

count 
 
x 
 
100 
 
LOGON 
 
1 
 
y 
 
APP_START 
 
200 
 
2 
 
x 
 
FILE_DOWNLOAD 
 
400 
 
3 
 
x 
 
REBOOT 
 
50 
 
4 
 
y 
 
LOGON 
 
150 
 
5 
 
x 
 
LOGON 
 
100 
 
6 
 
See also 
 

streamstats command 
 

streamstats command usage 
streamstats command examples 
 

Functions 
 



streamstats command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

streamstats 
[<by-clause>] 
[current=<bool>] 
[<reset-clause>] 
[window=<int>] 
<aggregation> ... 
 

If you're going to use any of the optional arguments, they must be specified before the <aggregation>. 
 




The AS and BY keywords are displayed in uppercase in the syntax and examples to make the syntax easier to read. 
You can specify these keywords in uppercase or lowercase. 
 

Required arguments 
 

aggregation 
 

Description: A statistical aggregation function. The function can be applied to an eval expression, or one or more 
 


358 
 
fields. You can specify multiple aggregation functions. Separate each aggregation function with a comma. 
 

By default, the name of the field added to the output is the same as your function. For example, if your search is 
... | streamstats avg(bytes) the field name in the output is avg(bytes). Use the AS clause to place the 
generated result into a new field with a name that you specify, for example ... | streamstats avg(bytes) AS 
'avg of bytes'. 
 

The syntax for the <aggregate-function> depends on the function that you use. See SPL2 Stats and Charting 
Functions Quick Reference for information about the statistical functions. 
 

Optional arguments 
 

by-clause 
 

Description: The name of one or more fields to group the results by. The <by-clause> returns one row for each 
distinct value in the <by-clause> fields. Think of the <by-clause> as a grouping. You cannot use the wildcard�h1h2h3}�h5Kuh�(h3h/�h}�ub�$f6722855-d657-4e3f-b7c3-577aa512fe6b�h+)�}�(h}�(h/Xedistinct value in the <by-clause> fields. Think of the <by-clause> as a grouping. You cannot use the wildcard 
character to specify multiple fields with similar names. You must specify each field separately. 
 

the incoming result set. 
 

current 
 


Syntax: current=<boolean> 
 

false, the search uses the field value from the previous event. 
Default: true 
 

reset-clause 
 

Description: You can specify one or more reset condition. If multiple conditions are specified, the reset occurs 
when any of the conditions triggers a reset. See Usage. 
 



Syntax: window=<integer> 
 

number. 
 


See also 
 

streamstats command 
 

streamstats command usage 
streamstats command examples 
 


streamstats command usage 
 






359 
 
Resetting the aggregations 
 

There are several ways to reset the aggregations. You can reset before something occurs, after something occurs, and 
when the values in the <by clause> field changes. 
 

Reset after and reset before 
 

The reset after clause resets the aggregation in the next search result after the condition occurs. 
 

The reset before clause resets the aggregation in the search result in which the condition occurs. 
 


Suppose that you have the following data: 
 

host 
 

bytes 
 

action 
 
x 
 
100 
 
LOGON 
 
y 
 
200 
 
APP_START 
 
x 
 
400 
 
FILE_DOWNLOAD 
 
x 
 
50 
 
REBOOT 
 
y 
 
150 
 
LOGON 
 
x 
 
100 
 
LOGON 
 
You want to calculate the total bytes for each host. However, when the system reboots you want the calculation for the 
total bytes to begin again. You can use the reset after argument to accomplish this. 
 

| streamstats reset after action="REBOOT" sum(bytes) AS total_bytes BY host 
 

Because the value in the action field is a string literal, the value needs to be enclosed in double quotation marks. 
 

The streamstats command calculates a running total of the bytes for each host into a field called total_bytes. The 
running total resets each time an event satisfies the action="REBOOT"criteria. The results look like this: 
 

host 
 

bytes 
 

action 
 

total_bytes 
 
x 
 
100 
 
LOGON 
 
100 
 
y 
 
200 
 
APP_START 
 
200 
 
x 
 
400�h1h2h3}�h5Kuh�(h3h/�h}�ub�$9e3474b3-35cb-4cf4-93f1-90354c53d950�h+)�}�(h}�(h/XUrunning total resets each time an event satisfies the action="REBOOT"criteria. The results look like this: 
 

host 
 

bytes 
 

action 
 

total_bytes 
 
x 
 
100 
 
LOGON 
 
100 
 
y 
 
200 
 
APP_START 
 
200 
 
x 
 
400 
 
FILE_DOWNLOAD 
 
500 
 
x 
 
50 
 
REBOOT 
 
550 
 
y 
 
150 
 
LOGON 
 
150 
 
x 
 
100 
 
LOGON 
 
100 
 
The total_bytes field accumulates a sum of the bytes so far for each host. When the reset after clause action="REBOOT" 
occurs in the 4th event, that event shows the sum for the x host, including the bytes for the REBOOT action. The sum of 
the bytes is reset for both the y and x hosts in the next events. 
 

If the reset before clause is used instead, the results would be this: 
 




360 
 
host 
 
bytes 
 
action 
 
total_bytes 
 
x 
 
100 
 
LOGON 
 
100 
 
y 
 
200 
 
APP_START 
 
200 
 
x 
 
400 
 
FILE_DOWNLOAD 
 
500 
 
x 
 
50 
 
REBOOT 
 
50 
 
y 
 
150 
 
LOGON 
 
150 
 
x 
 
100 
 
LOGON 
 
150 
 
Reset onchange 
 

To reset the aggregation whenever any of the fields specified in the <group-by> clause change, use the reset onchange 
condition. 
 

Continuing with the previous example, you would use this syntax: 
 

...| streamstats reset onchange sum(bytes) AS total_bytes BY host 
 

The output from this search is this: 
 

host 
 

bytes 
 

action 
 

total_bytes 
 
x 
 
100 
 
LOGON 
 
100 
 
y 
 
200 
 
APP_START 
 
200 
 
x 
 
400 
 
FILE_DOWNLOAD 
 
400 
 
x 
 
50 
 
REBOOT 
 
450 
 
y 
 
150 
 
LOGON 
 
150 
 
x 
 
100 
 
LOGON 
 
100 
 
Because the value of the host changes between the 2nd and 3rd rows, the total_bytes is reset in the 3rd row. The reset 
occurs again between the 4th and 5th rows. 
 

Combining reset clauses 
 

You can combine the reset clauses. For example you can use this search: 
 

...| streamstats reset after action="REBOOT" onchange sum(bytes) AS total_bytes BY host 
 

If combined, a reset occurs whenever any of the clauses triggers a reset. 
 

Differences between SPL and SPL2 
 

Command syntax has changed 
 

The streamstats command syntax in SPL2 is substantially different from the streamstats command in SPL. All of the�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c8d69dfe-2fb8-41ed-acfe-885474a0ceea�h+)�}�(h}�(h/X/Differences between SPL and SPL2 
 

Command syntax has changed 
 

The streamstats command syntax in SPL2 is substantially different from the streamstats command in SPL. All of the 
reset conditions have new syntax that makes it easier to write expressions. Instead of individual reset arguments, there is 
one reset argument where you can specify multiple reset conditions. Additionally, you no longer have to escape quotation 
 




361 
 
SPL 
 

The following table shows the SPL syntax and an example for the streamstats command. 
 

Syntax 
 

Example 
 
streamstats 
 
streamstats 
 
reset_on_change=<bool> 
 
reset_on_change=true 
 
reset_before="("<eval-expression>")" 
 
reset_before=(reboot="COMPLETE") 
 
reset_after="("<eval-expression>")" 
 
reset_after=(CPUUtilization > 50) 
 
current=<bool> 
 
current=false 
 
window=<int> 
 
window=5 
 
time_window=<span-length> 
 
global=<bool> 
 
allnum=<bool> 
 
<stats-agg-term>... 
 
avg(CPUUtilization) AS avg_cpu 
 
<by-clause> 
 
BY host 
 
SPL2 
 

The following table shows the SPL2 syntax and an example for the streamstats command. 
 

Syntax 
 

Example 
 
streamstats 
 
streamstats 
 
<stats aggregation> 
 
avg(CPUUtilization) AS avg_cpu 
 
current=<bool> 
 
current=false 
 
window=<int> 
 
window=5 
 
<by-clause> 
 
BY host 
 
reset 
 

before 
 
after 
<eval-expression> 
 

Some command options are not supported in SPL2 
 

The following arguments from SPL do not have an equivalent argument in SPL2. 
 

• allnum 
• global 
 







362 
 
See also 
 

streamstats command 
 

streamstats command syntax details 
streamstats command examples 
 


streamstats command examples 
 
The following are examples for using the SPL2 streamstats command. To learn more about the streamstats command, 
see How the streamstats command works. 
 

Many of these examples use the statistical functions. See Overview of SPL2 stats and chart functions. 
 

1. Add a running count to each search result 
 

In the following search, for each search result a new field is appended with a count of the results based on the host value.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$25f53904-0a81-4236-b510-3fdcdf77929b�h+)�}�(h}�(h/XK1. Add a running count to each search result 
 

In the following search, for each search result a new field is appended with a count of the results based on the host value. 
The count is cumulative and includes the current result. 
 

| from <dataset> | streamstats count() 
 

For example, if your data looks like this: 
 

host 
 

_time 
 
x 
 
2022-07-16T00:00:00.000Z 
 
y 
 
2022-07-15T00:00:00.000Z 
 
x 
 
2022-07-14T00:00:00.000Z 
 
x 
 
2022-07-13T00:00:00.000Z 
 
y 
 
2022-07-12T00:00:00.000Z 
 


The output would look like this: 
 

host 
 

_time 
 

count 
 
x 
 
2022-07-16T00:00:00.000Z 
 
1 
 
y 
 
2022-07-15T00:00:00.000Z 
 
2 
 
x 
 
2022-07-14T00:00:00.000Z 
 
3 
 
x 
 
2022-07-13T00:00:00.000Z 
 
4 
 
y 
 
2022-07-12T00:00:00.000Z 
 
5 
 
2. Using a <by-clause> to reset the search results count 
 

The following search uses the host field to reset the count. For each search result a new field is appended with a count of 
the results based on the host value. The count is cumulative and includes the current result. 
 


363 
 
| from <dataset> | streamstats count() BY host 
 

For example, if your data looks like this: 
 

host 
 

_time 
 
x 
 
2022-07-16T00:00:00.000Z 
 
y 
 
2022-07-15T00:00:00.000Z 
 
x 
 
2022-07-14T00:00:00.000Z 
 
x 
 
2022-07-13T00:00:00.000Z 
 
y 
 
2022-07-12T00:00:00.000Z 
 


The output would look like this: 
 

host 
 

_time 
 

count 
 
x 
 
2022-07-16T00:00:00.000Z 
 
1 
 
y 
 
2022-07-15T00:00:00.000Z 
 
1 
 
x 
 
2022-07-14T00:00:00.000Z 
 
2 
 
x 
 
2022-07-13T00:00:00.000Z 
 
3 
 
y 
 
2022-07-12T00:00:00.000Z 
 
2 
 
3. Specifying reset options 
 

This example performs an aggregation on the bytes field and displays the total number of bytes by host. The total number 
of bytes are reset when either action="REBOOT" or when the host changes. The reset options must be specified before 
the aggregation. 
 

...| streamstats reset after action="REBOOT" onchange sum(bytes) AS total_bytes BY host 
 


For detailed examples using the reset options, see streamstats command usage. 
 

4. Compute an aggregation of a field over a series of events�h1h2h3}�h5Kuh�(h3h/�h}�ub�$34853c75-0c02-4937-a710-6e456a227f5f�h+)�}�(h}�(h/X�For detailed examples using the reset options, see streamstats command usage. 
 

4. Compute an aggregation of a field over a series of events 
 

For each event, compute the average of the bytes field over the last 5 events, including the current event. The window 
option must be specified before the aggregation. 
 

... | streamstats window=5 avg(bytes) 
 

5. Using the streamstats command with other commands 
 

You can use the streamstats command with other commands to create a set events with hourly timestamps. For 
example, you can use the repeat function, with the eval and streamstats commands to create a set of 5 events with 
incremental timestamps: 
 

| FROM repeat({}, 5) | eval _time = now() | streamstats count() | eval _time=_time-(count*3600) 
 



364 
 
The results look something like this: 
 

_time 
 

count 
 
2022-02-25 15:35:14 
 
1 
 
2022-02-25 14:35:14 
 
2 
 
2022-02-25 13:35:14 
 
3 
 
2022-02-25 12:35:14 
 
4 
 
2022-02-25 11:35:14 
 
5 
 
For more examples like this, see the "Examples" section in the repeat dataset function topic. 
 

See also 
 

streamstats command 
 

streamstats command syntax details 
streamstats command usage 
 








































365 
 
thru command 
 


thru command overview 
 
Writes data to a writeable dataset and then passes the same data to the next command in the search string. By default, 
the thru command appends data to the dataset. 
 

Syntax 
 

The required syntax is in bold. 
 

thru 
 

<dataset> 
 



See also 
 

thru command 
 

thru command usage 
thru command examples 
 

Related information 
 



thru command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

thru 
 

<dataset> 
 

Required arguments 
 

dataset 
 


Syntax: <dataset> 
 


Optional arguments 
 

mode 
 


Syntax: mode=(append | replace) 
 

366 
 
Description: Specifies whether the search results are appended to the existing data in the dataset or replace the 
data in the dataset. 
 


See also 
 

thru command 
 

thru command usage 
thru command examples 
 


thru command usage 
 
The thru command is new in SPL2. Like the into command, the thru command replaces the outputlookup command.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$50032a07-1654-491a-9101-cb970b6083d5�h+)�}�(h}�(h/X�See also 
 

thru command 
 

thru command usage 
thru command examples 
 


thru command usage 
 
The thru command is new in SPL2. Like the into command, the thru command replaces the outputlookup command. 
 


The dataset that you specify with the thru command must be a dataset that can be written to. 
 

The default is mode=append, however not all built-in datasets support the mode options. 
 

• The main dataset does not support either the append or replace modes. This means you cannot use the thru 
	command to write data to the main dataset. 
 

actions dataset does not support the replace mode because actions that have already been invoked can't be 
uninvoked. For example, you can't unsend an email. However you can append data to the actions dataset. 
 

The following table lists the built-in datasets and the thru command modes that each dataset supports. 
 

Build-in datasets 
 

Dataset kind 
 

Supported modes 
 
main 
 
index 
 
none 
 
metrics 
 
metric 
 
none 
 
actions 
 
splv1sink 
 
mode=append 
 
geo.hex 
 
lookup 
 
none 
 
geo.iplocation 
 
lookup 
 
none 
 
catalog.* 
 
catalog 
 
none 
 
catalog.metrics 
 
catalog 
 
none 
 
ingest.events 
 
splv1sink 
 
mode=append 
 
ingest.metrics 
 
splv1sink 
 
mode=append 
 
See also 
 

thru command 
 

thru command syntax details 
thru command examples 
 



367 
 
thru command examples 
 
The following are examples for using the SPL2 thru command. To learn more about the thru command, see How the thru 
command works. 
 

1. Append all of the search results to a dataset 
 

This example appends all the incoming search result set to the actions dataset. Those same search results are also 
passed into the eval command. 
 

... | thru actions | eval field=<expression> 
 

2. Replace all of the search results in a dataset 
 

In this example, all of the existing data in the customers dataset is replaced by the incoming search result set. Those 
same search results are passed into the eval command. 
 

... | thru mode=replace customers | eval field=<expression> 
 

See also 
 

thru command 
 

thru command syntax details 
thru command usage 
 
































368�h1h2h3}�h5Kuh�(h3h/�h}�ub�$143f6ecf-64bd-4e70-8c58-94487d4f67e5�h+)�}�(h}�(h/XUsame search results are passed into the eval command. 
 

... | thru mode=replace customers | eval field=<expression> 
 

See also 
 

thru command 
 

thru command syntax details 
thru command usage 
 
































368 
 
timechart command 
 


timechart command overview 
 
Creates a time series chart with a corresponding table of statistics. 
 

A timechart is a aggregation applied to a field to produce a chart, with time used as the X-axis. You can specify a split-by 
field, where each distinct value of the split-by field becomes a series in the chart. 
 

Syntax 
 

The required syntax is in bold. 
 

timechart 
 

[agg=<aggregation>] [<bin-options>... ] 
 


You must specify either a <single-aggregate> or an <eval-expression> with a BY clause. 
 



See also 
 

timechart command 
 

timechart command usage 
timechart command examples 
 

Functions 
 


Related information 
 



timechart command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

timechart 
 

[agg=<aggregation>] [<bin-options>... ] 
 





369 
 
Required arguments 
 

When using the timechart command, you must specify either a single-aggregate> or an eval-expression> with a BY 
clause. 
 

single-aggregate 
 

Description: An aggregation applied to a single field, including an evaluated field. For <stats-function>, see 
stats-function in the Optional arguments section. No wildcards are allowed in the field name. A field must be 
specified, except when using the count() function, which applies to all events instead of a specific field. 
 

eval-expression 
 

<function> 
 

these evaluations to work, your field values need to be valid for the type of operation. For example, with the 
exception of addition, arithmetic operations might not produce valid results if the values are not numerical. 
 

a period '+' the search treats both values as strings, regardless of their actual data type. 
 

If you use an eval-expression>, the split-by-clause> is required. 
 

split-by-clause 
 

Description: A field to group the results by. If <field> is numerical, default discretization is applied. You can�h1h2h3}�h5Kuh�(h3h/�h}�ub�$4f99ebb0-b09e-4220-8449-ad8e2c099a58�h+)�}�(h}�(h/X�If you use an eval-expression>, the split-by-clause> is required. 
 

split-by-clause 
 

Description: A field to group the results by. If <field> is numerical, default discretization is applied. You can 
specify <timechart-options> to apply specific discretizations. You can only use one <split-by-clause>. See the 
Timechart options section. 
 

Optional arguments 
 

agg 
 


Syntax: agg=( <stats-function> ( <field> ) [AS <field>] ) 
 

function can be applied to an eval expression, or to a field or set of fields. Use the AS clause to place the result 
into a new field with a name that you specify. You can use wild card characters in field names. With the limit and 
agg options, you can specify series filtering. If you set limit=0, no series filtering occurs. 
 

bin-options 
 

Description: Options that you can use to specify discreet bins, or groups, to organize the information. The 
<bin-options> set the maximum number of bins, not the target number of bins. For an explanation of these 
options, see the Bins options section in this topic. 
 


cont 
 



Syntax: cont=<boolean> 
 

Default: true 
 



370 
 
fixedrange 
 

Description: Specifies whether or not to enforce the earliest and latest times of the search. Setting 
fixedrange=false allows the timechart command to constrict or expand to the time range covered by all events 
in the dataset. 
 


format 
 



Syntax: format=<string> 
 

split-by field. The format option takes precedence over the sep option. You can specify a parameterized 
expression with the stats aggregator and function ($AGG$) and the value of the split-by field ($VAL$). 
 

limit 
 


Syntax: limit=<int> 
 

agg options, you can specify series filtering. If you set limit=0, no series filtering occurs and all distinct values are 
used. Setting limit=N keeps the N highest scoring distinct values of the split-by field. All other values are grouped 
 


◊ If a single aggregation is specified, the score is based on the sum of the values in the aggregation for that�h1h2h3}�h5Kuh�(h3h/�h}�ub�$34dd7148-d407-4a33-8206-89a24326e16f�h+)�}�(h}�(h/X�◊ If a single aggregation is specified, the score is based on the sum of the values in the aggregation for that 
	split-by value. For example, for timechart avg(foo) BY <field> the avg(foo) values are added up for 
	each value of <field> to determine the scores. 
 

example, for timechart avg(foo) max(bar) BY <field>, the top scoring values for <field> are the most 
common values of <field>. 
 

takes precedence over 'bar', which takes precedence over 'foo'. See timechart command usage. 
 

partial 
 


Syntax: partial=<boolean> 
 

Default: True. Partial time bins are retained. 
 

sep 
 


Syntax: sep=<string> 
 

split-by field. This is equivalent to setting format to $AGG$<sep>$VAL$. 
 

stats-function 
 

Description: Statistical functions that you can use with the timechart command. Each time you invoke the 
timechart command, you can use one or more functions. See timechart command usage. 
 

For a list and description of the supported statistical and charting functions, see Stats and charting functions 
Quick Reference. 
 

Bins options 
 

bins 
 


Syntax: bins=<int> 
 


371 
 
Description: Sets the maximum number of bins to discretize into. This does not set the target number of bins. It 
finds the smallest bin size that results in no more than N distinct bins. Even though you specify a number such as 
300, the resulting number of bins might be much lower. 
 


minspan 
 

Description: Specifies the smallest span granularity to use automatically inferring span from the data time range. 
See timechart command usage. 
 

span 
 


Syntax: span=<log-span> | span=<span-length> | span=<snap-to-time> 
 

that snaps to a specific time. For descriptions of each of these options, see the Span options section. 
 

The starting time of a bin might not match your local timezone. See timechart command usage. 
 

start-end 
 

Description: Sets the minimum and maximum extents for numerical bins. Data outside of the [start, end] range is 
discarded. 
 

aligntime�h1h2h3}�h5Kuh�(h3h/�h}�ub�$32808a20-efb2-4df5-9c38-7f073edd5b1d�h+)�}�(h}�(h/Xstart-end 
 

Description: Sets the minimum and maximum extents for numerical bins. Data outside of the [start, end] range is 
discarded. 
 

aligntime 
 

Description: Align the bin times to something other than base UNIX time (epoch 0). The aligntime option is valid 
only when doing a time-based discretization. Ignored if span is in days, months, or years. 
 

Span options 
 

log-span 
 

Description: Sets a log-based span. The first number is a coefficient. The second number is the base. If the first 
number is supplied, it must be a real number >= 1.0 and < the base. Base, if supplied, must be real number > 1.0 
(strictly greater than 1). 
 

span-length 
 

Description: A span of each bin, based on time. If the timescale is provided, this is used as a time range. If not, 
this is an absolute bin length. 
 

timescale 
 

Description: Timescale units. 
Default: <sec> 
 

Timescale 
 

Valid syntax 
 

Description 
 
<sec> 
 
s | sec | secs | second | seconds 
 
Time scale in seconds 
 
<min> 
 
m | min | mins | minute | minutes 
 
Time scale in minutes 
 
<hr> 
 
h | hr | hrs | hour | hours 
 
Time scale in hours 
 


372 
 
Timescale 
 
Valid syntax 
 
Description 
 
<day> 
 
d | day | days 
 
Time scale in days 
 
<week> 
 
w | week | weeks 
 
Time scale in weeks 
 
<month> 
 
mon | month | months 
 
Time scale in months 
 
<subseconds> 
 
us | ms | cs | ds 
 
Time scale in microseconds (us), milliseconds (ms), centiseconds (cs), or deciseconds (ds) 
 

snap-to-time 
 

Description: A span of each bin, based on a relative time unit and a snap to time unit. The <snap-to-time> must 
include the <relative-time-unit>, the @ symbol, and the <snap-to-time-unit>. The offset, represented by the plus 
(+) or minus (-) is optional. If the <time_integer> is not specified, 1 is the default. For example if you specify w as 
the <relative-time-unit>, 1 week is assumed. 
 

The snap-to-time option is only used with the week timescale unit. It cannot be used with other timescale units such as 
minutes or quarters. 
 

Timechart options�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3f07e508-8afa-4707-9fd9-e083bca1fbde�h+)�}�(h}�(h/X�The snap-to-time option is only used with the week timescale unit. It cannot be used with other timescale units such as 
minutes or quarters. 
 

Timechart options 
 

The <timechart-options> are part of the <split-by-clause> and must be specified after the BY keyword. See the Required 
arguments section. 
 

timechart-options 
 

Description: Timechart options for controlling the behavior of splitting by a field. See the Bins options section. 
 

nullstr 
 


Syntax: nullstr=<string> 
 

split-by field. 
Default: NULL 
 


Syntax: otherstr=<string> 
 

Default: OTHER 
 

usenull 
 


Syntax: usenull=<bool> 
 

for the series is controlled by the nullstr option. 
Default: true 
 

useother 
 

Description: You specify which series to include in the results table by using the agg and limit options. The 
useother option specifies whether to merge all of the series not included in the results table into a single new 
 

Default: true 
 

373 
 
See also 
 

timechart command 
 

timechart command usage 
timechart command examples 
 


timechart command usage 
 
The timechart command is a transforming command, which orders the search results into a data table. 
 

bins and span arguments 
 

The timechart command accepts either the bins argument OR the span argument. If you specify both, only span is used. 
The bins argument is ignored. 
 

If you do not specify either bins or span, the timechart command uses the default bins=100. 
 

Default time spans 
 

It you use the predefined time ranges in the time range picker, and do not specify the span argument, the following table 
shows the default span that is used. 
 

Time range 
 

Default span 
 
Last 15 minutes 
 
10 seconds 
 
Last 60 minutes 
 
1 minute 
 
Last 4 hours 
 
5 minutes 
 
Last 24 hours 
 
30 minutes 
 
Last 7 days 
 
1 day 
 
Last 30 days 
 
1 day 
 
Previous year 
 
1 month 
 


Spans used when minspan is specified 
 

When you specify a minspan value, the span that is used for the search must be equal to or greater than one of the span�h1h2h3}�h5Kuh�(h3h/�h}�ub�$51e0111e-eac6-4218-b49a-b9fe330d6f62�h+)�}�(h}�(h/X1 day 
 
Previous year 
 
1 month 
 


Spans used when minspan is specified 
 

When you specify a minspan value, the span that is used for the search must be equal to or greater than one of the span 
threshold values in the following table. For example, if you specify minspan=15m that is equivalent to 900 seconds. The 
minimum span that can be used is 1800 seconds, or 30 minutes. 
 

Span threshold 
 

Time equivalents 
 
1 second 
 
5 second 
 
10 second 
 


374 
 
Span threshold 
 
Time equivalents 
 
30 second 
 
60 second 
 
1 minute 
 
300 second 
 
5 minutes 
 
600 second 
 
10 minutes 
 
1800 second 
 
30 minutes 
 
3600 seconds 
 
1 hour 
 
86400 seconds 
 
1 day 
 
2592000 seconds 
 
30 days 
 
Bin time spans and local time 
 

The span option always rounds down the starting date for the first bin. There is no guarantee that the bin start time used 
by the timechart command corresponds to your local timezone. In part this is due to differences in daylight savings time 
 


Bin time spans versus per_* functions 
 

The functions, per_day(), per_hour(), per_minute(), and per_second() are aggregator functions and are not responsible 
for setting a time span for the resultant chart. These functions are used to get a consistent scale for the data when an 
explicit span is not provided. The resulting span can depend on the search time range. 
 

For example, per_hour() converts the field value so that it is a rate per hour, or sum(<hours in the span>). If your chart 
span ends up being 30m, it is sum()*2. 
 

If you want the span to be 1h, you still have to specify the argument span=1h in your search. 
 

You can calculate per_hour() on one field and per_minute(), or any combination of the functions, on a different field in 
the same search. 
 

Split-by fields 
 

If you specify a split-by field, ensure that you specify the bins and span arguments before the split-by field. If you specify 
these arguments after the split-by field, Splunk software assumes that you want to control the bins on the split-by field, not�h1h2h3}�h5Kuh�(h3h/�h}�ub�$6fe24570-89fe-41fe-b28f-9f96342dba2e�h+)�}�(h}�(h/X�these arguments after the split-by field, Splunk software assumes that you want to control the bins on the split-by field, not 
 


You cannot use a field that you specify in a function as your split-by field. For example, you will not be able to run: 
 

... | timechart sum(A) by A span=log2 
 

However, you can work around this with an eval expression, for example: 
 

... | eval A1=A | timechart sum(A) by A1 span=log2 
 






375 
 
Functions and memory usage 
 

Some functions are inherently more expensive, from a memory standpoint, than other functions. For example, the 
distinct_count function requires far more memory than the count function. The values and list functions also can 
consume a lot of memory. 
 

If you are using the distinct_count function without a split-by field or with a low-cardinality split-by by field, consider 
replacing the distinct_count function with the the estdc function (estimated distinct count). The estdc function might 
result in significantly lower memory usage and run times. 
 

Lexicographical order 
 

Lexicographical order sorts items based on the values used to encode the items in computer memory. In Splunk software, 
this is almost always UTF-8 encoding, which is a superset of ASCII. 
 

• Numbers are sorted before letters. Numbers are sorted based on the first digit. For example, the numbers 10, 9, 
	70, 100 are sorted lexicographically as 10, 100, 70, 9. 
 

• Symbols are not standard. Some symbols are sorted before numeric values. Other symbols are sorted before or 
	after letters. 
 

You can specify a custom sort order that overrides the lexicographical order. See the blog Order Up! Custom Sort Orders. 
 

Differences between SPL and SPL2 
 

The <where-clause> is removed in the SPL2 syntax 
 

The <where-clause>, from the <split-by-clause>, is removed in the SPL2 syntax. The where <agg-func-name> in top<N> 
can be achieved by using agg=<agg-func-name> limit=<int>. 
 

Version 
 

Example 
 
SPL 
 
...| timechart avg(foo) by host where sum in top5 
 
SPL2�h1h2h3}�h5Kuh�(h3h/�h}�ub�$87b9515b-127b-48c8-a34b-31c88296aa95�h+)�}�(h}�(h/X6can be achieved by using agg=<agg-func-name> limit=<int>. 
 

Version 
 

Example 
 
SPL 
 
...| timechart avg(foo) by host where sum in top5 
 
SPL2 
 
...| timechart agg=sum limit=5 avg(foo) by host 
 
Some options only apply to the <split-by-clause> in SPL2 
 

The useother option and other timechart options apply only to the split-by field and must be specified immediately after 
the split-by field. 
 

Version 
 

Example 
 
SPL 
 
...| timechart count() useother=false by host 
 
SPL2 
 
...| timechart count() by host useother=false 
 
See also 
 

timechart command 
 

timechart command syntax details 
timechart command examples 
 


376 
 
timechart command examples 
 
The following are examples for using the SPL2 timechart command. To learn more about the timechart command, see 
How the timechart command works. 
 

1. Chart the count for each host in 1 hour increments 
 

For each hour, calculate the count for each host value. 
 

...| timechart span=1h count() by host 
 

2. Chart the average of "CPU" for each "host" 
 

For each minute, calculate the average value of "CPU" for each "host". 
 

... | timechart span=1m avg(CPU) BY host 
 

3. Chart the product of two averages for each host 
 

For each minute, calculate the product of the average "CPU" and average "MEM" and group the results by each host 
value. This example uses an <eval-expression> with the avg stats function, instead of a <field>. 
 

... | timechart span=1m eval(avg(CPU) * avg(MEM)) BY host 
 

4. Chart the average of cpu_seconds by processor 
 

Create a timechart of the average of cpu_seconds by processor, rounded to 2 decimal places. 
 

... | timechart eval(round(avg(cpu_seconds),2)) BY processor 
 

5. Chart the average "thruput" of hosts over time 
 

Create a timechart of the average of the thruput field and group the results by each host value. 
 

... | timechart span=5m avg(thruput) BY host 
 

6. Align the chart time bins to local time 
 

Align the time bins to 5am (local time). Set the span to 12h. The bins will represent 5am - 5pm, then 5pm - 5am (the next 
day), and so on.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$200135a8-5aa9-42f8-9555-7b9093f10ee4�h+)�}�(h}�(h/XO6. Align the chart time bins to local time 
 

Align the time bins to 5am (local time). Set the span to 12h. The bins will represent 5am - 5pm, then 5pm - 5am (the next 
day), and so on. 
 

...| timechart _time span=12h aligntime=@d+5h 
 

See also 
 

timechart command 
 

timechart command syntax details 
timechart command usage 
 



377 
 
timewrap command 
 


timewrap command overview 
 
The timewrap command displays, or wraps, the output of the timechart command so that every period of time is a 
different series. 
 

Use the timewrap command to compare data over specific time period, such as day-over-day or month-over-month. You 
can also use the timewrap command to compare multiple time periods, such as a two week period over another two week 
period. See timewrap command syntax details. 
 

Syntax 
 

The required syntax is in bold. 
 

timewrap 
	<timewrap-span> 
	[align=now | end] 
 

How the timewrap command works 
 

Because he timewrap command is used with the timechart command, let's start with that. 
 

The following search counts the number of earthquakes in Alaska where the magnitude is greater than or equal to 5.3. 
The results are organized in spans of 1 day. 
 

|search source=all_month.csv place=*alaska* mag>=5.3 | timechart count() span=1d 
 

The results look something like this: 
 

_time 
 

count 
 
08 Sep 2021 
 
1 
 
09 Sep 2021 
 
1 
 
10 Sep 2021 
 
1 
 
11 Sep 2021 
 
0 
 
12 Sep 2021 
 
0 
 
13 Sep 2021 
 
0 
 
14 Sep 2021 
 
1 
 
15 Sep 2021 
 
0 
 
16 Sep 2021 
 
0 
 
The results continue through 2021-09-23 but are truncated in this example. 
 





378 
 
Combining the timewrap and timechart commands 
 

Now let's add the timewrap command to the search and specify a <timewrap-span> of 1week. 
 

|search source=all_month.csv place=*alaska* mag>=5.3 | timechart count() span=1d | timewrap 1week 
 

The results are organized based on the day you run the search, which in this example 02 Oct 2021. Going back in 1 week 
increments to the week that the data starts (08 Sep 2021), the results look something like this: 
 

_time 
 

3weeks_before 
 

2weeks_before�h1h2h3}�h5Kuh�(h3h/�h}�ub�$819ab332-50d2-45b1-bc59-2d9178661843�h+)�}�(h}�(h/X�increments to the week that the data starts (08 Sep 2021), the results look something like this: 
 

_time 
 

3weeks_before 
 

2weeks_before 
 

1week_before 
 
26 Sep 2021 
 
0 
 
0 
 
27 Sep 2021 
 
0 
 
0 
 
28 Sep 2021 
 
1 
 
0 
 
29 Sep 2021 
 
1 
 
0 
 
0 
 
30 Sep 2021 
 
1 
 
0 
 
1 
 
01 Oct 2021 
 
1 
 
0 
 
02 Oct 2021 
 
0 
 
0 
 
Using the <timewrap-span> argument 
 

The <timewrap-span> you specify controls how many rows are returned in the results and the ranges for the counts 
displayed in the columns. The <timewrap-span> specified is 1week so there are 7 rows in the output. Counting back from 
02 Oct 2021, there are 3 weeks between 02 Oct 2021 and 08 Sep 2021, which is why the column headings refer to 3 
weeks, 2 weeks, and 1 week before. 
 

The first date in the output is 26 Sep 2021. Counting back 3 weeks is 05 Sep 2021. There are no events for that date, 
which is why the output contains no value in the column 3weeks_before for 26 Sep 2021. 
 

Look at the date 29 Sep 2021. Counting back 3 weeks is 08 Sep 2021. There is 1 earthquake for that date, as shown in 
the results for the first search. 
 

This pattern continues for the rest of the results. 
 

See also 
 

timewrap command 
 

timewrap command usage 
timewrap command examples 
 

Related information 
 



timewrap command syntax details 
 





379 
 
Syntax 
 

timewrap 
	<timewrap-span> 
	[align=now | end] 
 

Required arguments 
 

<timewrap-span> 
 

Description: A span of each bin, based on time. The timescale is required. The int is not required. If <int> is not 
specified, 1 is assumed. For example if day is specified for the timescale, 1day is assumed. See the Timescale 
options section. 
 

Optional arguments 
 

align 
 


Syntax: align=now | end 
 

Default: end 
 

Timescale options 
 

<timescale> 
 

Description: Time scale units. 
 

	Time 
scale 
 


Syntax 
 


Description 
 

<sec> 
 
s | sec | secs | 
second | seconds 
 

Time scale in seconds. 
 

<min> 
 
min | mins | minute | 
minutes 
 

Time scale in minutes. 
 

<hr> 
 
h | hr | hrs | hour | 
hours 
 

Time scale in hours. 
 
<day> 
 
d | day | days 
 
Time scale in days. 
 
<week>�h1h2h3}�h5Kuh�(h3h/�h}�ub�$24b44595-3cc1-4c17-9fdc-a7223c276a5a�h+)�}�(h}�(h/XTime scale in seconds. 
 

<min> 
 
min | mins | minute | 
minutes 
 

Time scale in minutes. 
 

<hr> 
 
h | hr | hrs | hour | 
hours 
 

Time scale in hours. 
 
<day> 
 
d | day | days 
 
Time scale in days. 
 
<week> 
 
w | week | weeks 
 
Time scale in weeks. 
 
Time scale in months. 
 

<month> 
 

m | mon | month | 
months 
 


The timewrap command uses the abbreviation m to refer to months. Other 
commands , such as timechart and bin use the abbreviation m to refer to 
minutes. 
 

<quarter> 
 
qtr | quarter | 
quarters 
 

Time scale in quarters 
 
<year> 
 
y | yr | year | years 
 
Time scale in years. 
 



380 
 
See also 
 

timewrap command 
 

timewrap command usage 
timewrap command examples 
 


timewrap command usage 
 
You must use the timechart command in the search before you use the timewrap command. 
 

The wrapping is based on the end time of the search. If you specify the time range of All time, the wrapping is based on 
today's date. You see this in the timestamps for the _time field and in the data series names. 
 

Differences between SPL and SPL2 
 

The following arguments from SPL do not have an equivalent argument in SPL2. 
 

• series 
 


See also 
 

timewrap command 
 

timewrap command syntax details 
timewrap command examples 
 


timewrap command examples 
 
The following are examples for using theSPL2 timewrap command. To learn more about the timewrap command, see How 
the timewrap command works. 
 

1. Week over week comparisons 
 

This example displays a timechart that has a span of 1 day for each count in a week over week comparison table. Each 
table column, which is the series, is 1 week of time. 
 

... | timechart count span=1d | timewrap 1week 
 

See also 
 

timewrap command 
 

timewrap command syntax details 
timewrap command usage 
 




381 
 
union command 
 


union command overview 
 
Merges the results from two or more datasets into one larger dataset. One of the datasets can be the incoming search 
results that are then piped into the union command and merged with a second dataset.�h1h2h3}�h5Kuh�(h3h/�h}�ub�$b8658c21-ef06-479d-b5a7-3113349c3746�h+)�}�(h}�(h/X\results that are then piped into the union command and merged with a second dataset. 
 

If all of the datasets that you want to merge are indexes, you can use the indexes dataset function instead of the union 
command. See indexes dataset function. 
 

Syntax 
 

The required syntax is in bold. 
 

union 
 


How the union command works 
 

Datasets with identical field names 
 

Consider the following two datasets: 
 

products-amer 
 

productID 
 

product_name 
 

supplierID 
 

supplier_name 
 

categoryID 
 
BS-AG-G09 
 
Benign Space Debris 
 
A51G-USA 
 
Area 51 Games 
 
ARCADE 
 
SF-BVS-G01 
 
Grand Theft Scooter 
 
IP-PAN 
 
Isthmus Pastimes 
 
ARCADE 
 
products-apac 
 

productID 
 

product_name 
 

supplierID 
 

supplier_name 
 

categoryID 
 
DC-SG-G02 
 
Dream Crusher 
 
PMG-KOR 
 
Play More Games 
 
STRATEGY 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
TF-JAP 
 
Tiger Fun 
 
STRATEGY 
 
SC-MG-G10 
 
SIM Cubicle 
 
PMG-KOR 
 
Play More Games 
 
SIMULATION 
 
You can use the union command to bring these dataset together. For example: 
 

$products = union products-amer, products-apac 
 

The results look something like this: 
 

productID 
 

product_name 
 

supplierID 
 

supplier_name 
 

categoryID 
 
BS-AG-G09 
 
Benign Space Debris 
 
A51G-USA 
 
Area 51 Games 
 
ARCADE 
 
DC-SG-G02 
 
Dream Crusher 
 
PMG-KOR 
 
Play More Games 
 
STRATEGY 
 



382 
 
productID 
 
product_name 
 
supplierID 
 
supplier_name 
 
categoryID 
 
PZ-SG-G05 
 
Puppies vs. Zombies 
 
TF-JAP 
 
Tiger Fun 
 
STRATEGY 
 
SC-MG-G10 
 
SIM Cubicle 
 
PMG-KOR 
 
Play More Games 
 
SIMULATION 
 
SF-BVS-G01 
 
Grand Theft Scooter 
 
IP-PAN 
 
Isthmus Pastimes 
 
ARCADE 
 
Datasets with different field names 
 

Consider the following events from two datasets: 
 

products-apac 
 

productID 
 

product_name 
 

supplierID 
 

supplier_name 
 

categoryID 
 
DC-SG-G02 
 
Dream Crusher 
 
PMG-KOR 
 
Play More Games 
 
STRATEGY 
 
suppliers_apac 
 

supplierId 
 

supplier_name 
 

contact_name 
 

email 
 

address 
 
PMG-KOR 
 
Play More Games 
 
Vanya Patel 
 
vanya@sample.com 
 
234 Sejong-daero ... Seoul South Korea�h1h2h3}�h5Kuh�(h3h/�h}�ub�$1cf4bbb1-2e36-44a9-81aa-77de1a908980�h+)�}�(h}�(h/XuPlay More Games 
 
STRATEGY 
 
suppliers_apac 
 

supplierId 
 

supplier_name 
 

contact_name 
 

email 
 

address 
 
PMG-KOR 
 
Play More Games 
 
Vanya Patel 
 
vanya@sample.com 
 
234 Sejong-daero ... Seoul South Korea 
 
Notice that both events have a field called supplier_name and fields for the supplier ID, but with different capitalization: 
supplierID and supplierId. 
 

You can use the union command to bring these dataset together. For example: 
 

$products = union products-apac, suppliers_apac 
 

When the datasets are unioned, the fields from both datasets added to the output. The NULL value is added to fields that 
were not in the original event. 
 

The results look something like this: 
 

address 
 

categoryID 
 

contact_name 
 

email 
 

productID 
 

product_name 
 

supplierID 
 

supplierId 
 

NULL 
 

STRATEGY 
 

NULL 
 

NULL 
 

DC-SG-G02 
 

Dream Crusher 
 

PMG-KOR 
 

NULL 
 

234 
Sejong-daero 
 


NULL 
 


Vanya Patel 
 


vanya@sample.com 
 


NULL 
 


NULL 
 


NULL 
 


PMG-KOR 
 
South Korea 
 
Both events have a field called supplier_name that appears in the output with the same value. However, because the 
supplier ID fields have different capitalization, both fields appear in the output, even though the fields have the same 
value. 
 

See also 
 

union command 
 

union command usage 
union command examples 
 


383 
 
union command syntax details 
 

Syntax 
 

The required syntax is in bold. 
 

union 
 


Required arguments 
 

dataset 
 


Syntax: [ <dataset-kind>"."]<dataset-name> 
 

only need to specify the dataset kind for built-in datasets that include the kind. The dataset can be the incoming 
set of search results, a dataset that has been defined in the Metadata Catalog, or a literal dataset that you type in. 
 

usage. 
 

See also 
 

union command 
 

union command usage 
union command examples 
 


union command usage 
 
The union command is a generating command. Generating commands fetch information from the datasets, without any 
transformations. 
 

You can use the union command at the beginning of your search to combine two datasets or later in your search where�h1h2h3}�h5Kuh�(h3h/�h}�ub�$0b60eeb6-4f7f-4d2a-b5bc-84111d33224d�h+)�}�(h}�(h/X3transformations. 
 

You can use the union command at the beginning of your search to combine two datasets or later in your search where 
you can combine the incoming search results with a dataset. 
 

Specifying a dataset 
 

You can declare, or specify, a dataset several different ways. Here are some examples: 
 

	Type of 
declaration 
 


Description 
 


Example 
 

Dataset 
references 
 
Specifying an existing dataset that is defined in the 
Metadata Catalog. The datasets in this example are 
indexes. 
 

...| union main, customers, purchases 
 

Transient 
 

Specifying a SPL subsearch as the dataset. Subsearches 
are enclosed in square brackets. 
 
...| union [search main | stats count() by 
host ], [from customers | stats count() by 
host] 
 
Fluent 
 
The search results that are piped into the union command     ... <some search criteria> | union 
 
[<subsearch1>], [<subsearch2>] 
 

384 
 
	Type of 
declaration 
 
Description 
 
Example 
 
has a union command that contains one or more 
subsearches. 
 


Literal 
 

Using literal values that you type in as subsearches. Each 
subsearch is a dataset. This example shows three separate 
literal dataset declarations. 
 
...| union [ { "state": "Washington", 
"population": 39557045 } ], [ { "state": 
"California", "population": 753591 }, { 
"state": "Oregon", "population": 4190713 } ] 
 
Specifying a mixture of the types of declarations. 
 


Mixed 
 


This example begins with a fluent, contains a 
dataset reference <ds1>, includes a subsearch 
comprised of SPL syntax <subsearch1>, and then 
a subsearch comprised of literal values. 
 

... | <union ds1, [ <subsearch1> ], [ { 
"state": "Washington", "population": 39557045 
} ] 
 


Semantics 
 

If all of the datasets that are unioned together are streamable time-series, the union command attempts to interleave the 
data from all datasets into one globally sorted list of events or metrics. The list is based on the _time field in descending 
order. Otherwise, the union command returns all the rows from the first dataset, followed by all the rows from the second�h1h2h3}�h5Kuh�(h3h/�h}�ub�$ebcbcfb1-dbb7-4f35-a5c8-ca667479347a�h+)�}�(h}�(h/Xxorder. Otherwise, the union command returns all the rows from the first dataset, followed by all the rows from the second 
dataset, and so on. 
 

Interleaving results 
 

When two datasets are retrieved from disk in time descending order, which is the default sort order, the union command 
interleaves the results. The interleave is based on the _time field. For example, suppose you have the following datasets: 
 

dataset_A 
 

_time 
 

Host 
 

Bytes 
 
4 
 
mailsrv1 
 
2412 
 
1 
 
dns15 
 
231 
 
dataset_B 
 

_time 
 

Host 
 

Bytes 
 
3 
 
router1 
 
23 
 
2 
 
dns12 
 
22o 
 
Both datasets are descending order by _time. When | union dataset_A, dataset_B is run, the following dataset is the 
result. 
 

_time 
 

Host 
 

Bytes 
 
4 
 
mailsrv1 
 
2412 
 
3 
 
router1 
 
23 
 



385 
 
_time 
 
Host 
 
Bytes 
 
2 
 
dns12 
 
22o 
 
1 
 
dns15 
 
231 
 
See also 
 

union command 
 

union command syntax details 
union command examples 
 


union command examples 
 
The following are examples for using the SPL2 union command. To learn more about the union command, see How the 
union command works. 
 

1. Union events from multiple datasets 
 

The following example merges events from the customers and orders index datasets, and the vendors_lookup dataset. 
You must separate the dataset names with a comma. 
 

| union customers, orders, vendors_lookup 
 


You can also embed the union command in the from command by using a subsearch in the FROM clause expression: 
 

| FROM [union customers, orders, vendors_lookup] WHERE ... 
 

2. Union events from an incoming set of search results 
 

The following example merges events from incoming search results with an existing dataset. 
 

| from mysecurityview | fields _time, clientip | union customers 
 

3. Union the results of a subsearch to the results of the main search 
 

The following example appends the current results of the main search with the tabular results of errors from the 
subsearch. 
 

... | stats count() BY category1 | union [search error | stats count() BY category2] 
 

See also 
 

union command 
 

union command syntax details 
union command usage 
 




386�h1h2h3}�h5Kuh�(h3h/�h}�ub�$14cf0548-f420-4fb3-b282-cafe802c631b�h+)�}�(h}�(h/X%subsearch. 
 

... | stats count() BY category1 | union [search error | stats count() BY category2] 
 

See also 
 

union command 
 

union command syntax details 
union command usage 
 




386 
 
where command 
 


where command overview 
 
The where command uses <predicate-expressions> to filter search results. A predicate expression, when evaluated, 
returns either TRUE or FALSE. The where command only returns the results that evaluate to TRUE. 
 

The where command is identical to the WHERE clause in the from command. 
 

Syntax 
 

The required syntax is in bold. 
 

where <predicate-expression> 
 

How the where command works 
 

The where command acts as a filter on your search results. The where command takes the results from your search and 
removes all of the results that do not match the <predicate-expression> that you specify. 
 

With the where command, you must specify a <predicate-expression> that evaluates to TRUE. This can include an 
expression such as field=value. The following table shows a few examples: 
 

Example 
 

Description 
 

...| where name="maria" 
 
In this example, maria is a string literal. All strings must be enclosed in double quotation 
marks. 
 
...| where ipaddress="198.51.100.1"  The IP address is a string value. All strings must be enclosed in double quotation marks. 
 

...| where 'host-name'="buttercup" 
 
If the expression references a field name that contains characters other than a-z, A-Z, 0-9, or 
the underscore ( _ ) character, the field name must be surrounded by single quotation marks. 
 
...| where status in("400", "401", 
"403", "404") 
 
The expression can include a function. This example returns in=TRUE if one of the values in 
the status field matches one of the values in the list. 
 
In addition to field=value expressions, you can specify a mathematical expression, concatenation expression, 
comparison expression, as long as the expression evaluates to TRUE. 
 

For more information about expressions, see Types of expressions and Predicate expressions in the SPL2 Search 
Manual. 
 

See also�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c29b3af3-4959-4592-b194-535790b4befc�h+)�}�(h}�(h/XAcomparison expression, as long as the expression evaluates to TRUE. 
 

For more information about expressions, see Types of expressions and Predicate expressions in the SPL2 Search 
Manual. 
 

See also 
 

where command 
 

where command usage 
where command examples 
 

Other commands 
 




387 
 
Functions 
 



where command syntax details 
 
The required syntax is in bold. 
 

where <predicate-expression> 
 

Required arguments 
 

predicate-expression 
 

Description: An expression that, when evaluated, returns either TRUE or FALSE. 
 

The syntax of the <predicate-expression> is checked before running the search, and an exception is returned for 
an invalid expression. 
 

For more information, see Predicate expressions in the SPL2 Search Manual. 
 

See also 
 

where command 
 

where command usage 
where command examples 
 


where command usage 
 
The where command is identical to the WHERE clause in the from command. 
 

Typically you use the where command when you want to filter the result of an aggregation or a lookup. 
 

Using wildcards 
 

You can use wildcards to match characters in string values. With the where command, you must use the like function. 
 

• Use the percent ( % ) symbol as a wildcard for matching multiple characters 
• Use the underscore ( _ ) character as a wildcard to match a single character 
 

In this example, the where command returns search results for values in the ipaddress field that start with 198. 
 

... | where like(ipaddress, "198.%") 
 

See the like (<str>, <pattern>) function in the list of Comparison and Conditional eval functions. 
 





388 
 
Comparing two fields 
 

One advantage of the where command is that you can use it to compare two different fields. You cannot do that with the 
search command. Here are some examples: 
 

Command 
 

Example 
 

Description 
 

Where 
 
... | where 
foo=bar 
 

This search looks for events where the field foo is equal to the field bar. 
 

Where 
 

... | where 
foo='bar-baz' 
 
This search looks for events where the field foo is equal to the field bar-baz. Because the field�h1h2h3}�h5Kuh�(h3h/�h}�ub�$c263a598-aab9-4354-b8b4-1ea307ff2f34�h+)�}�(h}�(h/X0Where 
 

... | where 
foo='bar-baz' 
 
This search looks for events where the field foo is equal to the field bar-baz. Because the field 
bar-baz contains a character that is not a-z, A-Z, 0-9, or and underscore ( _ ), it must be enclosed in 
single quotation marks. 
 

Search 
 

search foo=bar 
 
The search command handles these expressions as a field=value pair. In this example, The 
bar is interpreted as a string value. 
 

Where 
 
... | where 
foo="bar" 
 

This search looks for events where the field foo contains the string value bar. 
 
Predicate expressions 
 

The order in which predicate expressions are evaluated with the where command is: 
 

1. Expressions within parentheses 
2. NOT clauses 
 

4. OR clauses 
 

The where command evaluation order is different than the evaluation order used with the search command. The search 
command evaluates OR clauses before AND clauses. 
 

Functions 
 

You can use a wide range of functions with the where command. See Overview of SPL2 eval functions. 
 

See also 
 

Where command 
 

where command syntax details 
where command examples 
 

Other commands 
 



where command examples 
 
The where command expects a predicate expression. See Predicate expressions in the SPL2 Search Manual. 
 

In most cases you can use the WHERE clause in the from command instead of using the where command separately. 
 



389 
 
1. Specify wildcards 
 

You can only specify a wildcard with the where command by using the like function. The percent ( % ) symbol is the 
wildcard you must use with the like function. 
 

In this example, the where command returns search results for values in the ipaddress field that start with 198.. 
 

... | where like(ipaddress, "198.%") 
 

The like function supports several syntaxes, see Comparison and Conditional functions. 
 

2. Match IP addresses or a subnet using the where command 
 

Return events that match the IP or is in the specified subnet. This example uses both the like function and the cidrmatch 
function. 
 

...| where like(src, "10.9.165.%") OR cidrmatch("10.9.165.0/25", dst)�h1h2h3}�h5Kuh�(h3h/�h}�ub�$3a903868-d3b1-4795-bf91-9f7c9e2b0b87�h+)�}�(h}�(h/X�
function. 
 

...| where like(src, "10.9.165.%") OR cidrmatch("10.9.165.0/25", dst) 
 

3. Specify a calculation in the where command expression 
 

Return events with a speed is greater than 100. 
 

... | where distance/time > 100 
 



See also 
 

where command 
 

where command syntax details 
where command usage 
 
























390 


---
ConversationHistory: {history}
---
MemoryContext: {context}
---
Human: {question}
Bot:�h1h2h3}�h5Kuh�(h3h/�h}�ubusb�index_to_docstore_id�}�(Kh(K
h8Kh@KhHKhPKhXKh`KhhKhpK	hxK
h�Kh�Kh�K
h�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kh�Kj
Kj
Kj
Kj
Kj 
Kj(
K j0
K!j8
K"j@
K#jH
K$jP
K%jX
K&j`
K'jh
K(jp
K)jx
K*j�
K+j�
K,j�
K-j�
K.j�
K/j�
K0j�
K1j�
K2j�
K3j�
K4j�
K5j�
K6j�
K7j�
K8j�
K9j�
K:jK;jK<jK=jK>j K?j(K@j0KAj8KBj@KCjHKDjPKEjXKFj`KGjhKHjpKIjxKJj�KKj�KLj�KMj�KNj�KOj�KPj�KQj�KRj�KSj�KTj�KUj�KVj�KWj�KXj�KYj�KZjK[jK\jK]jK^j K_j(K`j0Kaj8Kbj@KcjHKdjPKejXKfj`KgjhKhjpKijxKjj�Kkj�Klj�Kmj�Knj�Koj�Kpj�Kqj�Krj�Ksj�Ktj�Kuj�Kvj�Kwj�Kxj�Kyj�KzjK{jK|jK}jK~j Kj(K�j0K�j8K�j@K�jHK�jPK�jXK�j`K�jhK�jpK�jxK�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�jK�jK�jK�jK�j K�j(K�j0K�j8K�j@K�jHK�jPK�jXK�j`K�jhK�jpK�jxK�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�jK�jK�jK�jK�j K�j(K�j0K�j8K�j@K�jHK�jPK�jXK�j`K�jhK�jpK�jxK�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�jK�jK�jK�jK�j K�j(K�j0K�j8K�j@K�jHK�jPK�jXK�j`K�jhK�jpK�jxK�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�j�K�jK�jK�jK�jK�j K�j(M
j0M

j8M
j@M
jHM
jPM
jXM
j`M
jhM
jpM	
jxM

j�M
j�M
j�M

j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j�M
j	M
j	M
j	M
j	M
j 	M
j(	M 
j0	M!
j8	M"
j@	M#
jH	M$
jP	M%
jX	M&
j`	M'
jh	M(
jp	M)
jx	M*
j�	M+
j�	M,
j�	M-
j�	M.
j�	M/
j�	M0
j�	M1
j�	M2
j�	M3
j�	M4
j�	M5
j�	M6
j�	M7
j�	M8
j�	M9
j�	M:
j
M;
j
M<
j
M=
j
M>
j 
M?
j(
M@
j0
MA
j8
MB
j@
MC
jH
MD
jP
ME
jX
MF
j`
MG
jh
MH
jp
MI
jx
MJ
j�
MK
j�
ML
j�
MM
j�
MN
j�
MO
j�
MP
j�
MQ
j�
MR
j�
MS
j�
MT
j�
MU
j�
MV
j�
MW
j�
MX
j�
MY
j�
MZ
jM[
jM\
jM]
jM^
j M_
j(M`
j0Ma
j8Mb
j@Mc
jHMd
jPMe
jXMf
j`Mg
jhMh
jpMi
jxuub.