Splunk® Cloud Services

SPL2 Search Reference

Compatibility library for SPL commands as functions

Some of the SPL commands are not supported directly in SPL2 as commands. Instead, these SPL commands are included as a set of command functions in the SPL compatibility library system module.

You must first import the SPL command functions into your SPL2 module to use the functions. See Importing SPL command functions.

You use the SPL command functions in SPL2 searches in the same way you use the commands in SPL searches See Using SPL command functions.

Supported SPL commands as functions

The following list shows which SPL commands are supported as command functions in SPL2:

addinfo

append
appendcols
appendpipe
convert
fillnull
iplocation

loadjob

makemv
makeresults
mstats
mvcombine
nomv
replace


spath

table
tags
tstats
typer
untable

Some of the options or arguments used with the SPL commands are not supported with the command functions in SPL2. These exceptions are listed in the command function descriptions.

The following sections describes the SPL command functions that are included the SPL compatibility library system module:

addinfo

Description

Adds fields to each event that contain global, common information about the search.

Syntax

The required syntax is in bold.

addinfo

Usage

This command function expects events. You can't use this function after an SPL2 command or command function that returns summary information, such as the stats command.

The following fields are added to each event when you use the addinfo command function:

  • info_min_time. The earliest time boundary for the search, in UNIX time.
  • info_max_time. The latest time boundary for the search, in UNIX time.
  • info_search_time The time when the search was run, in UNIX time.
  • info_sid. The ID of the search that generated the event.

Example

The following example adds information about the search to each event.

from <dataset> ...| addinfo

append

Description

Appends the results of a subsearch to the current results. The subsearch must be enclosed in square brackets. This command function runs only over historical data and does not produce correct results if used in a real-time search.

Syntax

The required syntax is in bold.

append
[ <subsearch> ]

Required parameters

subsearch
Syntax: [search <subsearch_criteria>]
Description: A search within a primary, or outer, search. The subsearch is run first. Subsearches must be enclosed in square brackets.

Usage

This SPL2 command function does not support the following <subsearch-options>, which are used with the SPL append command:

  • extendtimerange=<boolean>
  • maxtime=<int>
  • maxout=<int>
  • timeout=<int>

Example

The following search looks for events that are purchase actions and appends the results of the top IP addresses by category ID to the current results.

The top command is not supported in SPL2 as either a command or a command function. The subsearch in the append command function uses a search literal to include top command in the search.

from <dataset> | where action="purchase" | sort clientip | stats dc(clientip) BY categoryId | append [search action="purchase" | `top 1 clientip BY categoryId`]

appendcols

Description

Appends all of the fields of the subsearch results with the incoming search results, except for internal fields.

For example, the first subsearch result is merged with the first main search result, the second subsearch result is merged with the second main search result, and so on.

Syntax

The required syntax is in bold.

appendcols
[ <subsearch> ]

Required parameters

subsearch
Syntax: [search <subsearch_criteria>]
Description: A search within a primary, or outer, search. The subsearch is run first. Subsearches must be enclosed in square brackets.

Usage

This SPL2 command function does not support the following arguments, which are used with the SPL appendcols command:

  • override
  • maxtime
  • maxout
  • timeout

Example

The following example searches for "404" events and appends the fields in each event to the list of host values returned from the incoming search results.

from main | fields host | appendcols [search 404]

appendpipe

Description

Appends the result of the subpipe to the search results. Unlike a subsearch, the subpipe is not run first. The subpipe is run when the search reaches the appendpipe command function.

Use the appendpipe command function after transforming commands, such as timechart and stats.

Syntax

The required syntax is in bold.

appendpipe
run_in_preview=<boolean>
[<subpipe>]

Required parameters

subpipe
Syntax: [<command> | <command> ...]
Description: A series of commands that are applied to the search results that are piped into the appendpipe command. The subpipe must be enclosed in square brackets.

Optional parameters

