Conversion functions - Splunk Documentation (2024)

The following list contains the functions that you can use to mask IP addresses and convert numbers to strings and strings to numbers.

For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval functions.

ipmask(<mask>,<ip>)

Description

This function generates a new masked IP address by applying a mask to an IP address through a bitwise AND operation. You can use this function to simplify the isolation of an IPv4 address octet without splitting the IP address.

Usage

The <mask> argument must be a valid IPv4 address. The <ip> argument must be a valid IPv4 address or a field name where the field value is a valid IPv4 address.

A valid IPv4 address is a quad-dotted notation of four decimal integers, each ranging from 0-255.

For the <mask> argument, you can specify one of the default subnet masks such as 255.255.255.0.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Examples

The following example shows how to use the ipmask function with the eval command. The output of this example is 10.20.30.0.

... | eval maskedIP = ipmask("255.255.255.0", "10.20.30.120")

The following example shows how to use the ipmask function in the SELECT clause of the from command. This example masks every IP address in the clientip field and returns the results in an aliased field called maskedip.

FROM main SELECT ipmask("0.255.0.244", clientip) AS maskedip

The following example shows how to use the ipmask function in the WHERE clause of the from command to filter the events on a specific mask value. In this example, the masked value is 0.20.0.96.

FROM main WHERE ipmask("0.255.0.224", clientip)="10.20.30.120"

object_to_array(<object>, <key>, <value>)

Converts data that is in an object format into an array format.

Usage

You can use this function with the eval command.

The <object> is the data that is formatted as an object.

The <key> is the label you want to use for the name of the keys in the array of key-value pairs. The <key> must be enclosed in quotation marks.

The <value> is the label you want to use as the name of the values in the array of key-value pairs. The <value> must be enclosed in quotation marks.

Examples

Converting a single object into an array

Consider the following field, called statePop which consists of a set of state names and the population in those states:

{"Washington": 7535591, "California": 39557045, "Oregon": 4190714} 

Use the object_to_array function to create an array from the objects.

... | eval stateData=object_to_array(statePop,"state", "population")

The results look something like this:

You can separate the objects in the array by adding the expand command to the search:

... | eval stateData=object_to_array(statePop,"state", "population") | expand stateData

The results look something like this:

Converting nested objects into an array

Consider the following field, called employees which consists of information about employees organized by city:

{ "Berlin": [ { "employeeID": "011", "lastName": "Martin", "firstName": "Alex", "department": "Sales", "hireDate": "2004-11-15 00:00:00.000" }, { "employeeID": "015", "lastName": "Garcia", "firstName": "Claudia", "department": "Sales", "hireDate": "2001-08-15 00:00:00.000" }, { "employeeID": "017", "lastName": "Dubois", "firstName": "Maria", "department": "Marketing", "hireDate": "2017-03-15 00:00:00.000" } ], "Prague": [ { "employeeID": "023", "lastName": "Sullivan", "firstName": "Rutherford", "department": "Engineering", "hireDate": "2015-12-15 00:00:00.000" }, { "employeeID": "025", "lastName": "Patel", "firstName": "Vanya", "department": "Sales", "hireDate": "2019-06-15 00:00:00.000" } ], "Dublin": [ { "employeeID": "031", "lastName": "Zhang", "firstName": "Wei", "department": "Human Resources", "hireDate": "2019-09-15 00:00:00.000" }, { "employeeID": "036", "lastName": "Mayer", "firstName": "David", "department": "Sales", "hireDate": "2018-04-15 00:00:00.000" } ]}

Use the object_to_array function to create an array from the nested objects.

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info")

The results look something like this:

All of the Information appears on a single row.

Add the expand command to the search to separate out each nested array:

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info") | expand Dept

The results look something like this:

Information for each city appears on a separate row.

Add the flatten command to the search to create fields for the city and employee_info information:

FROM employees | eval Dept=object_to_array(employees,"city", "employee_info") | expand Dept | flatten Dept

The results look something like this:

printf(<format>, <arguments>)

This function builds a string value, based on a string format and the arguments specified. You can specify zero or more values. The values can be strings, numbers, computations, or fields.

The SPL2 printf function is similar to the C sprintf() function and similar functions in other languages such as Python, Perl, and Ruby.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

format

Description: The <format> is a character string that can include one or more format conversion specifiers. Each conversion specifier can include optional components such as flag characters, width specifications, and precision specifications. The <format> must be enclosed in quotation marks.

Syntax: "(%[flags][width][.precision]<conversion_specifier>)..."

arguments

