Functions#

Orchard exposes 56 functions in every expression — variable defaults, provider configs, component inputs, action attributes, scenario outputs, component outputs, and teardown bodies. All names use lowercase compound words with no separators (jsonencode, timeadd, timeseries, …).

Functions marked with (impure) may return different values on each call. That’s intentional — scenarios are single-shot imperative runs, not convergent plans.

Collections#

concat#

concat(lists...) → list

Concatenate two or more lists into one.

concat(["a"], ["b", "c"])

→ ["a", "b", "c"]

contains#

contains(list, value) → bool

Check whether a list or set contains a given value.

distinct#

distinct(list) → list

Remove duplicate elements from a list.

element#

element(list, index) → any

Return the element at the given index in a list.

keys#

keys(map) → list(string)

Return the keys of a map as a list.

length#

length(collection) → number

Return the number of elements in a collection.

Works on lists, maps, and tuples. Use strlen for string length.

lookup#

lookup(map, key, default) → any

Look up a key in a map with a default fallback.

merge#

merge(maps...) → map

Merge two or more maps. Later keys override earlier ones.

range#

range(args...) → list(number)

Generate a list of numbers.

range(3)

→ [0, 1, 2]

reverse#

reverse(list) → list

Reverse the order of elements in a list.

slice#

slice(list, start, end) → list

Extract a contiguous sub-list.

sort#

sort(list) → list(string)

Sort a list of strings lexicographically.

values#

values(map) → list

Return the values of a map as a list.

zipmap#

zipmap(keys, values) → map

Construct a map from a list of keys and a list of values.

Encoding#

csvdecode#

csvdecode(str) → list(map(string))

Decode a CSV string into a list of maps (first row = headers).

jsondecode#

jsondecode(str) → any

Decode a JSON string into a value.

jsonencode#

jsonencode(value) → string

Encode a value as a JSON string.

jsonencode({name = "alice", age = 30})

→ "{\"name\":\"alice\",\"age\":30}"

Environment#

env (impure)#

env(name) → string

Read an environment variable by name.

Returns an empty string when the variable is unset, matching shell convention. Values read via env() may appear in run records — use for connection strings and config, not raw secrets.

env("DATABASE_URL")

→ "postgres://localhost/mydb"

env("UNSET_VAR")

→ ""

Identity#

uuid (impure)#

uuid() → string

Generate a random v4 UUID string.

Each call produces a new value. Use for primary keys, correlation IDs, or any field that needs a unique identifier.

uuid()

→ "a3f29e5b-1234-4abc-9def-0123456789ab"

Math#

abs#

abs(n) → number

Return the absolute value of a number.

ceil#

ceil(n) → number

Round a number up to the nearest integer.

floor#

floor(n) → number

Round a number down to the nearest integer.

log#

log(n, base) → number

Return the logarithm of a number in a given base.

max#

max(numbers...) → number

Return the largest of the given numbers.

min#

min(numbers...) → number

Return the smallest of the given numbers.

pow#

pow(base, exponent) → number

Return base raised to the power of exponent.

signum#

signum(n) → number

Return -1, 0, or 1 depending on the sign of a number.

Regex#

regex#

regex(pattern, str) → string | list(string)

Apply a regular expression to a string and return the first match.

regexall#

regexall(pattern, str) → list(string) | list(list(string))

Apply a regular expression to a string and return all matches.

Sets#

setintersection#

setintersection(sets...) → set

Return elements common to all given sets.

setproduct#

setproduct(sets...) → set(tuple)

Compute the Cartesian product of the given sets.

setsubtract#

setsubtract(a, b) → set

Return elements in the first set that are not in the second.

setunion#

setunion(sets...) → set

Return the union of all given sets.

Strings#

chomp#

chomp(str) → string

Remove trailing newlines from a string.

format#

format(format, args...) → string

Format a string using printf-style verbs.

format("hello %s, you are %d", "alice", 30)

→ "hello alice, you are 30"

formatlist#

formatlist(format, args...) → list(string)

Format each element of a list using printf-style verbs.

join#

join(separator, list) → string

Join a list of strings with a separator.

join(", ", ["a", "b", "c"])

→ "a, b, c"

lower#

lower(str) → string

Convert a string to lowercase.

lower("HELLO")

→ "hello"

replace#

replace(str, old, new) → string

Replace all occurrences of a substring.

split#

split(separator, str) → list(string)

Split a string by a separator.

split(",", "a,b,c")

→ ["a", "b", "c"]

strlen#

strlen(str) → number

Return the length of a string in characters.

Use length for collections (lists, maps, tuples). strlen is for strings only.

substr#

substr(str, offset, length) → string

Extract a substring by offset and length.

title#

title(str) → string

Convert a string to title case.

title("hello world")

→ "Hello World"

trim#

trim(str, cutset) → string

Remove leading and trailing characters from a string.

trimprefix#

trimprefix(str, prefix) → string

Remove a prefix from the start of a string.

trimspace#

trimspace(str) → string

Remove leading and trailing whitespace from a string.

trimsuffix#

trimsuffix(str, suffix) → string

Remove a suffix from the end of a string.

upper#

upper(str) → string

Convert a string to uppercase.

upper("hello")

→ "HELLO"

Time#

formatdate#

formatdate(format, timestamp) → string

Format a timestamp using a format string.

Uses HCL’s format spec: YYYY (year), MM (month), DD (day), hh (hour), mm (minute), ss (second).

formatdate("YYYY-MM-DD", "2026-04-20T12:30:00Z")

→ "2026-04-20"

now (impure)#

now() → string

Return the current UTC time as an RFC3339 string.

Evaluated at expression-evaluation time. Two now() calls in the same action body may differ by microseconds.

now()

→ "2026-04-20T12:00:00Z"

timeadd#

timeadd(timestamp, duration) → string

Add a Go duration to a timestamp.

timeadd("2026-01-01T00:00:00Z", "24h")

→ "2026-01-02T00:00:00Z"

timerandom (impure)#

timerandom(start, end) → string

Return a random timestamp between start and end.

timerandom(timesub(now(), "30d"), now())

timesequence (impure)#

timesequence(start, end, min_interval, max_interval...) → list(string)

Generate timestamps stepping by random intervals between min and max.

Produces timestamps from start until end is reached. With only min_interval, steps are evenly spaced. With both min and max, each step is randomised within the range. Capped at 100,000 entries.

timesequence(timesub(now(), "30d"), now(), "1d", "5d")

timeseries#

timeseries(start, end, count) → list(string)

Distribute exactly N timestamps evenly between start and end.

First entry is start, last is end, intermediate points are equidistant. Use timesequence for interval-based generation.

timeseries(timesub(now(), "90d"), now(), 10)

→ ["2026-01-20T...", ..., "2026-04-20T..."]

timesub#

timesub(timestamp, duration) → string

Subtract a duration from a timestamp.

Supports extended durations: d (days = 24h) and w (weeks = 7d) on top of Go’s standard units.

timesub("2026-04-20T00:00:00Z", "7d")

→ "2026-04-13T00:00:00Z"

timeunix#

timeunix(timestamp) → number

Convert a timestamp to Unix epoch seconds.

timeunix("2026-01-01T00:00:00Z")

→ 1767225600