Jobs & Triggers#

RelataDB has a hard design invariant: every background work item is a typed Job. There are no opaque daemons, no hidden cron, and no shell scripts glued to the side. Anything that runs asynchronously — indexing, materialized-view refresh, compaction, pattern detection — is a first-class, observable Job.

This page explains the job model, what triggers each kind of work, and how the workflow and detection engines fit in. It pairs with the operational guide at Jobs, Workflows & Detection.

The model: typed jobs, not daemons#

A Job is a typed unit of background work. Every job surfaces in the system.jobs table with:

• state — pending · running · completed · failed
• owner — which role/worker is executing it
• progress — observable, not a black box

relata jobs                  # list all jobs
relata jobs status indexer   # check a specific job

curl -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  http://localhost:9090/jobs         # GET — list jobs
curl -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  http://localhost:9090/jobs/indexer # GET — one job's status

Because jobs are typed and resumable, a crashed worker is recoverable: the indexer, for example, resumes at the last committed WAL offset rather than re-scanning from zero.

What the jobs are#

Materialized-view refresh modes#

This is the same mechanism behind the lazy side of Data Flow — the indexer is a job, and the WAL offset is its resumable cursor.

Detection rules#

The pattern-detection engine evaluates rules continuously against new data. Rules are defined in YAML (Sigma-compatible) or SQL, and each rule declares a trigger (a type + condition) and an action.

curl -X POST http://localhost:9090/rules \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "large-transfer-flag",
    "trigger": { "type": "Transaction", "condition": "amount > 100000 AND currency = '\''USD'\''" },
    "action": "flag"
  }'

Detection modes#

• live — alerts fire immediately when data matches.
• shadow — alerts are logged but not surfaced (for validation).
• disabled — rule is inactive.

Rules must pass a precision/recall gate against a golden dataset before promotion from shadow to live. This is what keeps the detection engine trustworthy rather than noisy.

Workflows (governance-aware DAGs)#

Workflows are directed acyclic graphs of steps that automate multi-stage analysis — for example: detect (a rule fires) → enrich (a lookup) → report (a templated deliverable).

curl -X POST http://localhost:9090/workflows \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fraud-investigation",
    "steps": [
      {"name": "detect", "type": "rule", "rule": "large-transfer-flag"},
      {"name": "enrich", "type": "lookup", "table": "sanctions_list"},
      {"name": "report", "type": "report", "template": "sars-template"}
    ]
  }'

The critical property: every workflow step inherits the tenant context, PURPOSE, and ACL of the triggering request. Steps that would violate governance are blocked. Workflows cannot bypass policy — they run inside the same trust plane as a human-issued query.

Why "everything is a typed Job" matters#

• Observability — there is one place (system.jobs) to see what the system is doing. No secret timers.
• Resumability — jobs checkpoint (e.g. the indexer's WAL offset), so recovery is cheap and bounded.
• Governance — because jobs and workflows run inside the trust plane, asynchronous work is subject to the same ACL, provenance, and audit rules as synchronous queries.
• Honesty about partial results — when a job or a cluster read cannot complete fully, the system says so (partial reads return 206 with warnings) rather than silently truncating.

See also#

• Jobs, Workflows & Detection — the operational guide (full endpoint reference).
• Data Flow — where the indexer job sits in the eager/lazy split.
• Governance — the trust plane that jobs run inside.
• Observability — monitoring jobs and alerts.