> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculated Field Syntax

> Syntax rules, operators, and supported value types for calculated field formulas in Honeycomb Datasets and Environments.

An expression performs functions, and mathematical and/or logical operations on other primitives and field's values to return a result; similar to expressions in a spreadsheet.

You can use various functions in Calculated Field formulas.
Functions operate within the context of a single event, meaning that each function takes field values from an event and produces a new Calculated Field attached to that event.

## Field names

Reference fields, or columns, by prefixing their name with a dollar sign `$`.

```c theme={}
$durationMs
```

Field names that start with a number or contain spaces must be enclosed in double quotes `"`.

```c theme={}
$"1stToken"
$"Context Key Length"
```

## Literals

```ruby theme={}
"a string"      # string
`raw string`    # raw string
10              # integer
-3              # negative integer
12.02           # float
-4.82           # negative float
4e+2            # scientific E notation
4e-2            # scientific E notation
true            # boolean
false           # boolean
null            # null
```

### Strings

String literals are enclosed in double quotes (`"a string"`) and support interpretation.
Special characters are escaped with a backslash `\`.

Within the quotes, any character may appear except newline (`"\n"`) and unescaped double quote (`"\\"`) which require the use of the backslash character.

### Raw strings

Raw string literals are enclosed in single back ticks (`` `a raw string` ``).
Within the quotes, any character may appear except a back quote.
This is useful for expression of text that use the backslash character.
For example, file paths and regular expressions.

### Integers and floating point numbers

Positive or negative whole numbers or floating point numbers. [E notation style](https://en.wikipedia.org/wiki/Scientific_notation#E_notation) numbers are also supported.

```ruby theme={}
10              # integer
-3              # negative integer
12.02           # float
-4.82           # negative float
1.5e2           # scientific E notation
1.5e+2          # scientific E notation
1.5e-2          # scientific E notation
```

### Booleans

A truthy value represented with `true` and false `false`.

### Null

An empty, missing value represented with `null`.

## Operators

Calculated fields support infix arithmetic, logical, and comparison operators.

Add spaces around infix operators, otherwise your expression may not evaluate how you expect.
For example:

* `$column+5` returns the value of a field named `column+5`.
* `$column + 5` returns the sum of five and the `column` field's value.

### Arithmetic operators

```txt theme={}
+       sum
-       subtraction
*       multiplication
/       division
%       modulo
```

Sum, subtraction, multiplication, division, and modulo infix operators are supported.

| Operator syntax | Equivalent function |
| --------------- | ------------------- |
| `$a + $b`       | `SUM($a, $b)`       |
| `$a - $b`       | `SUB($a, $b)`       |
| `$a * $b`       | `MUL($a, $b)`       |
| `$a / $b`       | `DIV($a, $b)`       |
| `$a % $b`       | `MOD($a, $b)`       |

### Comparison operators

```txt theme={}
=       equal
!=      not equal
<       less than
<=      less than or equal
>       greater
>=      greater than or equal
```

| Operator syntax | Equivalent function   |
| --------------- | --------------------- |
| `$a = $b`       | `EQUALS($a, $b)`      |
| `$a != $b`      | `NOT(EQUALS($a, $b))` |
| `$a < $b`       | `LT($a, $b)`          |
| `$a <= $b`      | `LTE($a, $b)`         |
| `$a > $b`       | `GT($a, $b)`          |
| `$a >= $b`      | `GTE($a, $b)`         |

### Logical operators

```txt theme={}
AND     conditional AND
OR      conditional OR
!       NOT
```

Infix operators for conditional AND, conditional OR, and logical NOT.

| Operator syntax      | Equivalent function |
| -------------------- | ------------------- |
| `$a AND $b`          | `AND($a, $b)`       |
| `$a OR $b`           | `OR($a, $b)`        |
| `!$a` (also `!($a)`) | `NOT($a)`           |

## Functions

A function's name is all-capitalized.
Function arguments (if any) are enclosed in parenthesis.
Field names, literal values, and other functions are valid function arguments.

```ruby theme={}
SUM(1.0, 5, "2.3")

MUL(100, DIV($json_decode_ms, $total_ms))
```