Description: The <arguments> are optional and can include the width, precision, and the value to format. The <arguments> can be strings, numbers, or field names.

Syntax: [width][.precision][value]

Supported conversion specifiers

The following table describes the supported conversion specifiers.

Flag characters

The following table describes the supported flag characters.

Specifying field width

You can use an asterisk ( * ) with the printf function to return the field width or precision from an argument.

printf("%*d", 5, 123) which returns 123

printf("%.*f", 1, 1.23) which returns 1.2

printf("%*.*e", 9, 2, pi()) which returns 3.14e+00

The field width can be expressed using a number or an argument denoted with an asterisk ( * ) character.

Specifying precision

Unsupported conversion specifiers

There are a few conversion specifiers from the C sprintf() function that are not supported, including:

• %C, however%c is supported
• %n
• %S, however%s is supported
• %<num>$ specifier for picking which argument to use

Basic examples

This example creates a new field called new_field and creates string values based on the values in field_one and field_two. The values are formatted with 4 digits before the decimal and 4 digits after the decimal. The - specifies to left justify the string values. The 30 specifies the width of the field.

...| eval new_field=printf("%04.4f%-30s",field_one,field_two)

tojson(<internal_fields>)

Returns a JSON object representation of events or search results.

Usage

You can use this function with the eval and where commands, in clauses of the from command that can take an expression, and as part of evaluation expressions with other commands.

The <internal_fields> parameter is optional and used to specify whether fields that start with an underscore ( _ ) character, typically internal fields, are included in the JSON object. By default, <internal_fields> is set to "true".

Examples

1. Create a JSON object from a set of search results

Consider the following search:

FROM sample_data_index WHERE status=200 AND action="purchase" AND productId!=""| stats count() AS 'Total Purchased' , values(productId) AS 'Product IDs' BY clientip | rename clientip AS 'IP Addresses'

This search returns results that look like this:

To create a JSON object for each row in the search results, add the tojson function to the search:

from sample_data_index where status=200 AND action="purchase" AND productId!=""| stats count() AS 'Total Purchased' , values(productId) AS 'Product IDs' BY clientip | rename clientip AS 'IP Addresses' | eval jsonObject = tojson()

The JSON objects are placed into a new field called "jsonObject". The results look like this;

2. Create a JSON object from dataset literal

Here's another example. Consider this search, which uses a dataset literal to create an event:

FROM [{code: 200}, {code: 401, error_type: "auth"}] | eval _time = now()

This search returns results that look like this:

You can use the tojson function to place all of fields in the event into a JSON object in the _raw field:

FROM [{code: 200}, {code: 401, error_type: "auth"}] | eval _time = now() | eval _raw = tojson()

This search returns results that look like this:

tonumber(<str>, <base>)

This function converts a string to a number. The base is optional. If not specified, base 10 is used.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

The <str> can be a field name or a value.

The <base> is used to define the base of the number in <str>. The <base> can be 2 to 36. The default is 10, which corresponds to the decimal system.

If the tonumber function cannot parse a field value to a number, for example if the value contains a leading and trailing space, the function returns NULL.Use the trim function to remove leading or trailing spaces.

If the tonumber function cannot parse a literal string to a number, the function returns an error.

Basic examples

The following example converts the string values for the store_sales field to numbers. This example uses the default <base>.

... | eval n=tonumber(store_sales)

The following example takes the hexadecimal number and uses a <base> of 16 to return the number "164".

... | eval n=tonumber("0A4",16)

The following example trims any leading or trailing spaces from the values in the celsius field before converting it to a number.

... | eval temperature=tonumber(trim(celsius))

tostring(<value>, <format>)

This function converts a value to a string using the specified format.

If the input value is a number, it reformats it as a string. If the input value is a Boolean value, it returns the corresponding string value, "True" or "False".

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

When used with the eval command, the values might not sort as expected because the values are converted to ASCII. Use the fieldformat command with the tostring function to format the displayed values. The underlying values are not changed with the fieldformat command.

If <value> is a number, the second argument <format> is optional and can be "hex", "commas", or "duration".

Basic examples

The following example returns period=615 and period_time=00:10:15. The 615 seconds is converted into minutes and seconds.

... | eval period=615 | eval period_time = tostring(period, "duration")

The following example returns "True 0xF 12,345.68".

... | eval n=tostring(1==1) + " " + tostring(15, "hex") + " " + tostring(12345.6789, "commas")

See also

Function information

Quick Reference for SPL2 eval functions

Overview of SPL2 eval functions

Naming function arguments in the SPL2 Search Manual

Specific functions

mv_to_json_array

strptime