Evaluate and manipulate fields with multiple values

About multivalue fields

A multivalue field is a field that contains more than one value. For example, events such as email logs often have multivalue fields in the To: and Cc: information.

Multivalue fields are parsed at search time, which enables you to process the values in the search pipeline. Search commands that work with multivalue fields include makemv, mvcombine, mvexpand, and nomv. The eval and where commands support functions, such as mvcount(), mvfilter(), mvindex(), and mvjoin() that you can use with multivalue fields. See Evaluation functions in the Search Reference and the examples in this topic.

You can also use the statistical eval functions, max and min, on multivalue fields. See Statistical eval functions in the Search Reference.

If you are using Splunk Enterprise, you can configure multivalue fields in the fields.conf file to specify how Splunk software detects more than one field value in a single extracted field value. Edit the fields.conf in $SPLUNK_HOME/etc/system/local/, or your own custom application directory in $SPLUNK_HOME/etc/apps/. For more information on how to do this, see Configure extractions of multivalue fields with fields.conf in the Knowledge Manager Manual.

If your search produces results, such as a table, the results get written to the results.csv.gz file. The contents of the results.csv.gz file include fields that begin with "__mv_". These fields are for internal use only and are used to encode multivalue fields.

For Splunk Cloud Platform, you must create a private app to configure multivalue fields. If you are a Splunk Cloud Platform administrator with experience creating private apps, see Manage private apps in your Splunk Cloud Platform deployment in the Splunk Cloud Platform Admin Manual. If you have not created private apps, contact your Splunk account representative for help with this customization.

Evaluate multivalue fields

One of the more common examples of multivalue fields is email address fields, which typically appear two or three times in a single sendmail event--one time for the sender, another time for the list of recipients, and possibly a third time for the list of Cc addresses.

Count the number of values in a field

Use the mvcount() function to count the number of values in a single value or multivalue field.

In this example, mvcount() 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.

Filter values from a multivalue field

Use the mvfilter() function to filter a multivalue field using an arbitrary Boolean expression. The mvfilter function works with only one field at a time.

In this example, mvfilter() keeps all of the values for the field email that end in .net or .org.

eventtype="sendmail" | eval email=mvfilter(match(email, "\.net$") OR match(email, "\.org$"))

Note: This example also uses the match() function to compare the pattern defined in quotes to the value of email. See Evaluation functions in the Search Reference.

Return a subset of values from a multivalue field

Use the mvindex() function to reference a specific value or a subset of values in a multivalue field. Since the index numbering starts at 0, if you want to reference the 3rd value of a field, you would specify it as 2.

In this example, mvindex() returns the first email address in the "To" field for every email sent by Sender:

eventtype="sendmail" from=Sender@* | eval to_first=mvindex(to,0)

If you want to see the top 3 email addresses that Sender writes to, use the following search.

eventtype="sendmail" from=Sender@* | eval top_three=mvindex(to,0,2)

In this example, top_three is, itself, a multivalue field.

Manipulate multivalue fields

Use nomv to convert a multivalue field into a single value

You can use the nomv command to convert values of the specified multivalue field into one single value. The nomv command overrides the multivalue field configurations that are set in fields.conf file.

In this example for sendmail events, you want to combine the values of the senders field into a single value.

eventtype="sendmail" | nomv senders

Use makemv to separate a multivalue field

You can use the makemv command to separate multivalue fields into multiple single value fields. In this example for sendmail search results, you want to separate the values of the senders field into multiple field values.

eventtype="sendmail" | makemv delim="," senders

After you separate the field values, you can pipe it through other commands. For example, you can display the top senders.

eventtype="sendmail" | makemv delim="," senders | top senders

Use mvexpand to create multiple events based on a multivalue field

You can use the mvexpand command to expand the values of a multivalue field into separate events for each value of the multivalue field. In this example, new events are created for each value in the multivalue field, "foo".

... | mvexpand foo

Use mvcombine to create a multivalue field from similar events

Combine the values of "foo" with ":" delimiter.

... | mvcombine delim=":" foo

See also

Configure extractions of multivalue fields with fields.conf in the Knowledge Manager Manual.