 Download topic as PDF

# Mathematical functions

The following list contains the functions that you can use to perform mathematical calculations.

• For information about using string and numeric fields in functions, and nesting functions, see Overview of SPL2 eval functions.
• For the list of mathematical operators you can use with these functions, see the "Operators" section in eval command usage.

## abs(<num>)

This function returns the absolute value of a number.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example creates a field called `absnum`, whose values are the absolute values of the numeric field `number`.

`... | eval absnum=abs(number)`

The following example uses the `abs` function in a WHERE clause. In this example, the values in the `mydata` field are greater than the absolute value of the numeric literal `-10.95`.

`... WHERE mydata>abs(-10.95)`

## ceiling(<num>) or ceil(<num>)

This function rounds a number up to the next highest integer.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

You can use the abbreviation `ceil(<num>)` instead of the full name of the function.

### Basic example

The following example returns `n=2`.

`... | eval n=ceil(1.9)`

## exact(<expression>)

This function returns the result of a numeric eval calculation with a larger amount of precision in the formatted output.

### Usage

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

### Example

Calculates the circumference of a set of circles by multiplying `pi` by the values in the `diameter` field.

`... | eval n=exact(3.14 * diameter)`

## exp(<num>)

This function returns the exponential function `eX` of a number.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example returns y=e3.

`... | eval y=exp(3)`

## floor(<num>)

This function rounds a number down to the nearest whole integer.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example returns 1.

`... | eval n=floor(1.9)`

## ln(<num>)

This function returns the natural logarithm of a number.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example returns the natural logarithm of the values in the `bytes` field.

`... | eval lnBytes=ln(bytes)`

## log(<num>,<base>)

This function returns the logarithm of a number using a base. The base is optional, and if omitted the `log` function uses base 10.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example returns the logarithm of the values of the `number` field, using base 2.

`... | eval num=log(number,2)`

The following example returns the logarithm of the numeric literal `100000`, using base 10.

`... | eval num=log(100000,10)`

## pi()

This function takes no arguments and returns the constant '`pi` to 11 digits of precision.

### Usage

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

### Basic example

The following example calculates the area of a circle, which is `pi()` multiplied by the radius to the power of 2.

`... | eval area_circle=pi()*pow(radius,2)`

## pow(<num>, <exp>)

This function returns a number to the power of the exponent.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example calculates the area of a circle, which is pi() multiplied by the radius to the power of 2.

`... | eval area_circle=pi()*pow(radius,2)`

## round(<num>, <precision>)

This function returns a number rounded to the decimal places specified by the precision. The precision is optional, and if omitted the `round` function rounds to an integer.

You cannot specify a negative number for the precision.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic examples

#### Specifying a value without precision

The following example returns `n=4`. Because a `<precision>` is not specified, the number is rounded to the integer.

`... | eval n=round(3.5)`

This search returns `n=3`.

#### Specifying a value and a precision

The following example returns `n=2.56`.

`... | eval n=round(2.555, 2)`

## sigfig(<num>)

This function rounds a number to the appropriate number of significant figures.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

#### How sigfig is computed

The computation for `sigfig` is based on the type of calculation that generates the number.

• For multiplication and division, the result should have the minimum number of significant figures of all of the operands.
• For addition and subtraction, the result should have the same number of decimal places as the least precise number of all of the operands.

For example, the numbers 123.0 and 4.567 contain different precision with the decimal places. The first number is less precise because it has 1 decimal place. The second number is more precise because it has 3 decimal places.

If the calculation is 123.0 + 4.567 = 127.567, then the `sigfig` function returns the fewest number of decimal places. In this example only one decimal place is returned. Because the number to the right of the last significant figure is greater than 5, the result returned is 127.6

### Examples

Example 1: The following example shows how the `sigfig` function works. The calculation `1.00*1111` returns the value `n=1111`, but the following search using the `sigfig` function returns `n=1110`.

`... | eval n=sigfig(1.00*1111)`

In this example, 1.00 has 3 significant figures and 1111 has 4 significant figures. In this example, the minimum number of significant figures for all operands is 3. Using the `sigfig` function, the final result is rounded to 3 digits, returning n=1110 and not 1111.

Example 2: There are situations where the results of a calculation can return a different accuracy to the very far right of the decimal point. For example, the following search calculates the average of 100 values:

```| makeresults count=100 | eval test=3.99 | stats avg(test)```

The result of this calculation is:

avg(test)
3.9900000000000055

When the count is changed to 10000, the results are different:

```| makeresults count=10000 | eval test=3.99 | stats avg(test)```

The result of this calculation is:

avg(test)
3.990000000000215

This occurs because numbers are treated as double-precision floating-point numbers.

To mitigate this issue, you can use the `sigfig` function to specify the number of significant figures you want returned.

However, first you need to make a change to the `stats` command portion of the search. You need to change the name of the field `avg(test)` to remove the parenthesis. For example `stats avg(test) AS test`. The `sigfig` function expects either a number or a field name for X. The `sigfig` function cannot accept a field name that looks like another function, in this case `avg`.

To specify the number of decimal places you want returned, you multiply the field name by 1 and use zeros to specify the number of decimal places. If you want 4 decimal places returned, you would multiply the field name by 1.0000. To return 2 decimal places, multiply by 1.00, as shown in the following example:

```| makeresults count=10000 | eval test=3.99 | stats avg(test) AS test | eval new_test=sigfig(test*1.00)```

The result of this calculation is:

test
3.99

## sqrt(<num>)

This function returns the square root of a number.

### Usage

The `<num>` argument can be the name of a numeric field or a numeric literal.

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

### Basic example

The following example returns 3:

`... | eval n=sqrt(9)`

Function information
Quick Reference for SPL2 eval functions
Overview of SPL2 eval functions
Naming function arguments in the SPL2 Search Manual