Samson Advisory Samson AdvisoryGrowth Strategists & Implementers
Documentation

DBT Workshop

An in-browser IDE for writing, running, and shipping dbt transformations — without leaving Awali.

What It Is

DBT Workshop is Awali's data-transformation IDE. It gives you a Monaco-based code editor, a file tree, a lineage graph, a results pane, and a terminal — everything you need to write dbt models, ingest raw data, and validate your transformations before they reach the rest of the platform.

You'll find it at /admin/dbt-studio after logging in as an admin.

What You Can Do

Edit dbt project files

  • Create, edit, rename, and delete .sql, .yml, .yaml, .md, .csv, .txt, and .py files.
  • Browse your project in a tree view in the left sidebar.
  • Open multiple files in tabs; the editor remembers your open tabs across reloads.
  • Soft-delete files to a recoverable trash; restore or permanently empty at any time.

Ingest CSV data as seeds

  • Upload CSV files up to 400 MB directly into your seeds/ directory.
  • Preview column headers and sample rows before importing.
  • Import the seed straight into the database — Awali creates the destination table automatically.
  • Large files use streaming row-count estimation so the browser stays responsive.

Run and compile dbt models

  • Click “Run” on any model to compile and execute it.
  • Inspect the compiled SQL in target/compiled/.
  • Execute ad-hoc SELECT queries from the editor; results show in the Results tab with column headers, row counts, and an auto-applied LIMIT 1000 for safety.
  • A built-in SQL validator blocks destructive statements (DELETE, DROP, TRUNCATE, etc.) from running against your warehouse.

Visualize lineage

  • Open the Lineage tab to see your full project as a DAG.
  • Nodes are color-coded by resource type: model, source, seed, snapshot.
  • Click any node to see its schema, database, and file path.

Use the integrated terminal

  • Run dbt CLI commands directly: dbt run, dbt test, dbt compile, dbt seed, dbt build, and others.
  • Output streams to the terminal in real time.
  • Dangerous commands (shell injection patterns, file deletion outside the project, package installation) are blocked.

Manage data connections

  • Add API keys, secrets, and credentials in the Settings page (/admin/dbt-studio/settings).
  • Keys are stored as UPPERCASE_WITH_UNDERSCORES environment variables and auto-synced to dbt/.env so your Python macros and packages can read them.
  • Secret values are masked in the UI and every read is audit logged.

Common Workflows

Bringing in a new dataset

  1. Drop your CSV in the Workshop's upload pane.
  2. Review the preview, confirm the column types look right.
  3. Click Import — the table is created in data_db.
  4. Write a staging model in models/staging/ that casts columns to their final types.
  5. Run the model, check the results, and chain downstream models from there.

Iterating on a model

  1. Open the model file in the editor.
  2. Make your change; the editor saves automatically.
  3. Click Run to compile and execute.
  4. Review the Results tab. Use the Lineage tab to check what downstream models will be affected.
  5. Run dbt test from the terminal to catch quality regressions before shipping.

Glossary

Workshop
The DBT Workshop IDE itself — the editor, file tree, terminal, and lineage view.
Seed
A CSV file checked into the dbt project. Seeds become tables when you run dbt seed or use Workshop's import button.
Model
A SQL file that defines a transformation. Each model becomes a table or view in your warehouse when it runs.
Compile
The step where dbt validates a model's syntax and renders the final executable SQL (resolving ref(), macros, etc.).
Run
Executing a compiled model to create or update the destination table.
Test
A dbt assertion that validates data quality — uniqueness, not-null, referential integrity, custom rules.
DAG
The “directed acyclic graph” of your project — the dependency map showing how each model is built from its sources.
Data connection
A named secret or credential available to dbt Python macros and packages at run time.

Access & Security

  • Admin role required, plus an active MFA session.
  • All file paths are scoped to the dbt project — absolute paths and .. traversal are rejected.
  • Every CSV upload, seed import, and secret read is audit logged with the user's email and IP address.
  • Workshop files are synced to Awali's AI knowledge base so chat agents can answer questions about your models with full context.

← Back to overview

↑