Transformations

What is a Transformation Model?

A Transformation Model is a managed dbt model in Stackless. It turns raw or intermediate warehouse tables into a clean, reusable table or view: cleaned order facts, enriched customers, ad performance by channel, daily revenue, retention cohorts, and so on.

Transformation Models are the right place for business logic that should be reused across dashboards, Monitors, and the Agent. Semantic Models and dashboards should read from them rather than from raw source tables.

How models are written

Transformation Models are created and changed through the Agent: ask it in the main Agent page, or click Agent on the Transformation Models page to open the Transformation Model Agent beside the list. There are two kinds:

Spec models support these operations: filter, derive and cast, join enrichment, aggregation, union, flatten, dedupe, window functions (lag, lead, running totals, moving averages, z-scores), pivot, and unpivot.

Layers and materialization

Each model belongs to a layer, which decides the warehouse schema it publishes into:

Spec models materialize as a view (default), table, or incremental model.

The Transformation Models page

Go to Data > Transformation Models. Draft models are private to you; publishing shares them and adds them to the Catalog. Filter the list with All managed, My drafts, Published, or Catalog-only, or search by name.

Each row shows the model's status, its layer and domain, how many drafts exist, and when it was updated. The row menu offers Preview, Publish, Cleanup preview, and Delete draft for drafts, and Run now, Fork draft, and Unpublish for published models.

Status badges

The model detail page

Click a model to open it:

• Overview: the transformation pipeline from inputs to output, the Columns contract with each column's type, description, and tests, and Details such as layer, domain, refresh policy, last refresh, the published table name, and Open in catalog.
• Definition: for spec models, the grain, parents, dimensions, measures, joins, and tests; for SQL models, the SQL and schema YAML.
• Sample (drafts) or Data (published): rows from the model.
• Lineage: upstream and downstream assets.
• Versions (SQL models): every published version, with a diff between versions and Roll back.

Draft, sample, publish

1. Draft. The Agent creates or edits a private draft. To change a published model, use Fork draft; the published version keeps serving dashboards while you work.
2. Sample. Click Run sample to build a private preview and inspect sample rows. The Agent can also check that a model compiles, estimate its cost, or run a larger sample before you publish.
3. Publish. Click Publish. The review shows the Downstream impact and, for SQL models, the changes, reference checks, upstream refresh policies, warnings, and publish order. Type the confirmation phrase to publish. If the model depends on other unpublished drafts, Stackless publishes them first, in order. Keep the tab open until publishing finishes.

When you ask the Agent to publish, it shows the same review and asks you to type the exact confirmation phrase. Approving a dashboard does not approve the models it depends on.

Run and refresh

A model's Refresh policy controls when Operations rebuilds it:

For spec models, the refresh policy is part of the definition, so change it on a draft and publish. SQL models can change their refresh policy in place without a new version.

Run on a published model queues a dbt build of that model only, including its tests. Downstream models are not refreshed. Ask the Agent if you need to refresh a model together with its downstream dependents. Runs share a queue and can take a few minutes to start; follow them in Operations.

Versions, roll back, and unpublish

• Versions lists each published version of a SQL model with who published it and its refresh policy. Roll back copies an earlier version into your draft so you can review and publish it again.
• Unpublish (administrators only) turns a published model back into your private draft: the published table is dropped, the model leaves the Catalog, its scheduled refresh stops, and its published version history is deleted. Check downstream lineage first.
• Delete draft removes a private draft and its preview relations.

Tests

Columns can carry tests that run with every build:

• not_null for required fields.
• unique for primary keys.
• unique_combination for a composite grain.
• accepted_values for controlled categories.

Test the grain your reporting relies on. If a dashboard assumes one row per customer per day, that combination should be tested.

Lineage and downstream impact

Before changing or unpublishing a published model, check what depends on it: other Transformation Models, Semantic Models, dashboards, and Monitors. The Lineage tab and the publish review's Downstream impact show these. Monitors pin model revisions and will flag the change for review.

Permissions

Agent prompts for transformations

• "Find the Transformation Model behind this dashboard metric."
• "Create a Transformation Model that joins orders to customers and keeps the latest order update."
• "Run a sample of this draft and show me 20 rows."
• "Does this model test its grain?"
• "What depends on fct_northwind__orders?"
• "Refresh this model and its downstream dependents."