one of the best parts about dbt is its
ability to create
a data dictionary for you you can add
documentation to the model or columns
and it'll generate that website for you
and in this video we'll go through how
you can use what's called docs blocks
to better maintain your documentation
and make it a little bit easier to use
as your project grows
we're back in visual studio here where i
have a very simple project
and most importantly what we're
concerned with here is our yaml files
what we've covered up into this point
and what is completely acceptable
in the dbt world is to just write out
your descriptions for each column but
there are some scenarios
where this might not be the best course
of action you know maybe
it's too long maybe you need to reuse it
a bunch of times so what we're doing is
docs blocks
first you know how do we add one well
first we could just add it right in here
if we wanted we could just say
a new file schema.md you have to end it
with the dot
md that's the the one requirement and if
we go back to the documentation we can
see
this is the syntax you have to wrap it
in a jinja docs
tag here so let's let's copy this
we'll just put it in here i'm not going
to adjust this particular description i
just want to show you how it works
so let's say we want to use this
description
as the description of this model let's
just say
right now we have this but we want to
use whatever we've put in here and
what's good about this example is it
shows you
uh how it will keep the formatting so
here we have a we have a link
we have some bullet points you know and
this will be captured in this document
now again how do we use this it's as
simple as this you it's kind of like
adding a ref function or a source any of
those other things that we've touched on
already but instead of
just a doc tag so now let's go back to
our model here let's say we want to put
it as the description for this model
i'm going to paste this in and if we
look at these two side by side just to
recap it's dock and then the name
of the docs jinja block that you put in
here
so here it knows it's docs table events
and here it will know
to reference that here as well now let
me show you how this will look
i'm going to run the commands dbt docs
generate now this is served so let's
take a look at this
models staging which one i think we did
yeah first my first model and if we look
at the description here
this is coming from this docs block
by way of this function right here
and you can see it kept all the
formatting in place we have the link we
have
the bullet points etc you know and then
obviously you could come in here and
edit this do whatever you wanted
and it would reflect it here you don't
need to change it here you just change
it in this docs block
in a common dbt structure you're likely
going to have staging
you might have another folder let's say
for core you know for your let's say
data warehousing models just
the base models and perhaps you have
another one for mart's this is going
based off of
you know some of the suggested layouts
of dbt projects but let's say we're
using this team details and let's say we
have
you know this is the staging model and
then we have
a very similar one here and then let's
say we have the same thing here team
details
mart's again don't worry about the
naming it's just for example
the point being it's very likely that
you're going to have
the same description in multiple places
let's say you need to change the
definition of what the team is for
whatever reason you'd have to change it
here
here and here you know it's over and
over again so a nice use case of docs
blocks here
is to consolidate your definition so
that anytime you make a change
it's just in one place and it will be
reflected throughout you know that
concept of dry
don't repeat yourself so let's look at
that example here one way that you could
set this up potentially
is you could create a folder here called
docs but within here this is where you
can hold all of your
shared documentation so let's say we
have team
details docs or common team details
whatever you want to
call this and in here we can keep all of
the
definitions that we would want that
would be affiliated with this
so let's try that so what we could do
here is you know maybe we want to call
this
team details team name i'll just put all
the columns in here
and what i'll do is copy the
descriptions
for each of these in here you don't need
the
quotations because it's just implied
here and we want to get rid of the white
space here so i'm going to
delete that save and
now what we can do here similar to how
we handled
this with this docs function we can add
this here as well
instead of table events let's say team
details team name
and we'll go through and update these as
well
so now what we can do is this is copy
these
to the rest of them
and you can see how this is going to
play out obviously this is a very small
model there's only three columns here
but once you start to grow out your
project and you have multiple
models with many many columns the
maintenance and the code reviews can get
really out of hand
quickly and using docs blocks is a
really nice way to handle that
that'll do it for this video i hope you
found this helpful if you did
please feel free to like the video it
really does help the channel
leave a comment if you have any
questions and i'll do my best to answer
and i will see you at the next one
thanks for watching