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. Download topic as PDF

# fieldformat

## Description

With the `fieldformat` command you can use an <eval-expression> to change the format of a field value when the results render. This command changes the appearance of the results without changing the underlying value of the field.

Because commands that come later in the search pipeline cannot modify the formatted results, use the `fieldformat` command as late in the search pipeline as possible.

The `fieldformat` command does not apply to commands that export data, such as the `outputcsv` and `outputlookup` commands. The export retains the original data format and not the rendered format. If you want the format to apply to exported data, use the `eval` command instead of the `fieldformat` command.

## Syntax

fieldformat <field>=<eval-expression>

### Required arguments

<field>
Description: The name of a new or existing field, non-wildcarded, for the output of the eval expression.
<eval-expression>
Syntax: <string>
Description: A combination of values, variables, operators, and functions that represent the value of your destination field. You can specify only one <eval-expression> with the `fieldformat` command. To specify multiple formats you must use multiple `fieldformat` commands. See Examples.

For information about supported functions, see Usage.

## Usage

The `fieldformat` command is a distributable streaming command. See Command types.

Time format variables are frequently used with the `fieldformat` command. See Date and time format variables.

### Functions

You can use a wide range of functions with the `fieldformat` command. For general information about using functions, see Evaluation functions.

The following table lists the supported functions by type of function. Use the links in the table to learn more about each function, and to see examples.

Type of function Supported functions and syntax
Comparison and Conditional functions `case(X,"Y",...)`

`cidrmatch("X",Y)`
`coalesce(X,...)`
`false()`
`if(X,Y,Z)`

`in(VALUE-LIST)`

`like(TEXT, PATTERN)`
`match(SUBJECT, "REGEX")`
`null()`

`nullif(X,Y)`

`searchmatch(X)`
`true()`
`validate(X,Y,...)`

Conversion functions `printf("format",arguments)`
`tonumber(NUMSTR,BASE)`
`tostring(X,Y)`
Cryptographic functions `md5(X)`

`sha1(X)`

`sha256(X)`
`sha512(X)`
Date and Time functions `now()`

`relative_time(X,Y)`

`strftime(X,Y)`

`strptime(X,Y)`

`time()`
Informational functions `isbool(X)`

`isint(X)`
`isnotnull(X)`

`isnull(X)`

`isnum(X)`

`isstr(X)`

`typeof(X)`

Mathematical functions `abs(X)`

`ceiling(X)`
`exact(X)`
`exp(X)`

`floor(X)`

`ln(X)`
`log(X,Y)`
`pi()`

`pow(X,Y)`

`round(X,Y)`
`sigfig(X)`
`sqrt(X)`

Multivalue eval functions `commands(X)`

`mvappend(X,...)`
`mvcount(MVFIELD)`
`mvdedup(X)`

`mvfilter(X)`

`mvfind(MVFIELD,"REGEX")`
`mvindex(MVFIELD,STARTINDEX,ENDINDEX)`
`mvjoin(MVFIELD,STR)`

`mvrange(X,Y,Z)`

`mvsort(X)`
`mvzip(X,Y,"Z")`

Statistical eval functions `max(X,...)`
`min(X,...)`
`random()`
Text functions `len(X)`

`lower(X)`
`ltrim(X,Y)`
`replace(X,Y,Z)`

`rtrim(X,Y)`

`spath(X,Y)`
`split(X,"Y")`
`substr(X,Y,Z)`

`trim(X,Y)`

`upper(X)`
`urldecode(X)`

Trigonometry and Hyperbolic functions `acos(X)`

`acosh(X)`
`asin(X)`
`asinh(X)`
`atan(X)`

`atan2(X,Y)`

`atanh(X)`
`cos(X)`
`cosh(X)`
`hypot(X,Y)`

`sin(X)`

`sinh(X)`
`tan(X)`
`tanh(X)`

## Basic examples

### 1. Format numeric values to display commas

This example uses the metadata command to return results for the sourcetypes in the main index.

```| metadata type=sourcetypes | table sourcetype totalCount```

The `metadata` command returns many fields. The `table` command is used to return only the sourcetype and totalCount fields.

The results appear on the Statistics tab and look something like this:

sourcetype totalCount
cisco:esa 112421
csv 9510
secure 40088
vendor_sales 30244

Use the `fieldformat` command to reformat the appearance of the field values. The values in the `totalCount` field are formatted to display the values with commas.

```| metadata type=sourcetypes | table sourcetype totalCount | fieldformat totalCount=tostring(totalCount, "commas")```

The results appear on the Statistics tab and look something like this:

sourcetype totalCount
cisco:esa 112,421
csv 9,510
secure 40,088
vendor_sales 30,244

### 2. Display UNIX time in a readable format

Assume that the `start_time` field contains UNIX time. Format the `start_time` field to display only the hours, minutes, and seconds that correspond to the UNIX time.

