Splunk® Cloud Services

SPL2 Search Manual

Acrobat logo Download manual as PDF


Acrobat logo Download topic as PDF

Naming function arguments

When you use a function, you can include the names of the function arguments in your search. Although optional, naming function arguments is especially useful when the function includes arguments that have the same data type.

The function syntax tells you the names of the arguments. Here are a few examples:

round function example
The syntax for this function is:
round(<num>, <precision>)
An example of using this function is this:

...round(2.555, 2)

For someone reading the search, it's not clear what each of the numbers represents. You can clarify that by naming the arguments using the names provided in the syntax.
To name the arguments, you specify this:

...round(num:2.555, precision:2)

if function example
The syntax for this function is:
if(<predicate>, <true_value>, <false_value>)
An example of using this function is this:

... | eval response=if(code=200, "OK", "Error")

To name the arguments, you specify this:

... | eval response=if(predicate:code=200, true_value:"OK", false_value:"Error")

Syntax requirements for naming arguments

When you specify function argument names, you must follow these syntax requirements:

  • Argument names are separated from argument values by a colon ( : ).
  • If an argument can accept a list of values, you must enclose the list in square brackets [ ].
  • Named arguments can appear in any order.
  • You can choose to name only some of the arguments. However, unnamed arguments must appear before unnamed arguments. See Named argument order in this topic

Arguments that accept a list of values

When you use named arguments with a function that accepts a list of values, the values in the list must be separated by commas. If the function uses multiple lists, you must separate each list with a comma and enclose each list inside an array using square brackets [ ].

For example, suppose you have a function that contains two parameters that are lists:

function status($list1, $list2) ...

To specify each list would look something like this:

... status(["Critical", "High", "Medium", "Low"], [1, 2, 3]) 

Naming the arguments would look like this:

... status($list1: ["Critical", "High", "Medium", "Low"], $list2: [1, 2, 3])

Named argument order

If you name all of the arguments, the arguments can appear in any order.

Consider the round function, which has the syntax round(<num>, <precision>). You can specify the named arguments in any order, as shown in these two examples:

...round(num:2.555, precision:2)

...round(precision:2, num:2.555)

If you name only some of the arguments, you must specify the arguments in the syntax order. Unnamed arguments must appear before named arguments.

In this example, the <num> argument is not named but the <precision> argument is named:

...round(2.555, precision:2)

To name the <num> argument, you must also name the <precision> argument.

Named arguments and default values

Most of the built-in functions don't have default values, but it's common for custom functions to have default values. When a function has default values, you can either accept or override the default values.

Named arguments become important when you want to override only some of the default values.

Suppose you have a function that contains a set of parameters with default values

function ranking($a=1, $b=2, $c=3, $d=4) ...

You can override the default values by specifying the replacement values when you invoke the function. In this example, 5 replaces the default value for parameter $a, 6 replaces the default value for parameter $b, and so forth:

...ranking(5, 6, 7, 8)

However, if you only want to override some of the default values, you must name the parameter argument. The arguments not named will use the default values. For example:

...ranking($d=0)

If you don't name the argument, the assumption is that the value you name replaces the first argument in the function. In this example the 0 would replace the $a and the default values are used for the remaining arguments:

...ranking(0)

Additionally, if you name the parameter arguments, you can specify them in any order. For example:

...ranking($c=5, $a=7)

Examples of valid and invalid named arguments

The following table shows examples of valid and invalid syntax for named arguments:

Description Syntax Example
All arguments are named. Valid syntax

... round(num:2.555, precision:2)

... mvrange(start:1, end:11, step:2)

... log(num:64, base:2)

...ltrim(str:" ZZZZabcZZ ", trim_chars:" Z")

Named arguments can be in any order. Valid syntax

... round(num:2.555, precision:2)

... round(precision:2, num:2.555)

Not all arguments are named, but named arguments must come after unnamed arguments. Valid syntax

... round(2.555, precision:2)

... mvrange(1, 11, step:2)

Named arguments cannot come before unnamed arguments Invalid syntax

... round(num:2.555, 2)

... mvrange(start:1, end:11, 2)

A list of values must be treated as an array and enclosed in square brackets [ ]. Invalid syntax

| FROM indexes(patterns: 'data1*', 'data2*') ...

... coalesce(values: clientip, ipaddress)

See also

Related information
Built-in and custom functions
Last modified on 29 October, 2021
PREVIOUS
Built-in and custom functions
  NEXT
Timestamps and time ranges

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


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