description
- Models
- Sources
- Seeds
- Snapshots
- Analyses
- Macros
version: 2models:- name: model_namedescription: markdown_stringcolumns:- name: column_namedescription: markdown_string
Definition
A user-defined description. Can be used to document:
- a model, and model columns
- sources, source tables, and source columns
- seeds, and seed columns
- snapshots, and snapshot columns
- analyses, and analysis columns
- macros, and macro arguments
These descriptions are used in the documentation website rendered by dbt (see the documentation guide).
Descriptions can include markdown, as well as the doc
jinja function.
You may need to quote your YAML
Be mindful of YAML semantics when providing a description. If your description contains special yaml characters like curly brackets, colons, or square brackets, you may need to quote your description. An example of a quoted description is shown below.
Examples
Add a simple description to a model and column
version: 2models:- name: dim_customersdescription: One record per customercolumns:- name: customer_iddescription: Primary key
Add a multiline description to a model
You can use YAML block notation to split a longer description over multiple lines:
version: 2models:- name: dim_customersdescription: >One record per customer. Note that a customer must have made a purchase tobe included in this table — customer accounts that were created but neverused have been filtered out.columns:- name: customer_iddescription: Primary key.
Use some markdown in a description
You can use markdown in your descriptions, but you may need to quote your description to ensure the YAML parser doesn't get confused by special characters!
version: 2models:- name: dim_customersdescription: "**[Read more](https://www.google.com/)**"columns:- name: customer_iddescription: Primary key.
Use a docs block in a description
If you have a long description, especially if it contains markdown, it may make more sense to leverage a docs
block. A benefit of this approach is that code editors will correctly highlight markdown, making it easier to debug as you write.
version: 2models:- name: fct_ordersdescription: This table has basic information about orders, as well as some derived facts based on paymentscolumns:- name: statusdescription: '{{ doc("orders_status") }}'
{% docs orders_status %}Orders can be one of the following statuses:| status | description ||----------------|---------------------------------------------------------------------------|| placed | The order has been placed but has not yet left the warehouse || shipped | The order has ben shipped to the customer and is currently in transit || completed | The order has been received by the customer || returned | The order has been returned by the customer and received at the warehouse |{% enddocs %}
Link to another model in a description
You can use relative links to link to another model. It's a little hacky — but to do this:
- Serve your docs site.
- Navigate to the model you want to link to, e.g.
http://127.0.0.1:8080/#!/model/model.jaffle_shop.stg_stripe__payments
- Copy the url_path, i.e. everything after
http://127.0.0.1:8080/
, so in this case#!/model/model.jaffle_shop.stg_stripe__payments
- Paste it as the link
version: 2models:- name: customersdescription: "Filtering done based on [stg_stripe__payments](#!/model/model.jaffle_shop.stg_stripe__payments)"columns:- name: customer_iddescription: Primary key
Include an image from your repo in your descriptions
To include an image from your repository in your descriptions:
- Add the file in a subdirectory, e.g.
assets/dbt-logo.png
- Set the
asset-paths
config in yourdbt_project.yml
file so that this directory gets copied to thetarget/
directory as part ofdbt docs generate
asset-paths: ["assets"]
- Use a Markdown link to the image in your
description:
version: 2models:- name: customersdescription: ""columns:- name: customer_iddescription: Primary key
[CLI users only]
Run
dbt docs generate
— theassets
directory will be copied to thetarget
directoryRun
dbt docs serve
— the image will be rendered as part of your project documentation:
If mixing images and text together, also consider using a docs block.
Include an image from the web in your descriptions
Use the image URL to render the image.
version: 2models:- name: customersdescription: ""columns:- name: customer_iddescription: Primary key
If mixing images and text together, also consider using a docs block.
Use html in a description
You can use html in the description to do fancier things than you can in just markdown. Embedding iframes work too! It is recomended you do this in a docs block for ease of maintenance.
{% docs orders_status %}Here is an image documenting the ERD for this table:<div style="width: 640px; height: 480px; margin: 10px; position: relative;"><iframe allowfullscreen frameborder="0" style="width:640px; height:480px" src="https://your-embed-url.com"></iframe></div>{% enddocs %}