Core Execution Actions

Preview vs. Run vs. Test vs. Build

When developing and maintaining data pipelines in dex, you'll frequently interact with four core actions: Preview, Run, Test, and Build. Each serves a distinct purpose in the model development lifecycle and helps you validate, execute, or deploy your transformations with clarity and control.

Below is a breakdown of what each action does and when to use it:

Preview

Preview lets you see the result of a model’s SELECT statement without materializing the output to your warehouse.

Use this to:

• Quickly inspect a model’s logic

• Validate column values and row-level transformations

• Debug joins, filters, and aggregations

Preview does not create or update a table or view. It's lightweight, fast, and ideal during active development.

Run

Run executes the model and materializes it based on its configured materialization (view, table, incremental, or ephemeral).

Use this when:

• You want to persist the model’s result in your data warehouse

• You're ready to push updates to downstream models

• You need to trigger the full SQL or Python logic in a production-like setting

Run respects model dependencies defined using ref() and will execute upstream models as needed.

Test

Test runs one or more data quality assertions defined in your project.

Tests are used to:

• Validate that your data meets expected conditions

• Catch issues like nulls, duplicates, invalid relationships, or custom logic mismatches

• Monitor the health of your pipeline

You can test a single model or run all tests in a project. Failing tests will be logged and surfaced in the UI in the Develop and Flows tab.

Build

Build is a comprehensive action that:

1. Runs the model (materializes it)

2. Runs all associated tests

3. Respects full model dependencies

Use Build when:

• You're ready to promote or validate a complete transformation layer (e.g., a 3.gold model)

• You want a one-click way to execute and verify your logic end to end

• You're preparing models for deployment in automated Flows or production environments

Summary Table

Action	Persists Data	Runs SQL	Executes Tests
Preview	❌	✅	❌
Run	✅	✅	❌
Test	❌	❌	✅
Build	✅	✅	✅

Understanding Upstream and Downstream

dex models are connected through dependencies, which define the order of execution in your Flows.

• Upstream models are the ones your current model depends on. If model B references model A using {{ ref('A') }}, then A is upstream of B.

• Downstream models depend on the current model. Continuing the example, B would be downstream of A.

These relationships impact:

• Run order: Upstream models are always built first.

• Lineage: dex visualizes model dependencies to help you trace impact and troubleshoot issues.

• Build scope: When you build a model, all its upstream dependencies will also be built automatically.

Understanding upstream and downstream relationships is critical when:

• Debugging broken models

• Making schema changes

• Deciding where to place tests

• Organizing your model layers