Splunk® Cloud Services

SPL2 Search Reference

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

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.

To use named arguments, you must specify the values in an array, enclosing the values in square brackets. The syntax for named arguments is mvappend(values: [<value>, <value>,...]. For example:

... mvappend(values:["localhost", srcip])

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 192.168.1.1 which is a literal IP address.

... | 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_scrip>, <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.

If the field contains a single value, this function returns 1. If the field has no values, this function returns NULL.

To use named arguments, you must specify the argument name before the argument value. For example:

...mvcount(mv:myfield)

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.

To use named arguments, you must specify the argument name before the argument value. For example:

...mvdedup(mv:myfield)

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(!isnull(x))
  • 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.

To use named arguments, you must specify the argument name before the argument value. For example:

...mvfilter(predicate:match(email, "\.net$") OR match(email, "\.org$"))

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

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.

To use named arguments, you must specify the argument name before the argument value. For example:

...mvfind(mv:myfield, regex:"err\d+")

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, that value is included in the results. If <end> argument is not specified, the function returns only the value at <start>.

Both the <start> and <end> arguments can be negative. An index of -1 is used to specify the last element in the list.

If the indexes are out of range or invalid, the result is NULL.

Specifying named arguments

To use named arguments, you must specify the argument names before the argument values. For example:

...mvindex(myfield, 2,-1)

Examples

Because indexes start at zero, the following example returns the third value in the myfield field, if the value exists.

... | eval n=mvindex(myfield, 2)

Extended example

The following search displays at most the last 10 values in the myfield field.

... | eval keep=mvindex(myfield,-1-10,-1)

The <start> argument is specified as a range. The range starts with the last value, -1 and counts backwards 10 values -1-10 in the field. The <end> argument is specified so that the last value in the field is included in the results. If the <end> argument is not specified the last value in the field is omitted from the results.

  • If the multivalue field has 20 values, only the last 10 values are returned.
  • If the multivalue field has 3 values, only 3 values are returned.

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.

To use named arguments, you must specify the argument names before the argument values. For example:

...mvjoin(myfield ";")

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

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)


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(results1,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.

To use named arguments, you must specify the argument names before the argument values. For example:

...mvrange(start:1, end:11, step:2)

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

See Lexicographical order.

To use named arguments, you must specify the argument name before the argument value. For example:

...mvsort(mv:myfield)

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.

The values are stitched together 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. The default delimiter is a comma ( , ).

To use named arguments, you must specify the argument names before the argument values. For example:

...mvzip(mv_left:field1, mv_right:field2, delim:"|")

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

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.

To use named arguments, you must specify the argument names before the argument values. For example:

...split(str:myfield, delim:";")

Example

... | eval n=split(myfield, ";")

See also

Functions
SPL2 eval functions Quick Reference
Overview of SPL2 eval functions
Last modified on 29 September, 2021
PREVIOUS
Mathematical functions
  NEXT
Statistical eval functions

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


Was this documentation topic helpful?

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