dbt - Documentation

Package Management

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.

  - git: "https://github.com/fishtown-analytics/snowplow.git"
    revision: 0.6.3 # tag or branch name
  - git: "https://github.com/fishtown-analytics/dbt-utils.git"
    revision: 0.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.

Specifying package versions

When specifying a package from GitHub in the packages.yml file, you can optionally specify a revision. This 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.

dbt clean

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 deps.

Open source dbt packages

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:

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.

Package Management

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.