CEL EXPRESSIONS

Swamp uses CEL (Common Expression Language) for inline expressions in model definitions, workflow configurations, and data queries.

Expression Syntax

Embed CEL expressions in YAML values with the ${{ }} wrapper:

globalArguments:
  greeting: "${{ 'Hello, ' + self.name }}"
  vpc_id: "${{ model.my_vpc.resource.result.result.attributes.vpcId }}"

When the entire YAML value is a single ${{ }} expression, the evaluated result preserves its type (number, boolean, list, map). When mixed with surrounding text, the result is coerced to a string.

Where Expressions Are Evaluated

Each location has access to a different set of context variables:

* webhook is only available when the workflow was triggered by a webhook.

Context Variables

self

The current model definition being evaluated.

When forEach is active, the iteration variable is available as a field on self. For example, forEach: { item: "env", in: [...] } adds self.env.

model

A map of all models in the repository, indexed by name and UUID.

model.<name>.input

model.<name>.definition

model.<name>.resource.<specName>.<instanceName>

model.<name>.file.<specName>.<instanceName>

model.<name>.execution

Hyphenated Model Names

CEL interprets hyphens as subtraction. Swamp automatically transforms model.deploy-vpc.resource to model["deploy-vpc"].resource. Both forms work in expressions. Use bracket notation explicitly when needed:

model["deploy-vpc"].resource.result.result.attributes.vpcId

inputs

Input values provided when instantiating a definition. Available in workflow step task inputs.

inputs.vpc_id
inputs["hyphenated-name"]

env

The full process environment as a flat string map.

env.API_ENDPOINT
env.HOME

vault

Secure secret access. Secrets are fetched at runtime and never written to model output data. Vault expressions are resolved before CEL evaluation — the secret value is substituted into the expression before it runs.

vault.get("my-vault", "api-key")
vault.get("infra", "Client ID")

data

Namespace for querying versioned data artifacts. See Data Functions below.

file

Namespace for reading file contents. See File Functions below.

run

Metadata about the current workflow execution. Only available in workflow step expressions (task.inputs, forEach.in), not in workflow-level fields like description.

run.id
run.workflowName
run.tags

The flat workflowRunId variable is also available (equivalent to run.id) for backward compatibility with data.query() predicates.

Because run.id is unique per execution, it serves as a collision-safe key when the same workflow runs concurrently:

inputs:
  outputKey: "filtered-vms-${{ run.id }}"

webhook

Webhook request data, available in workflow step expressions (task.inputs, forEach.in) only when the workflow was triggered by a webhook. Not present for CLI-triggered or scheduled runs.

webhook.body.action == "opened"
webhook.headers["x-github-event"] == "issues"

Use webhook.body to route workflow behavior based on the incoming payload:

inputs:
  action: "${{ webhook.body.action }}"
  repo: "${{ webhook.body.repository.full_name }}"

DataRecord Fields

Data functions and query predicates operate on records with these fields:

Data Functions

All data functions are methods on the data namespace. They return DataRecord objects or arrays of them.

data.latest(modelName, dataName)

Returns the latest version of a named data item, or null.

data.latest("scanner", "result")
data.latest("scanner", "result").attributes.findings

# Null-safe — returns null instead of throwing if the data doesn't exist:
data.latest("scanner", "result").?attributes.?findings
data.latest("scanner", "result").?attributes.?findings.orValue([])

data.latest(modelName, dataName, varyValues)

Returns the latest version for a specific vary dimension.

data.latest("scanner", "result", ["dev"])
data.latest("scanner", "result", ["us-east-1", "prod"])

data.version(modelName, dataName, version)

Returns a specific version of a data item, or null.

data.version("scanner", "result", 1)
data.version("scanner", "result", 3).attributes.status

# Null-safe:
data.version("scanner", "result", 1).?attributes.?status.orValue("unknown")

data.version(modelName, dataName, varyValues, version)

Returns a specific version for a vary dimension.

data.version("scanner", "result", ["dev"], 2)

data.listVersions(modelName, dataName)

Returns all version numbers for a data item, in ascending order.

data.listVersions("scanner", "result")

With vary values:

data.listVersions("scanner", "result", ["prod"])

data.findByTag(tagKey, tagValue)

Returns all data records (latest version) matching a tag.

data.findByTag("env", "production")

data.findBySpec(modelName, specName)

Returns all data records for a model matching a given output spec name. Inside a workflow run, results are scoped to data produced during that run.

data.findBySpec("scanner", "result")

data.query(predicate)

Runs a CEL predicate against all data artifacts. Returns matching records.

data.query("modelName == \"scanner\" && size > 1000")

data.query(predicate, select)

Runs a predicate with a projection expression that transforms each matching row into the specified shape.

data.query("modelName == \"scanner\"", "attributes.status")
data.query("size > 1000", "{\"name\": name, \"size\": size}")

Cross-Namespace Queries

When a repository has a namespace assigned, data functions support cross-namespace access through a prefix syntax on the modelName argument.

Namespace prefix

