Skip to content
Henceforth Docs

Formula Language

The Henceforth formula language is a small expression DSL for defining derived field values. A formula is an expression that references other fields on the same object and evaluates to a scalar value. The compiler lowers formula expressions to SQL and embeds them in virtual generated columns.

Syntax Overview

Section titled “Syntax Overview”

A formula is an expression, not a statement. It produces a single value. There are no assignments, loops, or side effects.

firstName & ' ' & lastName

This expression concatenates three values: the firstName field, a space literal, and the lastName field. The & operator is null-safe string concatenation.

Field References

Section titled “Field References”

Field references use the fieldKey (camelCase) of another field on the same object:

firstName
lastName
active
amount

Rules:

  • Field references are case-sensitive. firstName and FirstName are different references.
  • References to scalar fields only – formula fields cannot reference other formula fields or themselves.
  • Lookup traversal (e.g., account.name) is not supported. See Capability Roadmap for cross-object formulas.

Operators

Section titled “Operators”
Category Operators Notes
Arithmetic +, -, *, / Standard numeric operations.
Comparison =, !=, <, <=, >, >= Return boolean.
Boolean &&, ||, ! Short forms.
Boolean (keyword) and, or, not Case-insensitive keyword equivalents of &&, ||, !.
Text & Null-safe string concatenation.

Functions

Section titled “Functions”

Function names are case-insensitive.

if(condition, thenValue, elseValue)

Section titled “if(condition, thenValue, elseValue)”

Evaluates condition and returns thenValue if true, elseValue if false.

if(active, "Active", "Inactive")

Compiles to a SQL searched CASE:

CASE WHEN "active" THEN 'Active' ELSE 'Inactive' END

case(expr, match1, result1, match2, result2, ..., default)

Section titled “case(expr, match1, result1, match2, result2, ..., default)”

Compares expr against each matchN value and returns the corresponding resultN. If no match is found, returns default (the last argument).

case(status, "new", "New Lead", "closed", "Closed Deal", "Unknown")

Compiles to a SQL simple CASE:

CASE "status"
  WHEN 'new' THEN 'New Lead'
  WHEN 'closed' THEN 'Closed Deal'
  ELSE 'Unknown'
END

Literals

Section titled “Literals”
Type Syntax Examples
String Double quotes "hello", "New Lead"
Integer Bare digits 0, 42, -1
Decimal Digits with dot 3.14, -0.5
Boolean Keywords true, false

Null Behavior

Section titled “Null Behavior”

The & (text concatenation) operator treats null inputs as empty strings. This makes it suitable for display-style concatenation where missing values should not produce null output:

firstName & " " & lastName

If firstName is null, the result is " Smith" rather than null.

Arithmetic and comparison operators follow standard SQL null propagation – any operation involving null produces null.

Compilation

Section titled “Compilation”

A formula compiles to a virtual generated column. The formula expression is lowered to a SQL expression that uses the snake_case column names of the referenced fields:

Formula SQL expression
firstName & ' ' & lastName COALESCE("first_name", '') || ' ' || COALESCE("last_name", '')
if(active, "Yes", "No") CASE WHEN "active" THEN 'Yes' ELSE 'No' END
amount * 0.1 "amount" * 0.1

When indexed: true on the formula field, the compiler creates an expression index using the same SQL expression.

See Also

Section titled “See Also”