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→422.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→999 / 2→49.54 / 2→2.07 % 3→11 + 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"→truetoUpper("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→true1 is not 2→true5 is "5"→false1 < 2 and 3 > 2→truefalse or true→truenot false→true2 in [1, 2]→true3 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→7x is defined→falsex 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→true5.5 is a Int→false"x" is a String→true"42" as Int→424.9 as Int→412 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 ofids.map paris the same formap. If one fails, the others finish first, then the error is raised. With nothing to wait for,parchanges 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 asYYYY-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;untiloptional, negatives count from the end.range(from, until): the Ints fromfromup tountil - 1.flatten(xs): one level of nested lists.round(x, places): rounds half away from zero, toplacesdecimals (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 oftextwithkey(named arguments only;crypto.hmac(key = "Jefe", text = "what do ya want for nothing?")gives5bdcc146…3843), to sign what a rule sends (a webhook's signature):algis"sha256"(if left out),"sha1"or"sha512",encis"hex"(if left out) or"base64"; anything else isE_ARG. The key can besecret("name"): the flow's trace shows the call ascrypto.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), anyhttp.*call isE_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 sameE_HTTPtext.http.post(url, headers, body),http.patch(url, headers, body): send to a web service, with the same limits and in the same places ashttp.json. They reach only a host listed in your project'sapps.sites(Settings:Project:api.example.com, or*.example.comfor the names under it), every redirect too; any other isE_SITE, naming the host: add it there. They need a member of the project (a signed-in non-member, or a read-only token, getsE_SCOPE). A scratch run (the Fiddle) sends for real. An Object or Arraybodygoes as JSON, a String as is;form = {grant_type: "client_credentials", client_id: id, client_secret: secret}in place ofbodysends a form. The answer is the JSON when the service sends JSON, else the text, and{}when it's empty. A refusal isE_HTTPwith 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.writesPerMinutein Settings:Project sets fewer) and 300 for the whole server; over a cap the call isE_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 ofnamein 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 withsecret(…)). 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 isE_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 fieldE_WAIT; in the expression boxE_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 entrysecret("name")reads (its Used by rules in lists your project); it never makes one (no such entry isE_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) isE_PERM, and an entry d2 keeps for its person alone (d2-user-enc, ad2-<role>, a mail grant) isE_SECRET. Each write is audited (the rule, the run, who, when; never the value); the trace showssecret.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).