Required arguments

None.

Optional arguments

Specifying row and column arguments

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

1. Example with no optional parameters

Suppose that you have results that look like this:

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.

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:

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:

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.

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 like this.

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.