Why documentation makes data discoverable in dbt - See It in Action

Why documentation makes data discoverable

📖 Scenario: You work in a team that builds data models using dbt. Your team wants to make it easy for everyone to find and understand the data models you create. Good documentation helps with this by explaining what each model does and how to use it.

🎯 Goal: Create a simple dbt model and add documentation to it. Then, configure dbt to generate documentation so that the data models become easy to discover and understand for your team.

📋 What You'll Learn

Create a dbt model file with a simple SQL query

Add a description to the model in the schema.yml file

Configure dbt to generate documentation

Run dbt commands to build and serve the documentation

💡 Why This Matters

🌍 Real World

Teams use dbt documentation to help everyone understand and find data models quickly, improving collaboration and reducing confusion.

💼 Career

Data analysts and engineers often need to document their work so others can trust and use data effectively. Knowing how to document in dbt is a valuable skill.

1

Create a simple dbt model

Create a dbt model file named my_first_model.sql inside the models folder. Write a simple SQL query that selects all columns from the raw_data.customers table.

dbt

-- Create the file models/my_first_model.sql
-- Write the SQL query below

-- Your code here

Need a hint?

Use a simple SELECT * FROM raw_data.customers query in the model file.

2

Add documentation to the model

Create or update the schema.yml file in the models folder. Add a description for the model my_first_model under the models section. Use the description: 'This model selects all customer data from the raw source.'

dbt

select * from raw_data.customers

# Add a schema.yml file with model description
# Your code here

Need a hint?

In schema.yml, add a models list with an entry for my_first_model and a description.

3

Configure dbt to generate documentation

In your dbt project, ensure you have a dbt_project.yml file. Add or confirm the docs section exists with generate: true to enable documentation generation.

dbt

select * from raw_data.customers

models:
  - name: my_first_model
    description: 'This model selects all customer data from the raw source.'

# Add or confirm docs section in dbt_project.yml
# Your code here

Need a hint?

In dbt_project.yml, add a docs section with generate: true to enable documentation.

4

Build and serve the documentation

Run the dbt commands dbt docs generate and dbt docs serve in your terminal to build and view the documentation. This will make your model and its description discoverable in a web browser.

dbt

select * from raw_data.customers

models:
  - name: my_first_model
    description: 'This model selects all customer data from the raw source.'

# dbt_project.yml content
name: 'my_dbt_project'
version: '1.0'
config-version: 2

profile: 'default'

source-paths: ['models']

analysis-paths: ['analysis']

test-paths: ['tests']

data-paths: ['data']

macro-paths: ['macros']

docs:
  generate: true

# Run dbt docs generate and dbt docs serve commands
# Your code here

Need a hint?

Run dbt docs generate to build docs and dbt docs serve to open them in your browser.