run_in_preview
Syntax: run_in_preview=<boolean>
Description: Specifies whether or not to display the impact of the appendpipe command function while the search is running. When set to false, the impact of the function on the search results appears only after the search has finished running.
Default: true

Usage

The appendpipe command function can be useful when you are constructing a table or chart because it provides a summary, total, or otherwise descriptive row for each component of the result set. This command is also useful when you need the original results for additional calculations.

Example

The following example append subtotals for each action across all users.

from sample_events | stats count() AS user_count BY action, clientip | appendpipe [stats sum(user_count) AS 'User Count' BY action | eval user = "TOTAL - USER COUNT"] | sort action

The results look something like this:

action clientip user_count User Count user
addtocart 107.1.146.207 15 NULL NULL
addtocart 108.65.113.83 16 NULL NULL
addtocart 109.169.32.135 3 NULL NULL
addtocart NULL NULL 34 TOTAL - USER COUNT
changequantity 107.1.146.207 2 NULL NULL
changequantity 108.65.113.83 1 NULL NULL
changequantity 109.169.32.135 2 NULL NULL
changequantity NULL NULL 4 TOTAL - USER COUNT

convert

Description

Converts field values in your search results into numerical values.

Syntax

The required syntax is in bold.

| convert
[ timeformat ]
<convert-function>
[ AS <field> ]

Required parameters

Convert_function
Specify one of the supported convert functions. You can use the AS clause to create a field to place the new values in. The convert functions are:
auto() | ctime() | dur2sec() | memk() | mktime() | mstime() | none() | num() | rmcomma() | rmunit()
auto()
Syntax: auto(<wc-field>)
Description: Automatically converts field values to numbers, using the best conversion data type. If some of the values in a field can't be converted using a known conversion type, none of the field values are converted. You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert auto(time_elapsed) AS elapsed

Example:

... | convert auto(*)

Example:

... | convert auto(host*)

ctime()
Syntax: ctime(<wc-field>) [AS <field_name>]
Description: Convert an epoch time to an ascii human readable time. Use the timeformat option to specify exact format to convert to. You can use a wildcard ( * ) character to specify all fields.
Example:

... | convert timeformat="%H:%M:%S" ctime(_time)

Example:

... | convert timeformat="%H:%M:%S" ctime(_time) AS c_time

dur2sec()
Syntax: dur2sec(<wc-field>) [AS <field_name>]
Description: Convert a duration format "[D+]HH:MM:SS" to seconds. For example, if delay="00:10:15", the resulting value is delay="615".You can use a wildcard ( * ) character to specify all fields.
Example:

... | convert dur2sec(xdelay), dur2sec(delay)

Example:

... | convert dur2sec(delay*)

Example:

... | convert dur2sec(elapsed_time) AS 'Elapsed-time'

memk()
Syntax: memk(<wc-field>) [AS <field_name>]
Description: Accepts a positive number (integer or float) followed by an optional "k", "m", or "g". The letter k indicates kilobytes, m indicates megabytes, and g indicates gigabytes. If no letter is specified, kilobytes is assumed. The output field is a number expressing quantity of kilobytes. Negative values cause data incoherency. You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert memk(bytes)

Example:

... | convert memk(bytes) AS kilo_bytes

mktime()
Syntax: mktime(<wc-field>) [AS <field_name>]
Description: Convert a human readable time string to an epoch time. Use timeformat option to specify exact format to convert from. You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert timeformat="%H:%M:%S" mktime(_time)

Example:

... | convert timeformat="%H:%M:%S" mktime(_time) AS mk_time

mstime()
Syntax: mstime(<wc-field>) [AS <field_name>]
Description: Convert a [MM:]SS.SSS format to seconds. You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert mstime(elapsed_*)

Example:

... | convert mstime(elapsed_time) AS ms_time

none()
Syntax: none(<wc-field>) [AS <field_name>]
Description: In the presence of other conversion functions, indicates that the matching fields should not be converted. You can use a wildcard ( * ) character to specify all fields.
Example:

