Help › Expressions · version 17 ·

Expression language reference with examples

Expressions compute values: in rules, in computed fields (@calc), in object queries (?query=), in ```table fences, and in the Fiddle, where you can try every line below. Each example shows the expression, then its value.

Values

  • 42 → 42
  • 2.5 → 2.5
  • "hello" → "hello"
  • 'single quotes too' → "single quotes too"
  • true → true
  • [1, 2, 3] → [1, 2, 3]
  • {a: 1, b: "x"} → {a: 1, b: "x"}
  • null ?? "none" → "none"

Numbers are Int (whole, 64-bit, wraps like Java's long) or Float. Number accepts either. Text is String. Dates and durations have their own types, below.

Arithmetic

  • 1 + 2 * 3 → 7
  • (1 + 2) * 3 → 9
  • 99 / 2 → 49.5
  • 4 / 2 → 2.0
  • 7 % 3 → 1
  • 1 + 2.5 → 3.5

/ always gives a Float. Dividing by zero is an error (E_ARITH), never infinity.

Text

  • "n=${1 + 2}" → "n=3"
  • "a" + "b" → "ab"
  • "ell" in "hello" → true
  • toUpper("abc") → "ABC"
  • split(s = "a,b,c", by = ",") → ["a", "b", "c"]

Write \${ for a literal ${. Triple quotes ("""…""") hold text over several lines.

Comparing and logic

  • 1 is 1 → true
  • 1 is not 2 → true
  • 5 is "5" → false
  • 1 < 2 and 3 > 2 → true
  • false or true → true
  • not false → true
  • 2 in [1, 2] → true
  • 3 not in [1, 2] → true
  • "a" in {a: 1} → true

is and == are the same, as are and/&&, or/||, not/!. and and or take Booleans only: for a default value use ??. Comparisons don't chain: 1 < 2 < 3 is an error.

Missing values

  • x ?? 7 → 7
  • x is defined → false
  • x is empty → true
  • [] is empty → true
  • {a: null}.a ?? "none" → "none"

Reading a name that has no value is an error (E_UNDEFINED) unless you test it or give it a default. ?. reads a field of something that may be null.

Choosing

  • if 2 > 1 then "yes" else "no" → "yes"
  • (if true then 1 else 2) + 5 → 6

An if in an expression always has an else.

Types and casts

  • 5 is a Int → true
  • 5.5 is a Int → false
  • "x" is a String → true
  • "42" as Int → 42
  • 4.9 as Int → 4
  • 12 as String → "12"
  • typeOf(1 + 1) → "Int"

Objects and lists

  • {a: 1} + {b: 2} → {a: 1, b: 2}
  • {a: {x: 1}} ++ {a: {y: 2}} → {a: {x: 1, y: 2}}
  • {a: 1, b: 2} - {b: ""} → {a: 1}
  • [1, 2] + 3 → [1, 2, 3]
  • [1] ++ [2] → [1, 2]
  • [1, 2, 3][-1] → 3
  • {"a-b": 2}["a-b"] → 2
  • {a: 5}.a → 5

+ merges objects one level deep (the right side wins); ++ merges all the way down and joins lists. A negative index counts from the end.

Working with lists

  • [1, 2, 3] map (x => x * 2) → [2, 4, 6]
  • [1, 2, 3] filter (x => x > 1) → [2, 3]
  • [1, 2, 3] exists (x => x > 2) → true
  • [[1], [2, 3]] flatMap (x => x) → [1, 2, 3]
  • [1, 2, 3] fold (acc = 0) (x => acc + x) → 6
  • [1, 2, 3] mkString ", " → "1, 2, 3"
  • [{id: "a"}, {id: "b"}] indexBy "id" → {a: {id: "a"}, b: {id: "b"}}
  • {a: 1} map (p => p.key + p.value) → ["a1"]
  • ids flatMap par (i => http.json(url = "https://…/" + i)): flatMap, with the web calls running at once, at most 4 at a time (flatMap par 8 (…) for up to 8, at most 32); results stay in the order of ids. map par is the same for map. If one fails, the others finish first, then the error is raised. With nothing to wait for, par changes nothing.
  • [1, 2, 3] filter (x => x > 1) map (x => x * 10) → [20, 30]

The part in parentheses is a small function: x => … takes each item as x. On an object, map, filter and exists see {key, value} pairs.

Patterns

  • "/acct/42" matches /\/acct\/(?<id>\d+)/ → true
  • "ab" ~= /a./ → true

A pattern is written between slashes, not quotes. In a rule, named groups like (?<id>…) become variables after a successful match.

Dates and durations

  • ("2026-09-24" as Date) < ("2026-09-25" as Date) → true
  • ("2026-09-24T00:00:00Z" as Date) + "2h30m" → "2026-09-24T02:30:00.000Z"
  • ("2026-09-25" as Date) - ("2026-09-24" as Date) → "1d"
  • "90s" as Duration → "1m30s"
  • isoDate("2026-09-24T10:00:00Z" as Date) → "2026-09-24"

A duration is text like "5s", "5 seconds", "2h30m", "1d"; next to a date it's read as a duration. Dates are ISO text when stored.

Core functions

Functions take named arguments, split(s = "a,b", by = ","); one that takes a single argument also takes it bare, sizeOf([1, 2]); a variable with the argument's name can stand for it, split(s, by). f(obj...) passes an object's fields as the arguments.

  • sizeOf(x): length of a String or list, number of fields of an object.
  • typeOf(x): the type's name.
  • now(): the current date and time. today(): today at 00:00 UTC.
  • isoDate(d): a Date as YYYY-MM-DD.
  • toMillis(x): a Date or Duration as milliseconds.
  • uuid(): a random id.
  • trim(s), toUpper(s), toLower(s).
  • split(s, by): text to a list.
  • replaceAll(s, regex, with), replaceFirst(s, regex, with): the regex given as text.
  • slice(x, from, until): part of a String or list; until optional, negatives count from the end.
  • range(from, until): the Ints from from up to until - 1.
  • flatten(xs): one level of nested lists.
  • round(x, places): rounds half away from zero, to places decimals (0 if left out); abs(x): the number without its sign.
  • math.sum(xs), math.min(xs), math.max(xs), math.average(xs): over a list of numbers; average is always a Float.
  • nicej(x): pretty JSON text.
  • hashcode(x): a sha1 of the value.
  • crypto.hmac(key = k, text = t, alg = "sha256", enc = "hex"): the HMAC of text with key (named arguments only; crypto.hmac(key = "Jefe", text = "what do ya want for nothing?") gives 5bdcc146…3843), to sign what a rule sends (a webhook's signature): alg is "sha256" (if left out), "sha1" or "sha512", enc is "hex" (if left out) or "base64"; anything else is E_ARG. The key can be secret("name"): the flow's trace shows the call as crypto.hmac(key=***), and the key shows as *** wherever the run shows anything.
  • urlencode(s), base64encode(s), base64decode(s).
  • json.parse(text): JSON text to a value.
  • csv.parse(text): CSV with a header row to a list of rows; numeric cells become numbers.
  • http.json(url, headers), http.text(url, headers): fetch a web page (https, public sites, 10 s, 2 MB; at most 5 redirects, each checked like the first, so a redirect to a private address fails as one would), in rules and flows only: the flow pauses while it waits, and the server carries on. In a computed field, a table or a query it's an error (E_WAIT): fetch in a rule and store the result. Web calls need you signed in: run by someone who isn't (a run or the Fiddle logged out), any http.* call is E_AUTH, "web calls need you signed in"; your project's own rules, fired by its events and crons, run as the project. A host that's private, unknown or refuses the connection gives one and the same E_HTTP text.
  • http.post(url, headers, body), http.patch(url, headers, body): send to a web service, with the same limits and in the same places as http.json. They reach only a host listed in your project's apps.sites (Settings:Project: api.example.com, or *.example.com for the names under it), every redirect too; any other is E_SITE, naming the host: add it there. They need a member of the project (a signed-in non-member, or a read-only token, gets E_SCOPE). A scratch run (the Fiddle) sends for real. An Object or Array body goes as JSON, a String as is; form = {grant_type: "client_credentials", client_id: id, client_secret: secret} in place of body sends a form. The answer is the JSON when the service sends JSON, else the text, and {} when it's empty. A refusal is E_HTTP with the status and the start of the service's answer. The headers and the body are never shown in a flow's trace or in an error, so a token or a client secret can go in them; they, and a token the service answers, show as *** wherever the flow would show them (a value, a rule's arguments, an error, the payload your rules answer with). Writes are capped: 60 a minute for a project (http.writesPerMinute in Settings:Project sets fewer) and 300 for the whole server; over a cap the call is E_RATE, with when to retry, and nothing is queued. Each write sent is logged (project, rule, who, method, host, path, status), never its body or headers.
  • secret("name"): the value of name in a vault, so a rule names a client secret instead of writing it (a secret written into a rule gets a hint when you save it: name it with secret(…)). The entry must list your project in its Used by rules in (the Vault: AI → Vault). Your project's own rules, fired by its events and crons, read the vault of whoever published the rule's topic; anything you run (a scratch run, the Fiddle, a story) reads only your own vault, so a rule someone else published gets nothing from yours. Anything else is E_SECRET, "no secret for rules in ", whether or not the entry exists; not signed in, E_AUTH. In rules and flows only (in a computed field E_WAIT; in the expression box E_SECRET, since only a run masks it). The value, and whatever a call sends or answers with it, shows as *** everywhere the run shows anything.
  • secret.set(name = "name", value = v): a new value for a vault entry that already exists, the very entry secret("name") reads (its Used by rules in lists your project); it never makes one (no such entry is E_NOT_FOUND). Only in your project's own published rules, those its events, crons and door verbs run, written as the rule's publisher; a run a person, an AI token or a framed App starts (/diesel/run, the Fiddle, a story) is E_PERM, and an entry d2 keeps for its person alone (d2-user-enc, a d2-<role>, a mail grant) is E_SECRET. Each write is audited (the rule, the run, who, when; never the value); the trace shows secret.set(name, value=***) and the value shows as *** wherever the run shows anything.
  • d2.ai.ask(model, prompt, context?, images?, format?, maxTokens?) asks a model (one of the project's ai.models) with a published topic's ## System as its prompt, context lines and the project's own images (paths in its files), paid from the credits of the person whose run it is → {json?, text, model, usage: {in, out, cost}, ms}; only in rules and flows; d2.native.ai.ask( is the same, the steps dictionary's wiring.

In rules there are also the engine's own messages: log(msg), diesel.throw(code, msg), dom.upsert(cls, entity), dom.find(cls, key), dom.d2find(cls, key) (the caller's own object of one of d2's person classes, such as a Recipe), dom.list(cls, q?, query?, sort?, limit?, after?, from?, fields?), dom.remove(cls, key). dom.list answers a page {data, count, total, next?, limit} as /api/v2/dom/<Class> does: q = "kind:fee AND amount:>100" (the list's q= search) and query (an expression, as ?query=) filter in the store, so every match is found however many objects the class has; sort = "-date" (or ["-date", "id"]) orders it, newest first on a date field; limit is 1,000 when left out and at most 1,000 (more is 1,000, capped: true); after = page.next, with the same q and sort, is the next page; from = n skips n (at most 5,000); fields = "a,b" only those.

When it goes wrong

Errors are never silent: they say what went wrong and where. The common ones are E_UNDEFINED (a name with no value: use ?? or is defined), E_TYPE (the wrong kind of value, like "a" or true), E_PARSE (the text isn't an expression), E_ARITH (division by zero), E_ARG (a function's arguments) and E_NO_TOOL (no such function).

Updated by razie · version 17