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

# Write your first formula

> Learn formula envelopes, functions, literals, nesting, and comments.

A formula is an expression made from values, field references, functions, and operators.

## Formula envelopes

Use a `${...}` envelope when a formula is embedded in calculated text:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Order total: ${Format([Quantity] * [Unit Price], "0.00")}
```

A field that expects only an expression can also accept the expression without the envelope:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Round([Quantity] * [Unit Price], 0.01)
```

Use `={...}` for a nested sub-expression in places that require the explicit subformula form:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
${Concat("Total: ", ={Format([Quantity] * [Unit Price], "0.00")})}
```

## Call a function

Write the function name, then place its inputs inside parentheses:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Upper([Customer Name])
```

Separate multiple inputs with commas:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Between([Temperature], 2, 8)
```

Function names are case-sensitive. Write `Len(...)`, not `len(...)`.

## Nest functions

The result of one function can be passed into another:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
If(IsNull([Customer Name]), "Unnamed customer", Proper(Trim([Customer Name])))
```

`If` and `Case` evaluate only the branch that is selected. This is useful when an unused branch would require data that may not exist.

## Write literal values

| Value       | Example                           |
| ----------- | --------------------------------- |
| Text        | `"Ready"` or `'Ready'`            |
| Number      | `12.5`                            |
| Boolean     | `true` or `false`                 |
| Empty value | `null`                            |
| Date        | `#2026-08-31#`                    |
| Time        | `#14:30:00#`                      |
| Timestamp   | `#2026-08-31T12:30:00Z#`          |
| Duration    | `2w`, `3d`, `4h`, `30m`, or `15s` |

Escape `\n`, `\r`, `\t`, `\\`, `\'`, or `\"` inside text when needed.

## Add a comment

`//` starts a comment that continues to the end of the line:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Round([Amount], 0.01) // Keep two decimal places
```

## Next step

Connect the expression to form data with [values and references](/getting-started/values-and-references), then use the [formula index](/reference) to choose a function.