Prefix the model name with the namespace and a colon to read from a specific namespace:

data.latest("infra:my-vpc", "result")
data.version("compute:web-server", "result", 3)
data.findBySpec("security:scanner", "findings")

Wildcard prefix

Use * to search all namespaces:

data.latest("*:my-vpc", "result")

If the model name exists in more than one namespace, the wildcard lookup fails with an ambiguity error.

Default scoping

Without a prefix, point lookups (data.latest, data.version, data.listVersions, data.findByTag, data.findBySpec) scope to the current repository's namespace.

data.query() returns results from all namespaces by default.

ns query field

The ns field is available in data.query() predicates and projections to filter or project by namespace:

data.query("ns == \"infra\" && modelName == \"my-vpc\"")
data.query("ns == \"infra\"", "{\"model\": modelName, \"ns\": ns}")

The field name is ns, not namespace. CEL reserves namespace as a keyword.

File Functions

file.contents(modelName, specName)

Returns the text content of a file data item, or null.

file.contents("config-gen", "output")

Data Query Predicates

The data.query() function and swamp data query command evaluate CEL predicates against data artifacts. Each row exposes the DataRecord fields as top-level variables.

Available Query Fields

id, name, version, createdAt, attributes, tags, modelName, modelType, specName, dataType, contentType, lifetime, ownerType, streaming, size, content, ns

When using data.query(), the attributes and content fields are lazy-loaded only when referenced in the predicate or projection. Other data functions (data.latest(), data.version(), etc.) load these fields eagerly.

Projections

A projection transforms each matching row into the shape specified by the expression. The second argument to data.query() (or --select flag on the CLI) is evaluated against each matching row, and the result replaces the full DataRecord in the output.

data.query("modelName == \"hello-world\"", "attributes.stdout")
data.query("size > 1000", "{\"name\": name, \"size\": size}")

Types

Primitives

Aggregates

Strings

Triple-quoted strings span multiple lines. Raw strings (r"...") disable escape processing.

"""multi
line"""
r"no\escape"

Operators

Arithmetic

Arithmetic operators work across int and double without explicit conversion. This covers +, -, *, /, and %.

Comparison

Logical

Membership

For string containment, use the .contains() method:

"hello world".contains("world")   // true

Access

Optional Select (.?)

The .? operator provides null-safe field access. When the receiver is null, .? evaluates to null instead of throwing an error. Chain multiple .? operators to traverse deeply nested structures that may contain null at any level.

data.latest("factory", "code-review").?attributes.?findings

Regular . access throws when the receiver is null — this is intentional, as it catches real bugs where data is expected to exist. Use .? only when the data genuinely might not exist (e.g., prior-cycle artifacts in rework loops, optional cross-model references).

.orValue() — Inline Defaults

Pair .? with .orValue() to provide a fallback value when the chain resolves to null:

data.latest("factory", "code-review").?attributes.?findings.orValue([])
data.version("scanner", "result", 1).?attributes.?status.orValue("unknown")

When to Use .? vs .

Precedence (Highest to Lowest)

1. (), ., .?, [] -- grouping, field access, optional select, indexing
2. - (unary), ! -- negation
3. *, /, % -- multiplicative
4. +, - -- additive
5. ==, !=, <, >, <=, >=, in -- comparison
6. && -- logical AND
7. || -- logical OR
8. ? : -- conditional

Built-in Functions

Type Conversion

Size

size("hello")        // 5
size([1, 2, 3])      // 3
size({"a": 1})       // 1
"hello".size()       // 5 (method form)

String Methods

List/String Join

["a", "b", "c"].join()       // "abc"
["a", "b", "c"].join(", ")   // "a, b, c"

Timestamp and Duration

Constructors

Valid duration units: ns, us, ms, s, m, h.

Timestamp Methods

All accept an optional timezone string (e.g., "America/New_York"). Default is UTC.

timestamp("2024-01-15T10:30:00Z").getHours("America/New_York")  // 5

Duration Methods

Arithmetic

timestamp("2024-01-15T10:00:00Z") + duration("1h")    // Timestamp
timestamp("2024-01-16T00:00:00Z") - timestamp("2024-01-15T00:00:00Z")  // Duration
duration("1h") + duration("30m")   // Duration

Macros

has()

Tests whether a field exists without throwing on missing properties.

has(model.scanner.resource)
has(attributes.optional_field)

all()

True if all elements satisfy the predicate. True for empty lists.

[1, 2, 3].all(x, x > 0)           // true

exists()

True if any element satisfies the predicate.

[1, 2, 3].exists(x, x > 2)        // true

exists_one()

True if exactly one element satisfies the predicate.

[1, 2, 3].exists_one(x, x > 2)    // true

filter()

Returns elements that satisfy the predicate.

[1, 2, 3, 4].filter(x, x > 2)     // [3, 4]

map()

Transforms each element. With three arguments, filters then transforms.

[1, 2, 3].map(x, x * 2)           // [2, 4, 6]
[1, 2, 3, 4].map(x, x > 2, x * 10)  // [30, 40]