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 multiplefieldformat
commands. See Examples.
For more information, see the eval command.
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",...)
|
in(VALUE-LIST)
|
nullif(X,Y)
|
Conversion functions | printf("format",arguments) |
tonumber(NUMSTR,BASE) |
tostring(X,Y) |
Cryptographic functions | md5(X)
|
sha256(X) |
sha512(X) |
Date and Time functions | now()
|
strftime(X,Y)
|
time() |
Informational functions | isbool(X)
|
isnull(X)
|
isstr(X)
|
Mathematical functions | abs(X)
|
floor(X)
|
pow(X,Y)
|
Multivalue eval functions | commands(X)
|
mvfilter(X)
|
mvrange(X,Y,Z)
|
Statistical eval functions | max(X,...) |
min(X,...) |
random() |
Text functions | len(X)
|
rtrim(X,Y)
|
trim(X,Y)
|
Trigonometry and Hyperbolic functions | acos(X)
|
atan2(X,Y)
|
sin(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 |
---|---|
access_combined_wcookie | 39532 |
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 |
---|---|
access_combined _wcookie | 39,532 |
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 fieldsfirstTime
,lastTime
,recentTime
,totalCount
, andtype
. - In addition, because the search specifies
types=sourcetypes
, a field calledsourcetype
is also returned. - The
totalCount
,firstTime
,lastTime
, andrecentTime
fields are renamed toCount
,First Event
,Last Event
, andLast Update
. - The
First Event
,Last Event
, andLast 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 |
---|---|---|---|---|
access_combined_wcookie | 39532 | 1520904136 | 1524014536 | 1524067875 |
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 |
See also
extract | fields |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403, 9.2.2406 (latest FedRAMP release)
Feedback submitted, thanks!