Splunk® Data Stream Processor

Function Reference

Acrobat logo Download manual as PDF


DSP 1.2.0 is impacted by the CVE-2021-44228 and CVE-2021-45046 security vulnerabilities from Apache Log4j. To fix these vulnerabilities, you must upgrade to DSP 1.2.4. See Upgrade the Splunk Data Stream Processor to 1.2.4 for upgrade instructions.

On October 30, 2022, all 1.2.x versions of the Splunk Data Stream Processor will reach its end of support date. See the Splunk Software Support Policy for details.
Acrobat logo Download topic as PDF

Conditional

case(condition, value, ...)

This function takes pairs of <condition> and <value> arguments and returns the first value for which the condition evaluates to TRUE. The condition arguments are Boolean expressions that are evaluated from first to last. When the first condition expression is encountered that evaluates to TRUE, the corresponding value argument is returned. The function returns NULL if none of the condition arguments are true.

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

Function Input
condition: boolean expression
value: T
Function Output
type: T
This function outputs the value which can be of any specific data type T.

SPL2 example

The following example returns descriptions for the corresponding HTTP status code.

... | eval description=case(status == 200, "OK", status ==404, "Not found", status == 500, "Internal Server Error");

Alternatively, you can use named arguments.

... | eval description=case(conditions: [source=200, "OK", source=400, "Not found", source=500, "Internal Server Error"]);

The outgoing data looks something like this:

status description
200 OK
200 OK
408
200 OK
404 Not found
200 OK
406
500 Internal Server Error
200 OK

Specifying a default value

In the above example, the description column is empty for status=406 and status=408.

To display a default value when the status does not match one of the values specified, use the literal true. For example:

... | eval description=case(status == 200, "OK", status ==404, "Not found", status == 500, "Internal Server Error", true, "Other");

The outgoing data will then contain the word Other for status=406 and status=408.

cidrmatch(cidr_range, ip)

Returns TRUE or FALSE based on whether an IPv4 address matches an IPv4 CIDR notation. Use this function to determine if an IPv4 address belongs to a particular subnet. This function returns TRUE, when the IP address ip belongs to a particular subnet cidr. Both ip and cidr are string arguments, where cidr is the CIDR subnet and ip is the IP address to match with the subnet. IPv6 is not supported.

Function Input
cidr_range: String
ip: String
Function Output
String

SPL2 example

The following example uses the cidrmatch function as a filter to remove events that do not match the IP address.

When working in the SPL View, you can write the function by using the following syntax.

... | where cidrmatch("10.0.0.0/8", "123.123.12.1");

Alternatively, you can use named arguments to list the arguments in any order.

... | where cidrmatch(ip: "123.123.12.1", cidr_range: "10.0.0.0/8");

coalesce(values)

This function takes a variable number of arguments and returns the first value that is not NULL.

Function Input
values: collection<R>
Function Output
R

SPL2 example

Suppose you have a set of records where the IP address is extracted to either host or ipaddress. This example defines a new field called ip, that takes the value of either the host field or ipaddress field, depending on which field is not NULL (does not exist in that record). If both the host and ipaddress field exist in the record, this function returns the first argument, the host field.

When working in the SPL View, you can write the function by using the following syntax.

...| eval ip=coalesce("host", "ipaddress");

Alternatively, you can use named arguments.

...| eval ip=coalesce(values: ["host", "ipaddress"]);

if(predicate, then, else)

Assigns an expression if the value is true, and another expression if the value is false.

Function Input
predicate: boolean
then: T
else: T
Function Output
type: T

SPL2 example

If the value of the kind field is event, then send the record to the index called main. If the value of the kind field is not event, then send the record to the index called metrics.

When working in the SPL View, you can write the function by using the following syntax.

...| into index("", if(kind="event", "main", "metrics"));

Alternatively, you can use named arguments to list the arguments in any order.

...| into index("", if(predicate: kind="event", then: "main", else: "metrics"));

in(value, test_values)

This function returns TRUE if one of the values in the list matches a value in the field you specify. This function also accepts map and list arguments, as shown in the SPL2 example below. This function accepts a variable number of arguments. Use this scalar function with the Eval or Where streaming functions.

