Logic Engine: alert when something matters¶

The Logic Engine is Datahub's alert rule builder. It runs SQL against your warehouse on a schedule, evaluates the result against a threshold, and fires actions — notify a user, ping a team, hit a webhook, or trigger a flow — when the rule's condition is met.

The same objects appear under Contracts → Decision contracts as a read-only governance view (Decision contracts) — use the builder to author; use Decision contracts to audit ownership, lifecycle, and links.

It's a Sentry-style WHEN / IF / THEN authoring surface for data alerts: pick what to monitor, define when to fire, configure who or what gets called. Light enough that an analyst can author one without leaving the platform.

When to choose this¶

Reach for Logic Engine when you want to:

Monitor a number against a threshold. "Alert me when active subscribers drops below 10,000."
Detect data quality regressions. "Alert if null rate on email rises above 5%."
Watch for SLA breaches. "Alert if any record is older than 24 h."
Notify on freshness. "Alert when the daily ETL hasn't run by 9 AM."
Bridge a metric to an action. "When churn-risk count > 100, trigger the Risk Outreach flow."

You do not need this module for:

Heavy automation (multi-step branches, parallel work) — use Flows.
One-off troubleshooting — use Insights or HERC.
Data quality tests baked into ELT — use the Metadata Engine's Data Tests.

What Logic Engine looks like¶

Surface	Where	What you see
List	`/logic-engine`	DataTable with name, status, sync state, last evaluated, schedule, owner. KPI row, search, filter pills, column customisation.
Create	`/logic-engine/new`	Sentry-style five numbered sections: Basics → WHEN (warehouse + query) → IF (threshold) → THEN (actions) → Preview / Submit. Each section has hints from HERC.
Detail	`/logic-engine/{id}`	Numbered read-only layout, status controls (Activate / Pause / Submit for review), workflow progress, sync card, query history, recent executions, Test alert sidebar.
Test alert	Detail → Test alert	Re-runs the rule's query immediately and shows whether it would trigger right now (with the value + row count).

Concepts¶

Concept	What it is
Alert rule	The full definition: query, threshold, schedule, lifecycle, integration, owner.
WHEN	The query — Databricks SQL that returns the column to evaluate.
IF	The threshold — comparison operator (`>`, `<`, `>=`, `<=`, `==`, `!=`) and a numeric value.
THEN	One or more actions — notify user / notify team / webhook / MS Teams / trigger flow.
Status	draft → under_review → approved → active → paused → archived.
Sync status	Datahub's view of the alert in Databricks: ok / pending / error.
Query history	A persistent log of every preview / test run on this rule (and globally).
Execution history	Records from real (scheduled) evaluations.

Setup — what an admin needs to do once¶

Prereq	Where	Why
Databricks integration	`/admin/integrations` → Databricks	Required — Logic Engine is Databricks-first. The integration provides host, auth, and a SQL warehouse.
AI provider key	`/admin/integrations` → AI Provider Keys	Powers the HERC hints in the rule builder.
Roles	`/rolegroups`	`logicengine.rules.read` to view; `logicengine.rules.write` to create / edit / activate / pause / archive.
(Optional) Workflow definition	`/admin/workflows`	If you want a review gate before activation, configure a workflow for `logicengine_alert_rule`. The seeding sets one up by default.

Building a rule¶

Basics. Name, description, integration (which Databricks workspace + warehouse).
WHEN — define the query.
- Pick a Databricks integration → catalog → schema (browse via the catalog tree, or paste full SQL).
- Write the SQL in the query input atom (syntax-highlighted, Ctrl+Enter to run).
- Click Run query — the platform calls Databricks (read-only validated, LIMIT 10 sample) and shows the result columns.
IF — pick the evaluation column.
- The dropdown is populated from the result columns (no manual typing).
- Pick comparison operator + threshold value.
- Toggle notify on OK if you also want a heads-up when the rule recovers.
THEN — pick actions.
- Add as many actions as you want. Action types:

Action	Config
Notify user	Pick a user.
Notify team	Pick a team.
Webhook	URL, method, headers, body template. SSRF-protected — internal hosts blocked, redirects validated.
MS Teams	Webhook URL + message template.
Trigger flow	Pick a flow definition; the alert payload becomes the flow's trigger context.

