The supported type specifiers are the following.

A number is a field that contains only an integer or a real number, with no grouping, for example, 1,000 is not a number. Scientific notation, for example, 1.74587E100 is supported.

If a field is not a number following the above description, the output of format given any of the above type specifiers is null.

format("%X", field=[num])

format("0x%X", field=[num])

On type specifier b or B, if the corresponding field is false, then the result is false or FALSE respectively. Otherwise, the result is true or TRUE, respectively.

A string is any sequence of length >= 1 consisting of unicode characters. Any field will match this description.

On type specifier c, the first character of the string is output. Type specifier s outputs the specified field.

For dates and times, the format specifier t or T is a prefix for the value specific format, as supported by the formatTime() and formatDuration() functions.

For example, to format the @timestamp field to show the time in HOUR:MINUTE format using format() function, it would need the format specifier %tH:%tM:

parseTimestamp(field=@timestamp)
| timeonly := format("%tH:%tM",field=[@timestamp,@timestamp])

In the above example, note as well that the source field @timestamp must be provided twice to be decoded by each format specifier.

This is equivalent to using formatTime():

parseTimestamp(field=@timestamp)
| timeonly := formatTime("%H:%M",field=@timestamp)

For more information, see formatTime()

Fields can only be used as date/time values if they are in milliseconds since the beginning of the Unix epoch, 1 January 1970 00:00:00 UTC. If the field is anything else, format outputs null.

All Date/Time type specifiers must be followed by a Date/Time modifier.

The following time modifiers are available:

The following date modifiers are available:

Furthermore, the following special date/time modifiers are available:

The argument index is a decimal integer indicating the position of the argument in the fields list. The first argument is referenced by 1$, the second by 2$, and so on. Another way to reference arguments by position is to use the '<'(\u003c) flag, which causes the argument for the previous format specifier to be re-used. For example, the following two statements produce identical strings:

format("Event date: %1$Tm/%1$Te/%1$TY", field=[@timestamp], timezone="Europe/Copenhagen")
format("Event date: %1$Tm/%<Te/%<TY", field=[@timestamp], timezone="Europe/Copenhagen")

If no argument index is specified, the first format specifier refers to the first argument of the fields list, the second format specifier refers to the second argument and so on.

The length argument specifies the length with which to interpret the given fields' data type.

In general, format() interprets any number that is not a floating point number to be that of a 64-bit signed integer and formats any such integer with leading zeros removed. For instance, converting 42 to hexadecimal with the format string 0x%X produces the string 0x2A and not one with 62 leading zeros. However, conversions of negative numbers to hexadecimal are represented using Two's complement which entails a large number of leading F characters. For example, the number -1 is by default represented using all 64-bits, hence the above format string produces 0xFFFFFFFFFFFFFFFF. This can for example be brought down to 0xFFFFFFFF by specifying the h length argument.

CPU time is the exact amount of time that the CPU has spent processing data for a specific program or process. In this example the avg() function is used to calculate the sum of all numbers; the mean of the CPU Time.

The query is used to averaging the field containing the CPU value. This value is then piped to the format() function, which provides a formatting code — how the field value should be formatted. In this example, it formats the value to two decimal. Calculation of CPU times is useful to determine processing power - for example if troubleshooting a system with high CPU usage.

Sample output from the incoming example data:

The concat() is not able to concatenate fields and strings together. For example to create a pathname based on the directory and filename it is not possible to do:

concat([dirname,"/",filename],as=pathname)

This will raise an error. Instead, we can use format().

The format() function provides a flexible method of formatting data, including encapsulating or combining strings and fields together.

In this example, the objectArray:eval() function is used to format the array entries in[].key and in[].value separating the concatenated values with a : in the output field out[]. The output must be a single field in this example as format() is only capable of creating a single value.

Example incoming data might look like this:

in[0].key = x
in[0].value = y
in[1].key = a
in[1].value = b

The query is used to format arrays of objects.

Sample output from the incoming example data:

out[0] = x:y
out[1] = a:b

In this example, the array:eval() function is used to convert all values (for example [Thermostat, Smart Light]) in an array devices[] from lowercase to uppercase and show the results in a new array.

Example incoming data might look like this:

The query is used to turn values in an array into uppercase. The array:eval() function can also be used for squaring a list of numbers in an array.

Sample output from the incoming example data:

To round a number to a specific number of decimal points, use format() rather than round()

When using format(), rounding is performed using standard math rules. The format() rounds a number to a specific decimal accuracy. To round a number to the nearest decimal, use round().