`... | fieldformat start_time = strftime(start_time, "%H:%M:%S")`

### 3. Add currency symbols to numerical values

To format numerical values in a field with a currency symbol, you must specify the symbol as a literal and enclose it in quotation marks. Use a period character as a binary concatenation operator, followed by the `tostring` function, which enables you to display commas in the currency values.

`...| fieldformat totalSales="\$".tostring(totalSales,"commas")`

## Extended example

### 1. Formatting multiple fields

This example shows how to change the appearance of search results to display commas in numerical values and dates into readable formats.

First, use the metadata command to return results for the sourcetypes in the main index.

|metadata type=sourcetypes | table sourcetype totalCount |fieldformat totalCount=tostring(totalCount, "commas")

```| metadata type=sourcetypes | rename totalCount as Count firstTime as "First Event" lastTime as "Last Event" recentTime as "Last Update" | table sourcetype Count "First Event" "Last Event" "Last Update"```

• The `metadata` command returns the fields `firstTime`, `lastTime`, `recentTime`, `totalCount`, and `type`.
• In addition, because the search specifies `types=sourcetypes`, a field called `sourcetype` is also returned.
• The `totalCount`, `firstTime`, `lastTime`, and `recentTime` fields are renamed to `Count`, `First Event`, `Last Event`, and `Last Update`.
• The `First Event`, `Last Event`, and `Last Update` fields display the values in UNIX time.

The results appear on the Statistics tab and look something like this:

sourcetype Count First Event Last Event Last Update
cisco:esa 112421 1521501480 1521515900 1523471156
csv 9510 1520307602 1523296313 1523392090
secure 40088 1520838901 1523949306 1524067876
vendor_sales 30244 1520904187 1524014642 1524067875

Use the `fieldformat` command to reformat the appearance of the output of these fields. The `Count` field is formatted to display the values with commas. The `First Event`, `Last Event`, and `Last Update` fields are formatted to display the values in readable timestamps.

```| metadata type=sourcetypes | rename totalCount as Count firstTime as "First Event" lastTime as "Last Event" recentTime as "Last Update" | table sourcetype Count "First Event" "Last Event" "Last Update" | fieldformat Count=tostring(Count, "commas") | fieldformat "First Event"=strftime('First Event', "%c") | fieldformat "Last Event"=strftime('Last Event', "%c") | fieldformat "Last Update"=strftime('Last Update', "%c")```

The results appear on the Statistics tab and look something like this:

sourcetype Count First Event Last Event Last Update
access_combined _wcookie 39,532 Mon Mar 12 18:22:16 2018 Tue Apr 17 18:22:16 2018 Wed Apr 18 09:11:15 2018
cisco:esa 112,421 Mon Mar 19 16:18:00 2018 Mon Mar 19 20:18:20 2018 Wed Apr 11 11:25:56 2018
csv 9,510 Mon Mar 5 19:40:02 2018 Mon Apr 9 10:51:53 2018 Tue Apr 10 13:28:10 2018
secure 40,088 Mon Mar 12 00:15:01 2018 Tue Apr 17 00:15:06 2018 Wed Apr 18 09:11:16 2018
vendor_sales 30,244 Mon Mar 12 18:23:07 2018 Tue Apr 17 18:24:02 2018 Wed Apr 18 09:11:15 2018
{"ft_lang_label":"__label__en","ft_lang_prob":0.578637,"math_prob":0.81901324,"size":7559,"snap":"2022-05-2022-21","text_gpt3_token_len":2416,"char_repetition_ratio":0.15234944,"word_repetition_ratio":0.15284249,"special_character_ratio":0.32782114,"punctuation_ratio":0.23378941,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.96476084,"pos_list":[0,1,2],"im_url_duplicate_count":[null,null,null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2022-05-26T14:37:09Z\",\"WARC-Record-ID\":\"<urn:uuid:782c4052-40b2-499a-afc9-4f58e020e66a>\",\"Content-Length\":\"208587\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:8ecea4f6-fc16-4b85-a796-946d60efbe5f>\",\"WARC-Concurrent-To\":\"<urn:uuid:d93ab300-2aeb-4954-864a-32f450cd8209>\",\"WARC-IP-Address\":\"44.236.217.47\",\"WARC-Target-URI\":\"https://docs.splunk.com/Documentation/Splunk/7.1.8/SearchReference/Fieldformat\",\"WARC-Payload-Digest\":\"sha1:HMUNDDMYBBLTSQNRX2RFAFPIB4XG42MV\",\"WARC-Block-Digest\":\"sha1:Z33JOTBGTQNGAQDMPS4OQAFR7YPOBP7M\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2022/CC-MAIN-2022-21/CC-MAIN-2022-21_segments_1652662606992.69_warc_CC-MAIN-20220526131456-20220526161456-00121.warc.gz\"}"}