Splunk® Cloud Services

SPL2 Search Reference

Conversion functions

The following list contains the SPL2 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 uses the ipmask function in a pipeline to create a new field with the masked values called maskedIP. The original field, clientip, is removed before sending the data to the destination.

$pipeline = from $source | eval maskedIP = ipmask("255.0.255.0", clientip) | fields - clientip | into $destination


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.255", 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:

Event
stateData: "[{"state":"Washington","population":7535591},{"state":"California","population":39557045},{"state":"Oregon","population":4190714}]"

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:

Event
stateData: "{"state":"Washington","population":7535591}"
stateData: "{"state":"California","population":39557045}"
stateData: "{"state":"Oregon","population":4190714}"

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:

Dept
"[{"city":"Berlin","employee_info":[{"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"}]},

{"city":"Prague","employee_info":[{"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"}]},
{"city":"Dublin","employee_info":
[{"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"}]}]"

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:

Dept
{"city":"Berlin","employee_info":[{"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"}]}
{"city":"Prague","employee_info":[{"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"}]}
{"city":"Dublin","employee_info":[{"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"}]}

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:

city employee_info
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"}]


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.

Conversion specifier Alias Description Examples
%a or %A Floating point number in hexadecimal format This example returns the value of pi to 3 decimal points, in hexadecimal format.

printf("%.3A",pi()) which returns 0X1.922P+1

%c Single Unicode code point This example returns the unicode code point for 65 and the first letter of the string "Foo".

printf("%c,%c",65,"Foo") which returns A,F
%d %i Signed decimal integer This example returns the positive or negative integer values, including any signs specified with those values.

printf("%d,%i,%d",-2,+4,30) which returns -2,4,30
%e or %E Floating point number, exponential format This example returns the number 5139 in exponential format with 2 decimal points.

printf("%.2e",5139) which returns 5.14e+03
%f or %F Floating point number This example returns the value of pi to 2 decimal points.

printf("%.2f",pi()) which returns 3.14

%g or %G Floating point number. This specifier uses either %e or %f depending on the range of the numbers being formatted. This example returns the value of pi to 2 decimal points (using the %f specifier) and the number 123 in exponential format with 2 decimal points (using %e specifier).

printf("%.2g,%.2g",pi(),123) which returns 3.1,1.2e+02

%o Unsigned octal number This example returns the base-8 number for 255.

printf("%o",255) which returns 377

%s %z String This example returns the concatenated string values of "foo" and "bar".

printf("%s%z", "foo", "bar") which returns foobar

%u Unsigned, or non-negative, decimal integer This example returns the integer value of the number in the argument. printf("%u,",99) which returns 99
%x or %X %p Unsigned hexadecimal number (lowercase or uppercase) This example returns the hexadecimal values that are equivalent to the numbers in the arguments. This example shows both upper and lowercase results when using this specifier.

printf("%x,%X,%p",10,10,10) which returns a,A,A

%% Percent sign This example returns the string value with a percent sign.

printf("100%%") which returns 100%

Flag characters

The following table describes the supported flag characters.