The following syntax is supported:

...| where in(field,"value1","value2", ...)
...| where field in("value1","value2", ...)
...| eval new_field=if(in(field,"value1","value2", ...), "value-if_true","value-if-false")

The eval function cannot accept a Boolean value. You must specify the IN function inside the IF function, which can accept a Boolean value as input.

The string values must be enclosed in quotation marks. You cannot specify wildcard characters with the values to specify a group of similar values, such as HTTP error codes or CIDR IP address ranges. Use the IN operator instead.

Function Input
value: any
test_values: collection<any>
Function Output
boolean

1. SPL2 example

The following example uses the in function as the first parameter for the if function. The evaluation expression returns TRUE if the value in the status field matches one of the values in the list.

When working in the SPL View, you can write the function by using the following syntax.

...| eval error=if(in(status, "error", "failure", "severe"),"true","false");

2. SPL2 example

The following example uses the where function to return TRUE if one of the values in the status_code field matches one of the values in the list.

When working in the SPL View, you can write the function by using the following syntax.

...| where in("status_code", ["400", "401", "403", "404"]);

3. SPL2 example

The following example uses the eval function to return true if the nested index field in attributes contains the value _internal or _metrics.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n=if(in(map_get(attributes, "index"), "_internal", "_metrics"), "true", "false");

4. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

...| where in(test_values: ["400", "401", "403", "404"], value: "status_code");

like(text, pattern)

This function takes two arguments, a string to match (text) and a string expression to match (pattern). It returns TRUE if text matches pattern. The pattern language supports an exact text match, as well as percent ( % ) characters for wildcards and underscore ( _ ) characters for a single character match. Use this scalar function with the Eval or Where streaming functions.

Because "_" is a special character for this function, the string you want to match cannot contain "_". To match a string containing "_", use the IN function instead.

Function Input
input: string
pattern: string
Function Output
boolean

SPL2 example

The following example uses the where function to return like=TRUE if the host field starts with the value 198. The percent ( % ) symbol is a wildcard for the like function.

When working in the SPL View, you can write the function by using the following syntax.

... | where like(host, "198.%");

Alternatively, you can use named arguments to list the arguments in any order.

... | where like(pattern: "198.%", input: host);

nullif('left', 'right')

Compare two fields, 'left' and 'right', and returns NULL if left = right. Use this scalar function with the Eval or Where streaming functions.

Function Input
'left': T
'right': any
Function Output
T

SPL2 example

The following example returns NULL if fieldA=fieldB. Otherwise the function returns fieldA.

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=nullif(fieldA,fieldB);

Alternatively, you can use SPL2 named arguments to list the arguments in any order.

...| eval n=nullif('left': fieldB, 'right': fieldA);

In SPL2, left and right are reserved keywords so they have to be enclosed in single quotation marks ( ' ).

validate(tests_and_values)

This function takes pairs of arguments, Boolean expressions specifying certain conditions and strings indicating that the conditions are not met. The function returns the string corresponding to the first expression that evaluates to FALSE. If all evaluate to TRUE, this function returns NULL. Use this scalar function with the Eval, Where, or Select streaming functions.

Function Input
tests_and_values: collection<union<boolean, string>>
Function Output
string

SPL2 example

The following example runs a simple check for valid ports in the range of 1-65535 inclusively.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n=validate(port >= 1 AND port <= 65535, "ERROR: Port is out of range");

Alternatively, you can use named arguments.

... | eval n=validate(tests_and_values: [port >= 1 AND port <= 65535, "ERROR: Port is out of range"]);
Last modified on 22 February, 2022
PREVIOUS
Casting
  NEXT
Conversion

This documentation applies to the following versions of Splunk® Data Stream Processor: 1.2.0, 1.2.1-patch02, 1.2.1, 1.2.2-patch02, 1.2.4, 1.2.5, 1.3.0, 1.3.1, 1.4.0, 1.4.1, 1.4.2, 1.4.3


Was this documentation topic helpful?


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