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