Every dbt project is itself a package that can be imported within other projects. External packages can be imported into your project by creating a
packages.yml file. Packages can be added either from a git repository (like GitHub) or from a local path on your computer. Your
packages.yml file should look something like this:
# add dependencies. these will get pulled during the `dbt deps` process. packages git"https://github.com/fishtown-analytics/snowplow.git" revision0.6.3 # tag or branch name git"https://github.com/fishtown-analytics/dbt-utils.git" revision0.1.21 # tag or branch name local/opt/dbt/redshift # use a local path
Once a package is added to the list above, updated source code for that package can be installed with
dbt deps. Models and macros defined in an included package will be available in the same dependency graph as the models and macros defined within your project. This allows your models to use
ref() on top of models that are built and maintained by others. You can also use macros defined in these packages as though you had defined them yourself! Check out the dbt-utils package for some handy macros that will save you time and effort while modeling your data.
When specifying a package from GitHub in the
packages.yml file, you can optionally specify a
revision can either be the name of a branch, or a tagged release. We strongly recommend "pinning" your package to a specific release by specifying a release name.
If you do not provide a revision, or if you use
master, then any updates to the package will be incorporated into your project the next time you run
dbt deps. While we generally try to avoid making breaking changes to these packages, they are sometimes unavoidable. Pinning a package revision helps prevent your code from changing without your explicit approval.
To find the latest release for a package, navigate to the
Releases tab in the relevant GitHub repository. You can find all of the releases for the dbt-utils package here.
When you remove a package from
packages.yml, it isn't automatically deleted from the
dbt_modules/ directory. If you want to completely uninstall a package, you can either delete the package directory in
dbt_modules/, or you can run
dbt clean to delete all packages, followed by
dbt packages published in public git repositories can be referenced by any other dbt project. There is a growing set of open source dbt packages; here are the ones that we know of:
- Facebook Ads
- Bing Ads
These packages are focused on performing common analytics on top of common datasets. It is also possible to build packages that are not tied directly to specific datasets; for instance, a package that contains macros to create indices in Postgres. As the community grows, we're excited to see what kinds of novel functionality is built and contributed via dbt packages.