Splunk® Cloud Services

SPL2 Search Reference

Conversion functions

The following list contains the SPL2 functions that you can use to mask IP addresses, build string values based on specified formats and arguments, and convert values from one data type to another.

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

ipmask(<mask>,<ip>)

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.

Basic 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>)

This function 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.

Extended examples

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

2. 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 example

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)


toarray(<value>)

This function converts a string or multivalue to an array. The function infers the data type of each array element as it converts the string or multivalue into an array.

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 <value> argument can be a string or multivalue, or the name of a field that contains a string or multivalue.

If the <value> argument is a string, it must be a list of comma-separated values where the entire list is enclosed in square brackets ( [ ] ), or else the function returns null. For example, this string value is valid: ["buttercup", "fluttershy", "rarity"]

Basic examples

The following example returns a field named my_array containing the value [1,2,3].

... | eval my_array=toarray(split("1, 2, 3", ","))

The following example converts the value ["carrots", 1.00, "potatoes", 1.75] from a string to an array and stores the result in a field named grocery_array.

... | eval grocery_array=toarray("[\"carrots\", 1.00, \"potatoes\", 1.75]")

Extended example

The test_data field in these events contains multivalues.

_time test_data
2024-12-10 00:46:39 100

200
300

2024-12-10 00:46:45 4

5
6

The following eval command converts the multivalues in the test_data field into arrays and stores them in a field named test_array:

... | eval test_array = toarray(test_data)

The results look like this:

_time test_data test_array
2024-12-10 00:46:39 100

200
300

[100,200,300]
2024-12-10 00:46:45 4

5
6

[4,5,6]

tobool(<value>)

This function converts a string or number to a Boolean value.

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. Because the function returns a Boolean value, it is supported differently in different product contexts:

  • In searches, you can use the tobool function directly with the where command, but the eval command can't directly accept a Boolean value. You must specify the function inside another function, such as the if function, which can accept a Boolean value as input.
  • In Edge Processor and Ingest Processor pipelines, the eval command is able to directly accept Boolean values, so you can use the tobool function directly with both the where and eval commands.

The <value> argument can be a string or number, or the name of a field that contains a string or number.

The following table describes how the tobool function converts specific strings and numbers into Boolean values. The function returns null for all other values.

Data type Value Returned Boolean value
String "true" or "True" true
"false" or "False" false
"TRUE" or "FALSE" Not supported, returns null.
Number 0 false
Any non-zero number true

Basic example

The following example is not supported in searches, and only works in Edge Processor and Ingest Processor pipelines.

In this example, the eval command uses the tobool function to convert the value true from a string to a Boolean, and then stores the converted value in a field named result_boolean.

... | eval result_boolean=tobool("true")

Extended example

The following example works in searches as well as Edge Processor and Ingest Processor pipelines.

Suppose you have data that looks like this:

_time categoryId units
2024-11-07 21:25:09 Dream Crusher 12
2024-11-07 21:25:09 Final Sequel 0
2024-11-07 21:25:09 Grand Theft Scooter 15
2024-11-07 21:25:09 Mediocre Kingdom 35
2024-11-07 21:25:09 Orvil the Wolverine 1

You can use the following eval command, which includes the tobool function, to determine which items are in stock:

... | eval in_stock=if(tobool(units), "In Stock", "Not in Stock")

The results look like this:

_time categoryId units in_stock
2024-11-07 21:25:09 Dream Crusher 12 In Stock
2024-11-07 21:25:09 Final Sequel 0 Not in Stock
2024-11-07 21:25:09 Grand Theft Scooter 15 In Stock
2024-11-07 21:25:09 Mediocre Kingdom 35 In Stock
2024-11-07 21:25:09 Orvil the Wolverine 1 In Stock

todouble(<value>, <base>)

This function converts a string or number to a double.

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 <value> argument can be a string or number, or the name of a field that contains a string or number.

The <base> argument is optional, and it is used only when the <value> argument is a string. The <base> argument defines the base of the number in the <value> argument. It defaults to 10, which corresponds to the decimal system. You can set <base> to a number between 2 and 36, inclusive.

If the todouble function cannot parse a field value to a number, such as 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 todouble function cannot parse a string to a number, the function returns null.

Basic examples

The following example converts the value 16.00 from a string to a double, and stores the converted value in a field named numbers_double.

... | eval numbers_double=todouble("16.00")

The following example converts the value 5 from a number to a double so that it becomes 5.0, and then stores the converted value in a field named numbers_double.

... | eval numbers_double=todouble(5)

toint(<value>, <base>)

This function converts a string or number to an integer.

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 <value> argument can be a string or number, or the name of a field that contains a string or number. If the value includes decimal places, the toint function rounds it down to the nearest whole number.

The <base> argument is optional, and it is used only when the <value> argument is a string. The <base> argument defines the base of the number in the <value> argument. It defaults to 10, which corresponds to the decimal system. You can set <base> to a number between 2 and 36, inclusive.

If the toint 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.

Be aware that integers are supported differently in different product contexts:

  • The Splunk platform supports 53-bit integers with 8 bits of precision. Integers larger than 53 bits are truncated.
  • The Edge Processor and Ingest Processor solutions support 64-bit integers.

Basic examples

The following example converts the value 24 from a string to an integer, and stores the converted value in a field named numbers_int.

... | eval numbers_int=toint("24")

The following example converts the value 3.14 from a double to an integer. The toint function rounds the value down to 3 and stores it in a field named numbers_int.

...| eval numbers_int=toint(3.14)

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

tomv(<value>)

This function converts a JSON array to a multivalue.

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 <value> argument can be a valid JSON array or the name of a field that contains a valid JSON array.

If the JSON array contains any string values, the tomv function omits the double quotation marks ( " ) that enclose those values.

Basic example

The following example creates an array in the ponies field, converts that array to a multivalue, and then stores the result in a field named mv_ponies:

... | eval ponies = json_array("Buttercup", "Fluttershy", "Rarity"), mv_ponies = tomv(ponies)

The results look like this:

_time mv_ponies ponies
2024-12-10 21:20:18 "Buttercup"

"Fluttershy"
"Rarity"

["Buttercup","Fluttershy","Rarity"]

tonumber(<str>, <base>)

This function converts a string to a number.

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> argument can be a string or the name of a field that contains a string. If the string contains a decimal point ( . ), then the tonumber function converts it to a double. Otherwise, the function converts the string to an integer.

Be aware that integers are supported differently in different product contexts:

  • The Splunk platform supports 53-bit integers with 8 bits of precision. Integers larger than 53 bits are truncated.
  • The Edge Processor and Ingest Processor solutions support 64-bit integers.

The <base> argument is optional. It defines the base of the number in the <value> argument. It defaults to 10, which corresponds to the decimal system. You can set <base> to a number between 2 and 36, inclusive.

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 from the store_sales field to numbers, and then stores the numbers in a field named n. This example uses the default base of 10.

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

toobject(<value>)

This function converts a string to an object.

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 <value> argument can be a string or the name of a field that contains a string. The string must be formatted as a valid JSON object. For more information, see the format described for the object type.

Basic example

The following example converts the string {name: "maria", age:25, status: "full-time"} to a JSON object named employee_record.

... | eval employee_record = toobject("{\"name\": \"maria\", \"age\": 25, \"status\": \"full-time\"}")

The results look like this:

_time employee_record
2024-12-17 19:28:07 {"name":"maria","age":25,"status":"full-time"}

tostring(<value>, <format>)

This function converts a value to a string.

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 <value> argument can be a field name or a value.

If the input value is a Boolean value, the function returns it as a string value with the first letter capitalized. For example, the Boolean value true is converted to the string value "True".

The <format> argument is optional, and it is used only when the <value> argument is a number. The following table describes the supported values for the <format> argument:

Format Description
hex Converts the number to hexadecimal.
commas Formats the number by separating every 3 digits with a comma ( , ). If the number includes a decimal ( . ), the function rounds it to the nearest two decimal places.
duration Interprets the number as representing a number of seconds, and converts it to a time duration using the format D+HH:MM:SS. If the time duration is less than 24 hours, the D+ part of the format is omitted.

Basic examples

Assume that the period field contains the value 615. The following example converts the period field from a number of seconds into a duration of minutes and seconds. The tostring function returns the value 00:10:15 and stores it in a field named period_time.

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

As another example, the following eval command 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
json_array
json_array_to_mv
mv_to_json_array
strptime
Related information
Built-in data types
Last modified on 17 December, 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