... | convert auto(*) none(src_ip)

num()
Syntax: num(<wc-field>) [AS <field_name>]
Description: Like auto(), except non-convertible values are removed. You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert num(*)

Example:

... | convert num(bytes)

rmcomma()
Syntax: rmcomma(<wc-field>) [AS <field_name>]
Description: Removes all commas from value. For example, rmcomma(1,000,000.00) returns 1000000.00. You can use a wildcard ( * ) character to specify all fields or fields with similar names
Example:

... | convert rmcomma(sales)

Example:

... | convert rmcomma(emeasales) AS 'Sales in EMEA'

rmunit()
Syntax: rmunit(<wc-field>) [AS <field_name>]
Description: Looks for numbers at the beginning of the value and removes trailing text. For example, if duration="212 sec", the resulting value is duration="212". You can use a wildcard ( * ) character to specify all fields or fields with similar names.
Example:

... | convert rmunit(duration)

Example:

... | convert rmunit(duration*)

Optional parameters

<field>
Syntax: AS <string>
Description: Creates a new field with the name you specify to place the converted values into. The original field and values remain intact.
timeformat
Syntax: timeformat=<string>
Description: Specify the output format for the converted time field. The timeformat option is used by ctime and mktime functions. For a list and descriptions of format options, see Using time variables in the SPL2 Search Manual.
Default: %m/%d/%Y %H:%M:%S. Note that this default does not conform to the locale settings.

Usage

You can also use the strftime(), strptime(), or tonumber() functions to convert field values.

Examples

The following example changes the duration values to seconds for the specified fields.

... | convert dur2sec(xdelay), dur2sec(delay)

The following example converts a time in MM:SS.SSS (minutes, seconds, and subseconds) format to a number in seconds. The mstime() function changes the timestamp to a numerical value. This is useful to perform calculations on timestamps.

... | convert mstime(_time) AS ms_time | select _time, ms_time

For additional examples see the individual convert functions.

fillnull

Description

Replaces null values with a specified string value. Null values are field values that are missing in a result but present in another result.

You can specify a string to fill the null field values or use the default field value, which is zero ( 0 ).

Syntax

The required syntax is in bold.

fillnull
[value="<string>"]
[<field-list>]

Required parameters

None

Optional arguments

field-list
Syntax: <field>, ...
Description: A comma-separated list of one or more field names. If you specify a field list, all of the fields in that list are filled in with the value you specify. If you specify a field that didn't previously exist, the field is created. If you do not specify a field list, the value is applied to all fields.
value
Syntax: value="<string>"
Description: A string value to replace the null values. The value must be in double quotation marks. The value can't be a field name. If you do not specify a value, the default value is applied to the <field-list>.
Default: 0

Examples

The following example fills all empty field values with the default value, 0:

...| fillnull

The following example fills all of the empty field values with the string NULL:

... | fillnull value="NULL"

The following example fills all empty field values in the host and kbps fields with the string unknown:

... | fillnull value="unknown" host, kbps

iplocation

Description

Extracts location information from IP addresses by using 3rd-party databases. Supports IPv4 and IPv6 addresses and subnets that use CIDR notation.

Syntax

The required syntax is in bold.

iplocation
<field>

Required parameters

field
Syntax: <field>
Description: The name of the field in the events that contains the IP address.

Usage

The IP address that you specify in the <field> parameter is looked up in a database. Fields from that database that contain location information are added to each event. The fields added are:

  • City
  • Country
  • Region
  • lat (latitude)
  • lon (longitude)

Because all the information might not be available in the database for each IP address, some fields can have empty field values.

For IP addresses which do not have a location, such as internal addresses, no fields are added.

Examples

The following example adds information about the IP address to each event:

...| iplocation clientip

The following example add information about the IP address to each event. This example uses the select command to display only certain fields in the search results:

