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"

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:

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:

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:

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:

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.

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.

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

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

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

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

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.

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:

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.

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:

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:

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)

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)

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:

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:

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

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 in the SPL2 Search Manual.

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:

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:

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