Flag characters Description Examples
single quote or apostrophe ( ' ) Adds commas as the thousands separator. printf("%'d",12345) which returns 12,345
dash or minus ( - ) Left justify. If this flag is not specified, the is right-justified. printf("%-4d",1) which returns 1   
zero ( 0 ) Zero pad This example returns the value in the argument with leading zeros such that the number has 4 digits.

printf("%04d",1) which returns 0001

plus ( + ) Always include the sign ( + or - ). If this flag is not specified, the conversion displays a sign only for negative values. printf("%+4d",1) which returns   +1
<space> Reserve space for the sign. If the first character of a signed conversion is not a sign or if a signed conversion results in no characters, a <space> is added as a prefixed to the result. If both the <space> and + flags are specified, the <space> flag is ignored. printf("% -4d",1) which returns    1
hash, number, or pound ( # ) Use an alternate form. For the %o conversion specifier, the # flag increases the precision to force the first digit of the result to be zero. For %x or %X conversion specifiers, a non-zero result has 0x (or 0X) prefixed to it. For %a, %A, %e, %E, %f, %F, %%g , and G conversion specifiers, the result always contains a radix character, even if no digits follow the radix character. Without this flag, a radix character appears in the result of these conversions only if a digit follows it. For %g and %G conversion specifiers, trailing zeros are not removed from the result as they normally are. For other conversion specifiers, the behavior is undefined. printf("%#x", 1) which returns 0x1

Specifying field width

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

Examples
The following example returns the positive or negative integer values, including any signs specified with those values.

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

The following example returns the floating point number with 1 decimal point.

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

The following example returns the value of pi() in exponential format with 2 decimal points.

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.

Field width specifier Description Examples
number The minimum number of characters to print. If the value to print is shorter than this number, the result is padded with blank spaces. The value is not truncated even if the result is larger.
* (asterisk) The width is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted.

Specifying precision

Precision Description
%d, %i, %o, %u, %x or %X Precision specifies the minimum number of digits to be return. If the value to be return is shorter than this number, the result is padded with leading zeros. The value is not truncated even if the result is longer. A precision of 0 means that no character is returned for the value 0.
%a or %A, %e or %E, %f or %F This is the number of digits to be returned after the decimal point. The default is 6 .
%g or %G This is the maximum number of significant digits to be returned.
%s This is the maximum number of characters to be returned. By default all characters are printed until the ending null character is encountered.
Specifying the period without a precision value If the period is specified without an explicit value for precision, 0 is assumed.
Specifying an asterisk for the precision value, for example .* The precision is not specified in the format string, but as an additional integer value argument preceding the argument that has to be formatted.

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:

IP Addresses Total Purchased Product IDs
107.3.146.207 66 BS-AG-G09,DC-SG-G02,MB-AG-T01,PZ-SG-G05,SC-MG-G10,WC-SH-A02,WC-SH-G04
108.65.113.83 30 MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-A01,WC-SH-A02
109.169.32.135 24 MB-AG-T01,SC-MG-G10,WC-SH-A01,WC-SH-T02
110.138.30.229 12 SC-MG-G10,WC-SH-T02
110.159.208.78 54 DB-SG-G01,DC-SG-G02,FI-AG-G08,MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-G04,WC-SH-T02

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;

IP Addresses Total Purchased Product IDs jsonObject
107.3.146.207 66 BS-AG-G09,DC-SG-G02,MB-AG-T01,PZ-SG-G05,SC-MG-G10,WC-SH-A02,WC-SH-G04 {"IP Addresses":"107.3.146.207","Product IDs":["BS-AG-G09","DC-SG-G02","MB-AG-T01","PZ-SG-G05","SC-MG-G10","WC-SH-A02","WC-SH-G04"],"Total Purchased":66}
108.65.113.83 30 MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-A01,WC-SH-A02 {"IP Addresses":"108.65.113.83","Product IDs":["MB-AG-G07","PZ-SG-G05","SC-MG-G10","WC-SH-A01","WC-SH-A02"],"Total Purchased":30}
109.169.32.135 24 MB-AG-T01,SC-MG-G10,WC-SH-A01,WC-SH-T02 {"IP Addresses":"109.169.32.135","Product IDs":["MB-AG-T01","SC-MG-G10","WC-SH-A01","WC-SH-T02"],"Total Purchased":24}
110.138.30.229 12 SC-MG-G10,WC-SH-T02 {"IP Addresses":"110.138.30.229","Product IDs":["SC-MG-G10","WC-SH-T02"],"Total Purchased":12}
110.159.208.78 54 DB-SG-G01,DC-SG-G02,FI-AG-G08,MB-AG-G07,PZ-SG-G05,SC-MG-G10,WC-SH-G04,WC-SH-T02 {"IP Addresses":"110.159.208.78","Product IDs":["DB-SG-G01","DC-SG-G02","FI-AG-G08","MB-AG-G07","PZ-SG-G05","SC-MG-G10","WC-SH-G04","WC-SH-T02"],"Total Purchased":54}

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:

_time code error_type
4:02:17 PM, 11 Apr 2022 200 NULL
4:02:17 PM, 11 Apr 2022 401 auth

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:

_time _raw code error_type
4:02:17 PM, 11 Apr 2022 {"_time":1649718137,"code":200} 200 NULL
4:02:17 PM, 11 Apr 2022 {"_time":1649718137,"code":401,"error_type":"auth"} 401 auth

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".

Examples Description
tostring(<value>,"hex") Converts <value> to hexadecimal.
tostring(<value>,"commas") Formats <value> with commas. If the number includes decimals, the function rounds to nearest two decimal places.
tostring(<value>,"duration") Converts a <value> that is in seconds to the readable time format HH:MM:SS.

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
Last modified on 14 August, 2024
Comparison and Conditional functions   Cryptographic functions

This documentation applies to the following versions of Splunk® Cloud Services: current

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters