# Calculated Fields Expression Language

##### Join the Beta!

Calculated Fields is in beta. Have feedback or a feature request? Let us know.

## Basic syntax and language constructs

ConstructSyntax and Notation
Reserved attribute or tag named `tag``tag` (no prefix required)
Attribute named `attr``@attr` (use an `@` prefix)
Calculated field named `field``#field` (use a `#` prefix)
String literal (quote)
For example, `text` or `Quoted "text"`.
`"text"`
`"Quoted \"text\""`
(Log Search Syntax applies)
Numeric literal (number)
For example, `ten`.
`10`
Function named `func` with parameters `x` and `y``func(x, y)`
Operator
For example, a binary operator `*` with operands `x` and `y`.
`x*y`

## Operators

The available operators in order of precedence:

OperatorDescription
`()`A grouping or function call
`!`, `NOT`, `-`A logical or arithmetic negation
`*`, `/`Multiplication, division
`+`, `-`Addition, subtraction
`<`, `<=`, `>`, `>=`Less than, less than or equal to, greater than, greater than or equal to
`==`, `!=`Match, does not match
`&&`, `AND`Logical AND
`||`, `OR`Logical OR

## Functions

The available functions are categorized as follows:

### Arithmetic

#### abs(num value)

Returns the absolute value of a number.

Example
A log event has the following attributes:
- `@client_latency` = 2
- `@server_latency` = 3

Formula: abs(`@client_latency`-`@server_latency`)
Result: 1

#### ceil(num value)

Rounds number up to the nearest integer.

Example
A log event has the following attribute: `@value`=2.2

Formula: ceil(`@value`)
Result: 3

#### floor(num value)

Rounds number down to the nearest integer.

Example
A log event has the following attribute: `@value`=9.99

Formula: floor(`@value`)
Result: 9

#### max(num value [, num value, …])

Finds maximum value amongst a set of numbers.

Example
A log event has the following attribute: `@list_of_values`=[-1, 1, 5, 5]

Formula: max(`@list_of_values`)
Result: 5

#### min(num value [, num value, …])

Finds the minimum value amongst a set of numbers.

Example
A log event has the following attribute: `@list_of_values` = [-1, 1, 5, 5]

Formula: min(`@list_of_values`)
Result: -1

#### round(num value, int precision)

Rounds a number. Optionally, define how many decimal places to maintain.

Example
A log event has the following attribute: `@randInt` = -1234.01

Formula: round(`@randInt`, -1)
Result: -1230

### String

#### concat(str value [, expr value, …])

Combines multiple values into a single string.

Example
A log event has the following attributes:
- `@first_name` = "Bob"
- `@last_name` = "Smith"

Formula: concat(`@first_name`, `@last_name`)
Result: "Bob Smith"

#### lower(str string)

Converts string to lowercase.

Example
A log event has the following attribute: `@first_name` = "Bob"

Formula: lower(`@first_name`)
Result: "bob"

#### prefix(str string, int num_chars)

Extracts a portion of text from the beginning of a string.

Example
A log event has the following attribute: `@country`="Canada"

Formula: upper(prefix(`@country`, 3))
Result: "CAN"

#### proper(str string)

Converts string to proper case.

Example
A log event has the following attribute: `@name` = "bob SMITH"

Formula: proper(`@name`)
Result: "Bob Smith"

#### split_before(str string, str separator, int occurrence)

Extracts the portion of text preceding a certain pattern in a string.

Example
A log event has the following attribute: `@row_value` = "1,Bob,Smith"

Formula: split_before(`@row_value`, ",")
Result: "1"

#### split_after(str string, str separator, int occurrence)

Extracts the portion of text following a certain pattern in a string.

Example
A log event has the following attributes: `@row_value` = "1,Bob,Smith"

Formula: split_after(`@row_value`, ",", 2)
Result: "Smith"

#### substring(str string, int start, int end)

Extracts a portion of text from the middle of a string.

Example
A log event has the following attributes: `@row_value` = "1,Bob,Smith"

Formula: substring(`@row_value`, 3, 3)
Result: "Bob"

#### suffix(str string, int num_chars)

Extracts a portion of text from the end of a string.

Example
A log event has the following attributes: `@url` = "www.datadoghq.com"

Formula: suffix(`@url`, 4)
Result: ".com"

#### textjoin(str delimiter, expr value [, expr value, …])

Combines multiple values into a single string with a delimiter in between.

Example
A log event has the following attributes:
- `@first_name` = "Bob"
- `@last_name` = "Smith"

Formula: textjoin(", ", `@last_name`, `@first_name`)
Result: "Smith, Bob"

#### upper(str string)

Converts string to uppercase.

Example
A log event has the following attributes: `@first_name` = "Bob"

Formula: upper(`@first_name`)
Result: "BOB"

### Logical

#### case(expr condition, expr value_if_true [, expr condition, expr value_if_true …], expr value_else)

Evaluates a series of conditions and returns a value accordingly.

#### if(expr condition, expr if_true, expr if_false)

Evaluates a condition and returns a value accordingly.

Example
A log event has the following attributes:
- `@origin_country` = "USA"
- `@destination_country` = "Canada"
- `@origin_continent` = "NA"
- `@destination_continent` = "NA"

Formula: if(`@origin_country` == `@destination_country`, "national", if(`@origin_continent` == `@destination_continent`, "continental", "intercontinental"))
Result: "continental"

#### is_null(expr value)

Checks if an attribute or expression is null.

Example
A log event has the following attributes:
- `@users_online` = 5
- `@max_capacity` = 0

Formula: is_null(`@users_online` / `@max_capacity`)
Result: TRUE