...| iplocation clientip | select _time, ipaddress, Country, Region, City

loadjob

Description

Loads the results of a previously completed search job, based on the search job ID <sid>. Must be specified at the beginning of a search.

Syntax

The required syntax is in bold.

loadjob
sid

Required parameters

sid
Syntax: <job_ID>
Description: The search job ID.

Usage

This SPL2 command function does not support loading saved searches.

This SPL2 command function does not support the following arguments, which are used with the SPL loadjob command:

  • result_event
  • delegate
  • artifact_offset
  • ignore_running

Example

The following example specifies the search ID for the search results that you want to load into a new search.

| loadjob 1233886270.2

makemv

Description

Converts a single value field into a multivalue field by splitting the values either on a string delimiter or by using a regular expression. You can't use this function on internal fields.

Syntax

The required syntax is in bold.

makemv
[ delim = <delimiter> ]
[ tokenizer = <tokenizer> ]
<field>

Required parameters

field
Syntax: <field>
Description: The name of the field to generate the multivalues from.

Optional parameters

delim
Syntax: delim=<string>
Description: A string value used as a delimiter. Splits the values in field on every occurrence of this delimiter. Multicharacter delimiters are supported.
Default: A single space (" ").
tokenizer
Syntax: tokenizer=<string>
Description: A regular expression with a capturing group that is repeat-matched against the values in the field. For each match, the first capturing group is used as a value in the newly created multivalue field.
Default: None

Usage

This SPL2 command function does not support the following arguments, which are used with the SPL makemv command:

  • allowempty=<bool>
  • setsv=<bool>

Examples

The following example separates values in the senders field using a comma ( , ) as the delimiter:

... | makemv delim="," senders

The following example separates the values in the my_multival field using a regular expression.

... | makemv tokenizer="([^,]+),?" my_multival

makeresults

Description

Generate the specified number of search results in temporary memory. The results include the _time field. If you don't specify count, one result is generated.

Syntax

The required syntax is in bold.

makeresults
<count>

Examples

The following example generates 5 identical events, each with the same timestamp:

| makeresults 5

The following example creates a series of events with different timestamp hours by using the streamstats and eval commands. 3600, the number of seconds in an hour, by using the eval command:

| makeresults count=5 | streamstats count | eval _time=_time-(count*3600)

mstats

Description

Analyzes metric data by performing statistics on the measurement, metric_name, and dimension fields in metric indexes. You can use mstats in historical searches and real-time searches. When you use mstats in a real-time search with a time window, a historical search runs first to backfill the data.

The mstats command provides the best search performance when you use it to search a single or small number of metric_name values.

Syntax

The syntax for the SPL2 mstats command function is different, but with similar capabilities, than the SPL mstats command.

The required syntax is in bold.

| mstats
aggregates=[<function-expression, ...>]
predicate=(<predicate-expression>)
byfields=[<field>...]

Required parameters

aggregates
Syntax: aggregates=[<function-expression, ...>]
Description: One or more function expressions using the supported statistical functions. See Quick Reference for SPL2 Stats and Charting Functions. Separate multiple function expressions with commas. You must enclose the list of function expressions in square brackets [ ].

Optional parameters

predicate
Syntax: predicate=(<predicate-expression>...)
Description: One or more predicate expressions. Use logical operators, such as AND or OR, to separate multiple predicate expressions. See Predicate expressions in the SPL2 Search Manual. The <predicate-expression> must be enclosed in parentheses ( ).

If no indexes are specified in the predicate, all of the indexes that you have access to in your module are searched.

Default: All of the indexes you have access to in your module.
byfields
Syntax: byfields=[<field>, ...]
Description: A comma-separated list of one or more field names to group the results by. You must enclose the field names in square brackets [ ]. You cannot use wildcards in the field names.
Default: None

Usage

In SPL2, metric names that contain one or more period ( . ) characters must be enclosed in single quotation marks.

This SPL2 command function does not support the following arguments that are used with the SPL mstats command:

[chart=<bool>]
[<chart-options>]
[prestats=<bool>]
[append=<bool>]
[backfill=<bool>]
[update_period=<integer>]
[fillnull_value=<string>]
[chunk_size=<unsigned int>]
[<span-length>]

In SPL2, use the bin command as an alternative to the SPL <span_length> argument.

Examples

The following example shows how to calculate a single metric grouped by time. This example returns the average value of the aws.ec2.CPUUtilization metric in the mymetricdata metric index. Use the bin command to bucket the results into 30 second time spans.

| mstats aggregates=[avg('aws.ec2.CPUUtilization')] predicate=(index=mymetricdata) | bin span=30s


The following example combines metrics with different metric names. This example returns the average value of both the aws.ec2.CPUUtilization and os.cpu.utilization metrics. Group the results by host. Use the bin command to bucket the results into 1 minute time spans. Both metrics are combined and considered a single metric series.

| mstats aggregates=[avg('aws.ec2.CPUUtilization'), avg('os.cpu.utilization')] predicate=(index=mymetricdata) byfields=[host] | bin span=1m


The following example filters the results on a dimension value and splits by the values of another dimension. This example returns the average value of the aws.ec2.CPUUtilization metric for all measurements with host=www2. The results are groupedby the values of the app dimension.

| mstats aggregates=[avg('aws.ec2.CPUUtilization')] predicate=(host=www2) byfields=[app]


The following example specifies multiple aggregations of multiple metrics. This example returns the average and maximum of the resident set size and virtual memory size. The results are grouped by the metric_name. The bin command is used to bucket the results into 1 minute spans.

| mstats aggregates=[avg('os.mem.rss') AS "AverageRSS", max('os.mem.rss') AS "MaxRSS", avg('os.mem.vsz') AS "AverageVMS", max('os.mem.vsz') AS "MaxVMS"] predicates=(index=mymetricdata) byfields=[metric_name] | bin span=1m


The following example calculates the rate of an accumulating counter metric and groups the results by time series. See Perform statistical calculations on metric time series in Metrics for more information.

| mstats aggregates=[rate('spl.intr.resource_usage.PerProcess.data.elapsed') as 'data.elapsed'] predicate=(index=_metrics) byfields=[_timeseries] | rename _timeseries AS timeseries


The following example returns a count of all of the measurements for the aws.ec2.CPUUtilization metric in the mymetricdata index.

| mstats aggregates=[count(_value)] predicate=(index=mymetricdata AND metric_name="aws.ec2.CPUUtilization")

mvcombine

Description

Takes a group of events that are identical except for the specified field, which contains a single value, and combines those events into a single event. The specified field becomes a multivalue field that contains all of the single values from the combined events.

The mvcombine command function is most useful after you reduce the set of available fields by using the stats, select, or fields command.

Syntax

The required syntax is in bold.

mvcombine
[delim=<string>]
<field>

Required parameters

field
Syntax: <field>
Description: The name of the field to generate the multivalues from.

Optional parameters

delim=<string>
Description: A string value used as a delimiter.
Default: A single space (" ").

Usage

The SPL2 mvcombine command function does not apply to internal fields.

Examples

The following example creates a multivalue field from the values in the host field by using the comma as a delimiter:

... | mvcombine delim="," host

The following example returns a flat string of results with the delimiters, convert the field into single value string by adding the nomv command function to your search:

... | mvcombine delim="," host | nomv host

The following example uses the stats command to summarize the data and the mvcombine command function to return a multivalue field for the host values.

... | stats max(bytes) AS max, min(bytes) AS min BY host | mvcombine host

nomv

Description

