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.