Skip to content

6. dbt Docs

Module 6: Stadium Documentation Site (dbt Docs)#

Overview#

Learn to navigate and use dbt documentation to understand table relationships, find data definitions, and explore the data lineage.

Learning Objectives#

By the end of this module, you will be able to:

  • Access dbt documentation
  • Navigate the dbt docs interface
  • Search for tables and columns
  • Understand table relationships through lineage graphs (DAG)
  • Use dbt docs to write better queries

Accessing dbt Docs#

There are three ways to access dbt documentation:

Your organization may host dbt docs at a URL. Check with your administrator for the link, or login to https://portal.edanalytics.app and select the tile for 'Stadium Ed-Fi Documentation' (if your organization is a Stadium partner).

2. Public Demo Site#

If you don't yet have EDU deployed, but want to get a sense for what dbt Docs looks like, head to our demo version.

3. Local Documentation#

If you have dbt installed locally:

cd /path/to/dbt/project
dbt docs generate
dbt docs serve

Then open your browser to http://localhost:8080.

This will be most helpful if you are a Developer and want to see live updates to the dbt documentation site.

dbt Docs Homepage#

When you first open dbt docs, you'll see:

  • 1. Overview (Left Navigation Bar) - Index of what's documented on the site
  • 2. Search bar (Top middle) - Quickly search for tables, columns, and code
  • 3. Welcome Message - Some auto-generated text that explains the site, and links to helpful resources, provided by dbt.

dbt Docs Home Page

There are two recommended paths toward finding a table and its associated documentation:

  1. Use the Database View (for clicking through the database in the same structure as you see in the Data Warehouse)
  2. Use the Search Bar (for quickly looking up a table you know the name of)

Database View#

Using the Left Navigation Bar, Click on Database, then choose the database, schema, and table, you're interested in. See Data Warehouse Overview for a refresher on the available databases and schemas.

Using the Database Viewer

Click any table to view its details.

Searching#

Use the search bar at the top to find:

  • Tables - Search by table name
  • Columns - Search by column name
  • Code - Search within SQL code
  • Descriptions - Search documentation text

Search tips:

  • Use filters to narrow results
  • Search for column names to find which tables contain them

Using the Search Bar

Table Overview Page#

When you click a table, you'll see several tabs:

1. Details Tab#

  • Description - What this table contains
  • Grain - What each row represents
  • Metadata - When last run, row count, size
  • Tags - Categorization tags

2. Description Tab#

Here's where you can find a quick description of the table, and often its Primary Key (use this when writing your joins!)

Description tab

3. Columns Tab#

This tab lists all the columns in the table, and their metadata: - Column name - Data type - Description - Tests applied to the column

Understanding Your Data

Always read column descriptions before using them in queries. They often contain important notes about nullability, grain, and meaning.

Columns tab

4. Referenced By#

Shows what tables or models use this table as input. Use this to trace what downstream uses of this table exist in the dbt project.

Referenced By

5. Depends On#

Shows what tables or sources this table is built from. Use this to trace where the data in this table came from.

Depends On

6. Code Tab#

Two sub-tabs:

  • Source - The original dbt SQL code
  • Compiled - The final SQL sent to the warehouse

Why both?

  • Source shows dbt macros and Jinja templates
  • Compiled shows the actual SQL that ran
  • You can copy the compiled code into Snowflake/Databricks to see how the query works step-by-step

Code tab — Source and Compiled

Lineage Graph (DAG)#

The lineage graph is one of the most powerful features of dbt docs!

Accessing the Lineage Graph#

Click the blue graph icon in the bottom right corner of any table page.

Controls:

  • Scroll - Zoom in/out
  • Click and drag - Pan around the graph
  • Click a node - Highlight that node and its connections

Filtering Options#

Use the sidebar to filter what's shown:

  • + button - Expand to show more upstream dependencies
  • - button - Expand to show more downstream dependents
  • Select a number - Show N levels up/down
  • Filters - Show only certain node types

Focusing on Nodes#

Right-click a node for options:

  • Focus on this model - Show only this model's lineage
  • Refocus - Reset the graph
  • View documentation - Jump to the table page

Practical Use Cases#

Use Case 1: Understanding a Table#

Before querying fct_student_school_association:

  1. Search for the table in dbt docs
  2. Read the description and grain
  3. Review the columns and their descriptions
  4. Check the lineage to see what sources feed it

Need student demographics for an enrollment query?

  1. Open fct_student_school_association in dbt docs
  2. View the lineage graph
  3. Look for dimension tables connected to it
  4. Find dim_student and see what columns it has

Use Case 3: Debugging Data Issues#

Data doesn't look right?

  1. Check the lineage graph
  2. Follow the transformations from source to final table
  3. Look at intermediate build tables
  4. Review the SQL in the Code tab

Use Case 4: Discovering Available Data#

What assessment data is available?

  1. Search for "assessment" in dbt docs
  2. Review tables and columns that match
  3. Check descriptions to understand differences
  4. View lineage to understand how they're related
  5. Query the tables you see in Snowflake to determine what's available.

Best Practices#

dbt Docs Best Practices

  1. Always check dbt docs before writing a query - Save time by understanding the data first
  2. Use the lineage graph - Visualize relationships between tables
  3. Read column descriptions - They contain important context
  4. Check the grain - Understand what each row represents
  5. Look at tests - Tests show data quality checks and expected values
  6. Use search - Don't browse manually, search for what you need

Practice Exercise#

Explore dbt Docs

  1. Access your dbt docs (hosted or local)
  2. Search for dim_student
  3. Read the table description and review columns
  4. Open the lineage graph
  5. Find what fact tables use dim_student
  6. Pick one fact table and review its documentation
  7. View the compiled SQL for that fact table

Congratulations!#

You've completed the Query and Analyze training series! You now have the foundational knowledge to:

  • ✅ Understand the EDU data stack architecture
  • ✅ Connect to your data warehouse
  • ✅ Navigate the Snowflake interface
  • ✅ Understand the warehouse structure
  • ✅ Work with EDU table conventions
  • ✅ Write SQL queries against EDU data
  • ✅ Use dbt docs to explore and understand data

Next Steps#

Now you're ready to:

Happy querying! 🎉