---
title: Formulas
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Log Management > Log Explorer > Calculated Fields > Formulas
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Formulas

## Overview{% #overview %}

The formula (or expression) defines the value of the value of the calculated field for each log event. You can reference log attributes, other calculated fields, and supported functions and operators. As you write or edit a formula, the editor automatically suggests relevant fields, functions, and operators.

## Basic syntax and language constructs{% #basic-syntax-and-language-constructs %}

| Construct                                                             | Syntax and Notation                                                                                                 |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Reserved attribute or tag named `tag`                                 | `tag` (no prefix required)For tags containing dashes, escape them with a backslash.Example: `ci\-job\-id`           |
| 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](https://docs.datadoghq.com/logs/explorer/search_syntax.md) applies) |
| Numeric literal (number)For example, `ten`.                           | `10`                                                                                                                |
| Function named `func` with parameters `x` and `y`                     | `func(x, y)`                                                                                                        |
| OperatorFor example, a binary operator `*` with operands `x` and `y`. | `x*y`                                                                                                               |

## Operators{% #operators %}

The available operators in order of precedence:

| Operator             | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `()`                 | A grouping or function call                                              |
| `!`, `NOT`, `-`      | A logical or arithmetic negation                                         |
| `^`, `%`             | Exponentiation, Modulo                                                   |
| `*`, `/`             | 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{% #functions %}

The available functions are categorized as follows:

- Arithmetic
- String
- Logical
- Regex

### Arithmetic{% #arithmetic %}

#### abs(num value)

Returns the absolute value of a number.

{% collapsible-section %}
##### Example

| Example                                                                                 | Formula                                                 | Result             |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------ |
| A log event has the following attributes:- `@client_latency` = 2- `@server_latency` = 3 | `#discrepancy = abs(@client_latency - @server_latency)` | `#discrepancy` = 1 |

{% /collapsible-section %}

#### ceil(num value)

Rounds number up to the nearest integer.

{% collapsible-section %}
##### Example

| Example                                                | Formula                      | Result            |
| ------------------------------------------------------ | ---------------------------- | ----------------- |
| A log event has the following attribute:`@value` = 2.2 | `#rounded_up = ceil(@value)` | `#rounded_up` = 3 |

{% /collapsible-section %}

#### floor(num value)

Rounds number down to the nearest integer.

{% collapsible-section %}
##### Example

| Example                                                 | Formula                         | Result              |
| ------------------------------------------------------- | ------------------------------- | ------------------- |
| A log event has the following attribute:`@value` = 9.99 | `#rounded_down = floor(@value)` | `#rounded_down` = 9 |

{% /collapsible-section %}

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

Finds maximum value amongst a set of numbers.

{% collapsible-section %}
##### Example

| Example                                                                     | Formula                                  | Result              |
| --------------------------------------------------------------------------- | ---------------------------------------- | ------------------- |
| A log event has the following attribute:`@CPU_temperatures` = [-1, 1, 5, 5] | `#highest_temp = max(@CPU_temperatures)` | `#highest_temp` = 5 |

{% /collapsible-section %}

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

Finds the minimum value amongst a set of numbers.

{% collapsible-section %}
##### Example

| Example                                                                     | Formula                                 | Result              |
| --------------------------------------------------------------------------- | --------------------------------------- | ------------------- |
| A log event has the following attribute:`@CPU_temperatures` = [-1, 1, 5, 5] | `#lowest_temp = min(@CPU_temperatures)` | `#lowest_temp` = -1 |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                     | Formula                                | Result                     |
| ----------------------------------------------------------- | -------------------------------------- | -------------------------- |
| A log event has the following attribute:`@value` = -1234.01 | `#rounded_to_tens = round(@value, -1)` | `#rounded_to_tens` = -1230 |

{% /collapsible-section %}

### String{% #string %}

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

Combines multiple values into a single string.

{% collapsible-section %}
##### Example

| Example                                                                             | Formula                                   | Result                      |
| ----------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------- |
| A log event has the following attributes:- `@city` = "Paris"- `@country` = "France" | `#region = concat(@city, ", ", @country)` | `#region` = "Paris, France" |

{% /collapsible-section %}

#### lower(str string)

Converts string to lowercase.

{% collapsible-section %}
##### Example

| Example                                                       | Formula                            | Result                |
| ------------------------------------------------------------- | ---------------------------------- | --------------------- |
| A log event has the following attribute:`@first_name` = "Bob" | `#lower_name = lower(@first_name)` | `#lower_name` = "bob" |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                       | Formula                       | Result              |
| ------------------------------------------------------------- | ----------------------------- | ------------------- |
| A log event has the following attribute:`@price` = "USD10.50" | `#currency = left(@price, 3)` | `#currency` = "USD" |

{% /collapsible-section %}

#### proper(str string)

Converts string to proper case.

{% collapsible-section %}
##### Example

| Example                                                            | Formula                                 | Result                               |
| ------------------------------------------------------------------ | --------------------------------------- | ------------------------------------ |
| A log event has the following attribute:`@address` = "123 main st" | `#formatted_address = proper(@address)` | `#formatted_address` = "123 Main St" |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                                          | Formula                                        | Result                                     |
| -------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------ |
| A log event has the following attribute:`@url` = "www.example.com/path/to/split" | `#url_extraction = split_before(@url, "/", 1)` | `#url_extraction` = "www.example.com/path" |
| `#url_extraction = split_before(@url, "/", 2)`                                   | `#url_extraction` = "www.example.com/path/to"  |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                                          | Formula                                       | Result                              |
| -------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------- |
| A log event has the following attribute:`@url` = "www.example.com/path/to/split" | `#url_extraction = split_after(@url, "/", 0)` | `#url_extraction` = "path/to/split" |
| `#url_extraction = split_after(@url, "/", 1)`                                    | `#url_extraction` = "to/split"                |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                       | Formula                                   | Result                 |
| ------------------------------------------------------------- | ----------------------------------------- | ---------------------- |
| A log event has the following attribute:`@price` = "USD10.50" | `#dollar_value = substring(@price, 2, 2)` | `#dollar_value` = "10" |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                       | Formula                          | Result               |
| ------------------------------------------------------------- | -------------------------------- | -------------------- |
| A log event has the following attribute:`@price` = "USD10.50" | `#cent_value = right(@price, 2)` | `#cent_value` = "50" |

{% /collapsible-section %}

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

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

{% collapsible-section %}
##### Example

| Example                                                                             | Formula                                              | Result                      |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------- | --------------------------- |
| A log event has the following attributes:- `@city` = "Paris"- `@country` = "France" | `#region = textjoin(", ", "false", @city, @country)` | `#region` = "Paris, France" |

{% /collapsible-section %}

#### upper(str string)

Converts string to uppercase.

{% collapsible-section %}
##### Example

| Example                                                        | Formula                            | Result                |
| -------------------------------------------------------------- | ---------------------------------- | --------------------- |
| A log event has the following attribute: `@first_name` = "Bob" | `#upper_name = upper(@first_name)` | `#upper_name` = "BOB" |

{% /collapsible-section %}

### Logical{% #logical %}

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

Evaluates a condition and returns a value accordingly.

{% collapsible-section %}
##### Example

| Example                                                                                             | Formula                                             | Result             |
| --------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------ |
| A log event has the following attributes:- `@location` = "Paris, France"- `@home` = "New York, USA" | `#abroad = if(@location == @home, "false", "true")` | `#abroad` = "true" |

{% /collapsible-section %}

#### is_null(expr value)

Checks if an attribute or expression is null.

{% collapsible-section %}
##### Example

| Example                                                                             | Formula                                  | Result |
| ----------------------------------------------------------------------------------- | ---------------------------------------- | ------ |
| A log event has the following attributes:- `@users_online` = 5- `@max_capacity` = 0 | `is_null(@users_online / @max_capacity)` | "true" |

{% /collapsible-section %}

### Regex{% #regex %}

Regex functions match or transform a value using a regular expression (regex). Patterns support the same regex constructs as [regex extraction](https://docs.datadoghq.com/logs/explorer/calculated_fields/extractions.md#regex), such as literals, character classes, and quantifiers. The same [pattern performance](https://docs.datadoghq.com/logs/explorer/calculated_fields/extractions.md#pattern-performance) guidance applies. Unlike extraction, capture groups in formula patterns do not need a name.
Formula arguments are double-quoted string literals, so a literal backslash must be written as two backslashes. For example, to match the digit shorthand class, write `"\\d"` in the pattern. The same rule applies to the replacement string: to insert a literal dollar sign rather than a group reference, write `"\\$"`.
#### regexp_like(str value, str pattern)

Returns `true` when the pattern matches anywhere in the value, and `false` otherwise.

{% collapsible-section %}
##### Example

| Example                                                                            | Formula                                                           | Result                 |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------- |
| A log event has the following attribute:`message` = "connection timeout after 30s" | `#is_timeout = regexp_like(message, "timeout|deadline exceeded")` | `#is_timeout` = "true" |

{% /collapsible-section %}

#### regexp_replace(str input, str pattern, str replacement, [int start, int N])

Returns `input` with matched text replaced. Use `$1` through `$9` in `replacement` to insert a capture group's match, or `${name}` for a named group.

| Argument      | Meaning                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------- |
| `input`       | The text to transform                                                                         |
| `pattern`     | The regex pattern to match                                                                    |
| `replacement` | The regex transformation pattern, often using capture groups                                  |
| `start`       | Optional. The zero-based character index to begin matching from. Defaults to `0`              |
| `N`           | Optional. The maximum number of matches to replace. Defaults to `1`. `0` replaces every match |

{% collapsible-section %}
##### Example

| Example                                                            | Formula                                                          | Result                 |
| ------------------------------------------------------------------ | ---------------------------------------------------------------- | ---------------------- |
| A log event has the following attribute:`@path` = "/api/v1/orders" | `#resource = regexp_replace(@path, "^/api/v[0-9]+/(.*)$", "$1")` | `#resource` = "orders" |

{% /collapsible-section %}

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Calculated Fields](https://docs.datadoghq.com/logs/explorer/calculated_fields.md)