{% extends "layout.html" %} {% block content %}
{# ── Hero ─────────────────────────────────────────────────────────────── #}

Documentation

How Governor works

Governor finds expensive patterns in your dbt project, proposes concrete fixes, and lets you apply them with confidence. Everything below is scoped to what you'll actually see and do in the UI.

{# ── Workflow ─────────────────────────────────────────────────────────── #}

The workflow

  1. 1. Sync — Governor reads your local dbt project (manifest.json, run_results.json) and pulls the matching BigQuery job metadata. This is how models get linked to real cost.
  2. 2. Detect — Rules scan your recent runs for known-expensive patterns (partition pruning missed, join explosions, shuffle spills, slot contention, etc.) and surface each one as an opportunity.
  3. 3. Review — Each opportunity gets a generated solution: a concrete SQL or dbt_project.yml change with before/after diff and an estimated saving.
  4. 4. Apply — For low-risk changes, Apply & Commit writes the file into your local dbt project and creates a git commit. Higher-risk changes land as a pull request on your repo for human review.
{# ── Key pages ────────────────────────────────────────────────────────── #}

Dashboard

Last dbt execution: total spend, savings already verified, and cost broken down by model. Quickest way to see whether governance is moving the needle.

Opportunities

Every detected issue, one row per model. Sort by cost or savings, jump into a row to see the generated solution, diff, and apply button. In local mode the list groups by dbt model, so a model with multiple findings shows as a single row with an "N issues" badge; click through to the model detail page to see each finding.

Configurations

One entry per dbt project. Set the local project path and the GCP project ID here. Trigger a sync, inspect recent syncs, or jump to the raw BigQuery jobs the sync pulled.

Documentation

You're here. Explains the moving parts and the workflow in plain language.

{# ── Glossary ─────────────────────────────────────────────────────────── #}

Key terms

Opportunity
A specific detected inefficiency on one dbt model. Tied to a type (partition pruning, shuffle spill, etc.) and an estimated cost impact.
Solution
A proposed fix for an opportunity — usually a SQL diff or a config() change — with before/after dry-run cost.
Workload: Build
Cost from materializing models — the dbt run itself. Usually the easiest lever to pull.
Workload: Consumption
Cost from downstream queries against your models. Needs different treatment (materialization choice, clustering, partitioning).
Workload: Ingestion
Raw-landed objects, ingestion/storage layout, and upstream pipeline strategy before data reaches the build layer. Detection rules in this family target the source-side cost.
State: Safe / Review / Upstream fix
How confident Governor is in the proposed change. Safe can ship via a commit; Review needs a human; Upstream fix means another model's fix will resolve this one.
Shadow validation
Runs your dbt project twice — baseline vs. proposed change — and compares real bytes and cost. Empirical proof before you merge. Can be triggered manually via the Run Comparison button, or automatically for every Safe solution via the Auto-validate Safe solutions toggle on a project configuration. Auto-triggered runs incur the same real BigQuery cost as manual ones and are flagged with an Auto badge on the result panel.
{# ── Roadmap ──────────────────────────────────────────────────────────── #}

Roadmap

Governor today covers detection and fixes for partition pruning, shuffle spill, slot contention, join explosion, and materialization choice. The next wave of agents extends the same pattern — detect, propose, apply — into adjacent cost levers.

  • Coming SQL Duplication — flag duplicated SQL logic across models and projects so it can be factored into a shared CTE or macro.
  • Coming SQL Scheduling — recommend run cadences and time-of-day windows for models whose freshness requirements don't justify the current schedule.
  • Coming SQL Redundancy — detect unused tables and unused columns so dead materializations can be retired.
  • In progress Storage Model Insights — full storage-cost agent. Today the storage billing view ships metrics; the recommendation layer is next.
{% endblock %}