Converts values of the specified multivalue field into one single value. Separates the values using a new line ( "\n ) delimiter.

Syntax

The required syntax is in bold.

nomv
<field>

Required parameters

field
Syntax: <field>
Description: The name of the multivalue field to convert.

Examples

The following example combines the values in the senders field into a single value.

from main where eventtype="sendmail" | nomv senders

replace

Description

Replaces field values in your search results with the values that you specify. Does not replace values in fields generated by stats or eval functions. If you do not specify a field, the value is replaced in all non-generated fields.

Syntax

The required syntax is in bold.

replace
str=<value>
replacement=<value>
[<field-list>]

Required parameters

str
Syntax: str=<value>
Description: A field value that you want to replace. You can use the asterisk ( * ) wildcard character to match similar values.
replacement
Syntax: replacement=<value>
Description: A replacement value. You can use the asterisk ( * ) wildcard character to match similar values.

Optional parameters

field-list
Syntax: <field>, ...
Description: A comma-separated list of one or more field names to replace the values in.

Examples

The following example replaces a value in all of the fields in the search results. Any value in any field that ends with localhost is replaced with simply localhost.

... | replace str="*localhost" replacement="localhost"

The following example replaces a value in a specific field. The IP address is replaced with a more descriptive name in the host field.

... | replace str="127.0.0.1" replacement="localhost" host

The following example changes a value in two fields, the start_month and end_month fields.

... | replace str="aug" replacement="August" start_month, end_month

You can change the order of values in a field by using wildcards. The following example changes the order of string values that contain the word localhost so that the string "localhost" precedes the other strings in the host field.

... | replace str="* localhost" replacement="localhost *" host

You can replace fields that contain empty string values with a value. The following example replaces empty strings with "None" in the errmsg field.

... | replace str="" replacement="None" errmsg

This example will not work unless you have values that are actually the empty string, which is not the same as not having a value.

spath

Description

Extracts information from the XML and JSON structured data formats.

Syntax

The required syntax is in bold.

spath
[input=<field>]
[output=<field>]
[path="<path>"]

Required parameters

None

Optional parameters

input
Syntax: <field>
Description: The field to read in and extract values from.
Default: _raw
output
Syntax: <field>
Description: The value extracted from the <path> is written to this field name.
Default: The value for the <path> becomes the field name for the extracted value.
path
Syntax: "<path>"
Description: The location path to the value that you want to extract, expressed in dot ( . ) notation. The path must be enclosed in quotation marks.
A location path is composed of one or more location steps, separated by periods. An example of this is 'emea.europe.pl'. A location step is composed of a field name and an optional index surrounded by curly brackets. The index can be an integer, to refer to the position of the data in an array (this differs between JSON and XML), or a string, to refer to an XML attribute. If the index refers to an XML attribute, specify the attribute name with an @ symbol.
Default: None

Examples

The following example shows how to specify an output field and path:

... | spath output=myfield path="server.name"

The following example shows how to specify an output field and path with a wildcard for JSON data:

... | spath output=commit_author path="commits{}.author.name"

The following example shows how to extract the value of the locale attribute in XML data. Because the output field name contains a special character, a period ( . ), the field name must be enclosed in quotation marks.

... | spath output="locDesc.locale" path="vendorProductSet.product.desc.locDesc{@locale}"

table

Description

Returns a table that is formed from the fields that you specify. Columns are displayed in the same order that fields are specified.

Syntax

The required syntax is in bold.

table
<field-list>

Required parameters

field-list
Syntax: <field>, ...
Description: A comma-separated list of one or more field names. Use a wildcard ( * ) to specify multiple fields with similar names and enclose the name in quotation marks, for example "source*".

Examples

The following example returns a table with only the host and action fields.

...| table host, action

The following example return a table with only the host and action fields, and any field that begins with "source".

...| table host, action, "source*"

tags

Description

Adds fields to your search results with information about the tags found for those results. To use this command function, the tags must already exist.

Syntax

The required syntax is in bold.

tags
[allowed_fields=[<field-list>] ]
[<outputfield>=<field>]
[<inclname>=<boolean>]
[<inclvalue>=<boolean>]
[<field-list>]

Required parameters

None

Optional parameters

allowed_tags
Syntax: allowed_tags=[<field-list>]
Description: A comma-separated list of the tags to return. You must enclose the list in square brackets.
Default: All tags
field-list
Syntax: field, ...
Description: A comma-separated list of one or more field names that you want to return the associated tags information for. The field list must appear after the other parameters. If not specified, the tag information for all fields is returned.
Default: All fields
inclname
Syntax: inclname=<boolean>
Description: Valid only if outputfield is specified. Specifies if the event field name is included in the output field, along with the tag names. Specify true to include the field name. For example, if the field that the tag is associated with is ipaddress and the tag is main_office the results in the output field shows ipaddress::main_office
Default: false
inclvalue
Syntax: inclvalue=<boolean>
Description: Valid only if outputfield is specified. Specifies if the event field value is included in the output field, along with the tag names. Specify true to include the event field value.
Default: false
outputfield
Syntax: outputfield=<field>
Description: The name of a single field to write all of the tag names to. If not specified, a new field is created for each field that has tags associated with that field. The tag names are written to these new fields using the naming convention tag_name::<field>. In addition, a new field is created called tags that lists all of the tag names in all of the fields.
Default: A new field is created for each field that has tags associated with that field.

Usage

If you do not specify which fields you want to identify tags for, this command function looks for tags associated with all of the fields.

The field list must appear after the other parameters.

Examples

The following example creates a field called mytags and returns the tags for only the host and clientip fields. The tag information will include the field name. The field list must appear after the other parameters.

...| tags outputfield=mytags inclname=true host, clientip

The following example returns only information about the tags error and group that are associated with any field. This example places the tag information, including the field name and value, in a field called teamtags.

...| tags allowed_tags=[error, group] outputfield=teamtags inclname=true inclvalue=true

tstats

Description

Performs searches on indexed fields in tsidx files using statistical functions. The indexed fields can be from indexed data or accelerated data models.

Syntax

The syntax for the SPL2 tstats command function is different, but with similar capabilities, than the SPL tstats command.

The required syntax is in bold.

| tstats
aggregates=[<function-expression, ...>]
datamodel_name='<data_model_name>.<root_dataset_name>'
predicate=(<predicate-expression>)
byfields=[<field>...]

Required parameters

aggregates
Syntax: aggregates=[<function-expression, ...>]
Description: One or more function expression from the list of supported statistical functions. See Quick Reference for SPL2 Stats and Charting Functions. Separate multiple function expressions with commas. You must enclose the <function-expression> in square brackets [ ].

Optional parameters

datamodel_name
Syntax: datamodel_name='<data_model_name>.<root_dataset_name>'
Description: The name of the data model and the root dataset name. Names with special characters, such as periods or dashes, must be enclosed in single quotation marks. Specify node names in the predicate parameter. For example: nodename = '<root_dataset_name>.<...>.<target_dataset_name>'.
Default: None
predicate
Syntax: predicate=(<predicate-expression>...)
Description: One or more predicate expressions. Use logical operators, such as AND or OR, to separate multiple predicate expressions. See Predicate expressions in the SPL2 Search Manual. The <predicate-expression> must be enclosed in parentheses ( ).

If no indexes are specified in the predicate, all of the indexes that you have access to in your module are searched.

Default: All indexes you have access to in your module.
byfields
Syntax: byfields=[<field>, ...]
Description: A comma-separated list of one or more field names to group the results by. You must enclose the field names in square brackets [ ]. You cannot use wildcards in the field names.
Default: None

Usage

Because only index-time fields are search instead of raw events, the SPL2 tstats command function is faster than the stats command.

By default, the SPL2 tstats command function runs over accelerated and unaccelerated data models.

This SPL2 command function does not support the following arguments that are used with the SPL tstats command:

[prestats=<bool>]
[local=<bool>]
[append=<bool>]
[summariesonly=<bool>]
[include_reduced_buckets=<bool>]
[allow_old_summaries=<bool>]
[chunk_size=<unsigned int>]
[fillnull_value=<string>]

Examples

The following example specifies only the required parameters. Aggregates must be enclosed in square brackets [ ]. However, because no indexes are specified, the search performs a count of all of the indexes in the module.

| tstats aggregates=[count()]

The following example shows that you can rename the aggregate using the AS keyword:

| tstats aggregates=[min(_time) AS min] predicate=(index=myindex)

The following example specifies an aggregate and a data model. Because there is a period between the data module name and the root dataset name, the datamodel_name value must be enclosed in single quotation marks:

| tstats aggregates=[count()] datamodel_name='NetworkTraffic.emea'

The following example shows how to specify the target dataset name in the predicate in a data model:

| tstats aggregates=[count()] predicate=(nodename='emea.eur.poland') datamodel_name='NetworkTraffic.emea'

The following example shows how to specify multiple predicates using the AND logical operator:

| tstats aggregates=[avg(bytes)] predicate=(index=sample_events AND host="www3")

The following example shows how to specify a byfields value, which must be enclosed in square brackets [ ]:

| tstats aggregates=[count()] predicate=(status IN("400", "404", "503")) byfields=[host]

The following example shows how to specify multiple aggregates in the tstats command function. This example also shows that you can use SPL command functions with SPL2 commands, in this case the eval command:

| tstats aggregates=[min(_time) AS min, max(_time) AS max] datamodel_name='Buttercup_Games.Sales' | eval prettymin=strftime(min, "%c") | eval prettymax=strftime(max, "%c")

typer

Description

Creates an eventtype field in for search results that match known event types. The event types must already exist to use this command function.

Syntax

The required syntax is in bold.

typer
[eventtypes=<string>, ...]
[maxlen=<integer>]

Required parameters

None

Optional parameters

eventtypes
Syntax: eventtypes=<string-list>
Description: A comma-separated list of the event types for the events that you want returned. The names of the event types must be enclosed in quotation marks.
Default: Returns all associated event types
maxlen
Syntax: maxlen=<integer>
Description: The maximum number of characters to search an event for to determine the event type.
Default: 10000 characters

Examples

The following example returns a field called eventtype which contains the names of the event types associated with the search results.

... | typer

The following example returns only events with the successful purchases event type and limits the number of characters to search each event to 300.

...| typer eventypes="successful purchases" maxlen=300

untable

Description

Converts tabular information into individual rows of results.

Syntax

The required syntax is in bold.

untable
<xname>
<yname>
<ydata>

Required arguments

<xname>
Syntax: <field>
Description: The field in the search results to use for the x-axis labels or row names. This is the first field in the output.
<yname>
Syntax: <string>
Description: The name for a new field to contain the labels for the data series. You can specify any name for this field. All of the field names, other than <xname>, are used as the values for the <yname> field.
<ydata>
Syntax: <string>
Description: The name for a new field to contain the data to chart. You can specify any name for this field. All of the values from the fields, other than <xname>, are used as the values for the <ydata> field.

Examples

The following search returns a count of the event organized by the host and status fields.

from sample_events where status=200 | stats count() by host, status

The results look like this:

host status count
www1 200 42
www2 200 46
www3 200 51
www4 200 39

The following example adds the untable command function and converts the results from the stats command. The host field becomes row labels. The count and status field names become values in the labels field. The values from the count and status fields become the values in the data field.

from sample_events where status=200 | stats count() by host, status | untable host, label, data

The results look like this:

host label data
www1 count 42
www1 status 200
www2 count 51
www2 status 200
www3 count 42
www3 status 200
www4 count 51
www4 status 200

See also

Related information
Importing SPL command functions
Using SPL command functions
Last modified on 08 February, 2024
Compatibility Quick Reference for SPL2 evaluation functions   Importing SPL command functions

This documentation applies to the following versions of Splunk® Cloud Services: current


Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters