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. Below are a few examples.

The following example uses the round function to show how to name function arguments. The syntax for this function is:
CODE 
round(<num>, <precision>)
Here's an example of using the round function without naming the arguments. It is not explicitly clear which value is the number and which is the precision.
CODE 
...round(2.555, 2)
To make it explicit, you can name the function arguments, as shown in this example:
CODE 
...round(num:2.555, precision:2)

The following example uses the if function to show how to name function arguments. The syntax for this function is:

CODE 
if(<predicate>, <true_value>, <false_value>)
Here's an example of using the if function without naming the arguments. It is not explicitly clear which is the value to return when the predicate evaluates to true or false.
CODE 
... | eval response=if(code=200, "OK", "Error")
To make it explicit, you can name the function arguments, as shown in this example:
CODE 
... | 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 2 parameters that are lists:

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

To specify each list looks something like this:

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

Naming the arguments looks like this:

CODE 
... 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 2 examples:

CODE 
...round(num:2.555, precision:2)
CODE 
...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:

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

JAVASCRIPT 
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:

CODE 
...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:

CODE 
...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:

CODE 
...ranking(0)

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

CODE 
...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
CODE 
... round(num:2.555, precision:2)
CODE 
... mvrange(start:1, end:11, step:2)
CODE 
... log(num:64, base:2)
CODE 
...ltrim(str:"   ZZZZabcZZ ", trim_chars:" Z")
Named arguments can be in any order. Valid syntax
CODE 
... round(num:2.555, precision:2)
CODE 
... round(precision:2, num:2.555)
Not all arguments are named, but named arguments must come after unnamed arguments. Valid syntax
CODE 
... round(2.555, precision:2)
CODE 
... mvrange(1, 11, step:2)
Named arguments cannot come before unnamed arguments Invalid syntax
CODE 
... round(num:2.555, 2)
CODE 
... mvrange(start:1, end:11, 2)
A list of values must be treated as an array and enclosed in square brackets [ ]. Invalid syntax
CODE 
| FROM indexes(patterns: 'data1*', 'data2*') ...
CODE 
... coalesce(values: clientip, ipaddress)