Language Tour

A tour of the CEL language as it behaves in Octo, one example at a time. Every expression on this page was evaluated with octo eval, and the results are shown exactly as it prints them — as JSON-native values. Try any of them yourself:

bin/octo eval --expr '[1, 2, 3].filter(x, x % 2 == 1)'
# {"ok":true,"result":[1,3]}

Types and literals

CEL has eight scalar types — int, uint, double, bool, string, bytes, timestamp, duration — plus list, map, and null.

Ints, uints, and doubles are distinct types — 1, 1u, and 1.0 are three different values, and mixing them in operators is a compile error (see Equality and numeric types).

Operators

Arithmetic, comparison, logical operators, and the ternary conditional.

Runtime failures like 1 / 0 surface as evaluation errors (division by zero), which in a flow fail the message into its error path.

Strings

matches uses RE2 syntax — no backreferences or lookaheads. It is also available as a global: matches("hello", "^h") is the same as "hello".matches("^h").

Lists and maps

Indexing past the end of a list or reading a missing key is an evaluation error (no such key), not null — see Presence and defaults. There is no slice syntax ([1,2,3][1:2] does not parse) and maps cannot be concatenated with +.

Presence and defaults

Accessing a field that does not exist is an error, so guard optional fields with has() or the in operator before reading them. These examples bind body with --data:

The idiomatic default is a ternary:

bin/octo eval --expr 'has(body.name) ? body.name : "anonymous"' --data '{}'
# {"ok":true,"result":"anonymous"}

has() takes a field selection (has(body.name)), not a bare variable or an index expression. For map keys held in variables, use key in map instead.

Type conversions

type(x) returns a value's type and is useful in comparisons — type("a") == string evaluates to true — but a type itself is not a JSON-serializable result, so an expression must not return one, and string(type(x)) does not compile.

Timestamps and durations

timestamp parses RFC 3339 strings, duration parses Go-style duration strings ("300ms", "90m", "1h30m", "24h"). The variable now is bound to the evaluation time. Timestamps render back as RFC 3339 strings and durations as seconds.

Accessor methods extract components. Note the conventions: getMonth() is zero-based (January is 0), getDayOfWeek() is zero-based from Sunday, getDayOfMonth() is zero-based while getDate() is one-based.

On durations, the accessors convert the whole value: duration("90m").getHours() is 1, duration("90m").getMinutes() is 90, and duration("2h").getSeconds() is 7200.

Equality and numeric types

Equality is deep for lists and maps, and CEL refuses to compile comparisons between statically known distinct types:

That last row matters in practice: message data is dynamically typed, and JSON numbers decode as doubles, so comparisons against int literals work — body.n == 1 and body.n > 0 are both true for --data '{"n": 1}'. Arithmetic is stricter: body.n + 1 fails at runtime with no such overload because a double cannot be added to an int. Write body.n + 1.0, or convert: int(body.n) + 1.