Schedule. Pick an interval (e.g. every 5 minutes, every hour, daily at 09:00).
Preview. Inline preview shows what would fire right now: the matched value, the row count, and whether the threshold would trip.
Submit for review (if a workflow is configured) → the reviewer approves → you can activate.
Activate. The platform pushes the rule to Databricks AlertsV2; Databricks owns the schedule + execution from there. Datahub stays the source of truth for definition + history.

Lifecycle and Databricks sync¶

The platform pushes — Databricks executes:

Lifecycle event	What syncs
Activate	Create / update the alert in Databricks. Sync status = ok if the SDK accepts; error if it rejects (the rule still saves on the platform side; the sync error is shown).
Pause	Set Databricks schedule to paused.
Update (active rule)	Re-sync changes.
Archive	Trash the alert in Databricks.
Refresh state	Poll Databricks for the latest evaluation state + last-evaluated-at. Manual button on the detail page.

A Procrastinate periodic job polls active rules every five minutes to keep state fresh in the platform without an admin clicking Refresh.

If a sync fails, the platform stays consistent with itself; the Sync card on the detail page tells you what went wrong and lets you retry.

Reviewing rules¶

If your tenant configured the review workflow:

Submit for review on a draft rule creates a task for the reviewer role group.
The reviewer opens the task → sees the rule details + workflow progress → approves or rejects.
An approved rule can then be activated by the owner.

This is the standard governance pattern — see Workflows and Tasks.

Query history¶

Every time anyone runs the rule's query (preview, test, or scheduled execution) the run is logged with duration, columns returned, row count, and trigger assessment.

Per-rule history lives in the detail page sidebar.
Global history is in /logic-engine/rules/query-history — useful for "who's been hitting Databricks the hardest" triage.

Test alert¶

The Test alert sidebar card on the detail page re-runs the rule's query immediately and tells you:

Would it trigger right now? (yes / no badge)
What value did the evaluation column return?
How many rows did the query return overall?

Use this to sanity-check a rule after editing — you don't need to wait for the next scheduled run.

Limitations¶

Limit	Why	Workaround
Databricks-only execution today.	Phase 1 scope.	A platform-native execution path is on the roadmap.
Webhook actions are SSRF-hardened — internal hosts and redirects to internal hosts are blocked.	Security.	Use a public-internet endpoint or a tenant-internal endpoint approved at integration setup.
The query must be read-only.	Safety. The platform validates and blocks DDL / DML before execution.	Encapsulate writes behind a flow triggered by the alert.
Threshold is numeric.	The IF clause is single-value comparison.	For multi-value or string conditions, write the condition into the query itself and threshold on a binary column.
One evaluation column per rule.	Single-value threshold model.	Split into multiple rules; or fan out via a flow.
Sync errors don't block the rule from saving.	We never want Databricks downtime to block authoring.	Watch the sync status card; click Sync to retry.

Audit & compliance¶

Question a CISO might ask	Where to look
"Who created / edited this rule?"	Detail page metadata; full audit at `/admin/audit-log` filtered by `logicengine`.
"Did the query ever run a write?"	The platform's read-only validator blocks DDL / DML pre-execution; query history shows the actual SQL of every run.
"Where do webhook calls go?"	Each action's URL is shown; SSRF guard blocks internal hosts (and any redirect to one).
"Did this rule fire a flow that did something destructive?"	Trigger-flow actions reference the flow definition by name; flow execution history shows what ran.
"Who approved this rule?"	Workflow progress card on detail page → reviewer + comment.

Troubleshooting¶

Symptom	Likely cause	Fix
Sync status shows error after activate	Databricks rejected the alert (auth, warehouse, query syntax).	Open the Sync card → see the SDK message → fix and retry.
Preview returns "0 rows" but you expect data	Query empty for the LIMIT 10 sample. The platform shows the true total row count from Databricks's manifest, not just the sample.	Check the Total rows badge; revise the WHERE clause.
Threshold dropdown empty	You haven't run the query yet.	Click Run query in the WHEN section first.
Preview returns silently with no error and 0 rows	The SDK didn't raise but Databricks reported a query error (e.g. column not found). The platform now surfaces those errors with column suggestions.	Check the inline preview — the actual error and column suggestions are shown.
Active rule's last-evaluated time is stale	The 5-minute background poll hasn't ticked yet, or Databricks paused the schedule.	Click Refresh state.
Test alert button shows different value than scheduled execution	Time-window difference.	Tighten the query's date filter; the test runs now.
Webhook action fails	SSRF guard blocked the URL.	Use a public-internet URL, or open a ticket to allowlist the internal host.