Required arguments

Optional arguments

Using functions in modules

You create custom eval functions in an SPL2 module. You can use a custom function multiple times within that module. Custom functions can also be imported into other modules.

Using functions in the API

You can also create custom functions using the Search Service API.

1. A function with a simple return expression

This example shows how to use a custom function with a simple expression.

This example returns error codes that are greater than or equal to 400. The custom function is called isError and returns a Boolean value. A parameter is defined, called $code, which has an input data type of number. There is no SPL statement in this example. The expression for this function returns results only when the value of the $code parameter is greater than or equal to 400.

function isError($code : number) : boolean {
  return $code >= 400 
}

This example invokes the function in the WHERE clause of the from command:

| FROM jsondata WHERE method="GET" AND isError(status_code)

In this example, the isError function is used as a filter in the WHERE clause of a from command. The status_code field is the value used for the $code parameter.

As the events from the jsondata dataset are read, the events are filtered by the WHERE clause. Only the events that have a method field with a value of GET and have an error status code of 400 or greater are returned.

Suppose the following events are in the jsondata dataset:

When the search is run with the custom eval function, the following results are returned:

2. Using and overriding a default value

This example shows how to specify a default value in a custom function and override that default value.

Suppose you want to create a custom function that combines the built-in if and round functions. You want to take the values in a field and round the values to a specific number of decimal points, but only if the number is greater than 1.

Start by creating some sample data. You can use a dataset literal like this:

$sample = FROM [{score: 2.345678},{score: 0.1234},{score: 1.0076543}] 

Next, combine the functions that you want to use explicitly. For example, if you want to apply the function to the score field, this would be the function expression:

if(score>1, round(score, 2), score) 

Then test your explicit function expression against the sample data:

$function_test1 = FROM $sample SELECT score, if(score>1, round(score, 2), score)  as newscore

You can convert the explicit function expression into a custom function, which includes a default value for $precision:

function roundIf($field:int, $precision:number=2): int {
  return if($field>1, round($field, $precision), $field) 
}

Now you're ready to test the function. Notice this search doesn't specify a precision. It uses the default $precision in the function.

$function_test2 = FROM $sample SELECT score, roundIf(score) as newscore

You can override the default $precision by specifying a different precision in your search. For example:

$function_test2 = FROM $sample SELECT score, roundIf(score, 4) as newscore

3. Reusing a custom function

You can use your custom eval functions in multiple searches within the same SPL module. To use a custom function in another SPL module, you must export the custom function.

This custom function, isError, is identical to the custom function described in example 1.

This custom function is used in three different searches:

function isError($code : number) : boolean {
  return $code >= 400 
}

| FROM jsondata WHERE method="GET" AND isError(status_code)

| FROM jsondata WHERE isError(status_code)
| stats count(method) BY status_code, method

| FROM main WHERE isError(status_code)
| stats (earliest_time(_time)) AS 'First Instance'
| eval 'First Instance'=strftime('First Instance', "%Y-%m-%d %H:%M:%S")

First search

This search returns events where the method is GET and the values in the status_code field are equal to or greater than 400:

FROM jsondata WHERE method="GET" AND isError(status_code)

Second search

This search returns events where the values in the status_code field are equal to or greater than 400. The search then counts the values in the method field and organizes the results by the values in the status_code field and the method field.

FROM jsondata WHERE isError(status_code)
| stats count(method) BY status_code, method

The results look something like this:

Third search

This search returns events from a different dataset where the values in the status_code field are equal to or greater than 400. The search returns the time from the earliest event in the search results, which is the first occurrence of the 4xx status codes for the time range specified. The field returned is renamed First Instance. Because the earliest_time function returns a UNIX time, the strftime eval function is used to change the time into a human-readable time format.

FROM main WHERE isError(status_code)
|stats (earliest_time(_time)) AS 'First Instance'
|eval 'First Instance'=strftime('First Instance', "%Y-%m-%d %H:%M:%S")

The results look something like this: