Splunk® Enterprise

Search Reference

Acrobat logo Download manual as PDF


Splunk Enterprise version 7.1 is no longer supported as of October 31, 2020. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
Acrobat logo Download topic as PDF

format

Description

This command is used implicitly by subsearches. This command takes the results of a subsearch, formats the results into a single result and places that result into a new field called search.

The format command performs similar functions as the return command.

Syntax

The required syntax is in bold.

format
[mvsep="<mv separator>"]
[maxresults=<int>]
["<row prefix>" "<column prefix>" "<column separator>" "<column end>" "<row separator>" "<row end>"]
[emptystr="<string>"]

If you want to specify a row or column options, you must specify all of the row and column options.

Required arguments

None.

Optional arguments

mvsep
Syntax: mvsep="<string>"
Description: The separator to use for multivalue fields.
Default: OR
maxresults
Syntax: maxresults=<int>
Description: The maximum results to return.
Default: 0, which means no limitation on the number of results returned.
<row prefix>
Syntax: "<string>"
Description: The value to use for the row prefix.
Default: The open parenthesis character "("
<column prefix>
Syntax: "<string>"
Description: The value to use for the column prefix.
Default: The open parenthesis character "("
<column separator>
Syntax: "<string>"
Description: The value to use for the column separator.
Default: AND
<column end>
Syntax: "<string>"
Description: The value to use for the column end.
Default: The close parenthesis character ")"
<row separator>
Syntax: "<string>"
Description: The value to use for the row separator.
Default: OR
<row end>
Syntax: "<string>"
Description: The value to use for the column end.
Default: The close parenthesis character ")"
emptystr
Syntax: emptystr="<string>"
Description: The value that the format command outputs instead of the default empty string NOT( ) if the results generated up to that point are empty and no fields or values other than internal fields are returned. You can set this argument to a custom string that is displayed instead of the default empty string whenever your search results are empty.
Default: NOT( )

Usage

By default, when you do not specify any of the optional row and column arguments, the output of the format command defaults to: "(" "(" "AND" ")" "OR" ")".

Specifying row and column arguments

There are several reasons to specify the row and column arguments:

Subsearches
There is an implicit format at the end of a subsearch that uses the default values for column and row arguments. For example, you can specify OR for the column separator by including the format command at the end of the subsearch.
Export the search to a different system
Specify the row and column arguments when you need to export the search to another system that requires different formatting.

Examples

1. Example with no optional parameters

Suppose that you have results that look like this:

source sourcetype host
syslog.log syslog my_laptop
bob-syslog.log syslog bobs_laptop
laura-syslog.log syslog lauras_laptop

The following search returns the top 2 results, and creates a search based on the host, source, and sourcetype fields. The default format settings are used.

... | head 2 | fields source, sourcetype, host | format

This search returns the syntax for a search that is based on the field values in the top 2 results. The syntax is placed into a new field called search.

source sourcetype host search
( ( host="mylaptop" AND source="syslog.log" AND sourcetype="syslog" ) OR ( host="bobslaptop" AND source="bob-syslog.log" AND sourcetype="syslog" ) )

2. Example using the optional parameters

You want to produce output that is formatted to use on an external system.

... | format "[" "[" "&&" "]" "||" "]"

Using the data in Example 1, the result is:

source sourcetype host search
[ [ host="mylaptop" && source="syslog.log" && sourcetype="syslog" ] | | [ host="bobslaptop" && source="bob-syslog.log" && sourcetype="syslog" ] ]

3. Multivalue separator example

The following search uses the eval command to create a field called "foo" that contains one value "eventtype,log_level". The makemv command is used to make the foo field a mulitvalue field and specifies the comma as the delimiter between the values. The search then outputs only the foo field and formats that field.

index=_internal |head 1 |eval foo="eventtype,log_level" | makemv delim="," foo | fields foo | format mvsep="mvseparator" "{" "[" "AND" "]" "AND" "}"

This results in the following output:

foo search
{ [ ( foo="eventtype" mvseparator foo="log_level" ) ] }

4. Use emptystr to indicate empty results

When a search generates empty results, the format command returns internal fields and the contents of emptystr. You can change the value of emptystr from the default to a custom string. For example, the results in the following search are empty, so format returns a customized string "Error Found" in a new field called search.

| makeresults count=1 | format emptystr="Error Found"

The results look something like this.

search
Error Found

If your search doesn't include emptystr like the following example, the format command displays the default empty string to indicate that the results are empty.

| makeresults count=1 | format

The results look something like this.

search
NOT ( )

5. Use emptystr in a subsearch as a failsafe

Customizing your empty string as shown in the last example is one way to use emptystr. However, it is more typical to use the format command as a subsearch that is operating as a search filter, and then use emptystr as a failsafe in case your search returns empty results. For example, perhaps your index isn't generating results because one of the fields you're specifying in the subsearch doesn't exist or there's a typo or some other error in your search. You can include the emptystr argument and set it to a default source type that you know is always present, such as splunkd. Then, instead of returning nothing, your search will return some results that you can use for further filtering.

You can use the following sample search to make sure you get results even if your search contains errors.

index=_internal sourcetype= [search index=does_not_exist | head 1 | fields sourcetype | format emptystr="splunkd"]

The results look something like this.

i Time Event
> 11/16/21

3:11:33.745 PM

11-16-2021 15:11:33.745 -0800 INFO Metrics - group=thruput, name=thruput, instantaneous_kbps=4.984, instantaneous_eps=20.935, average_kbps=1.667, total_k_processed=182447.000, kb=154.505, ev=649

host = PF32198Dsource = C:\Program Files\Splunk\var\log\splunk\metrics.logsourcetype = splunkd

> 11/16/21

3:11:33.745 PM

11-16-2021 15:11:33.745 -0800 INFO Metrics - group=thruput, name=syslog_output, instantaneous_kbps=0.000, instantaneous_eps=0.000, average_kbps=0.000, total_k_processed=0.000, kb=0.000, ev=0 host = PF32198Dsource = C:\Program Files\Splunk\var\log\splunk\metrics.logsourcetype = splunkd
> 11/16/21

3:11:33.745 PM

11-16-2021 15:11:33.745 -0800 INFO Metrics - group=thruput, name=index_thruput, instantaneous_kbps=4.971, instantaneous_eps=19.355, average_kbps=1.667, total_k_processed=182424.000, kb=154.094, ev=600 host = PF32198Dsource = C:\Program Files\Splunk\var\log\splunk\metrics.logsourcetype = splunkd
> 11/16/21

3:11:33.745 PM

11-16-2021 15:11:33.745 -0800 INFO Metrics - group=queue, name=winparsing, max_size_kb=500, current_size_kb=0, current_size=0, largest_size=0, smallest_size=0 host = PF32198Dsource = C:\Program Files\Splunk\var\log\splunk\metrics.logsourcetype = splunkd

See also

search, return

Last modified on 20 December, 2022
PREVIOUS
foreach
  NEXT
from

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.5, 8.0.10, 7.2.1, 7.0.1, 8.0.4, 8.0.9, 8.1.0, 8.1.1, 8.1.2, 8.1.3, 8.1.4, 8.1.5, 8.1.6, 8.1.7, 8.1.8, 8.1.9, 8.1.10, 8.1.11, 8.1.12, 8.1.13, 8.1.14, 8.2.0, 8.2.1, 8.2.2, 8.2.3, 8.2.4, 8.2.5, 8.2.6, 8.2.7, 8.2.8, 8.2.9, 8.2.10, 8.2.11, 8.2.12, 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.2.0, 8.0.6, 8.0.7, 8.0.8


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