Skip to content

Boards Shipped in a dbt Package

A dbt package can ship its own boards alongside its models and macros. Once the package is installed, its boards are discovered automatically, the same way ref('zendesk', 'zendesk__ticket_metrics') reaches that package's models today. There is nothing to configure.

Where a package puts its boards

A package that ships boards puts them in its own charts/ directory, at the package's root, the same place your own project puts its boards:

dbt_zendesk/                     # the package, as dbt deps installs it
├── charts/
│   ├── overview.yml
│   └── meta.yml
├── models/
│   └── ...
└── dbt_project.yml

dbt deps copies that into your project's dbt_packages/ directory:

my_project/
├── charts/                      # your own boards
│   └── home.yml
├── dbt_packages/
│   └── dbt_zendesk/
│       └── charts/              # the package's boards — discovered automatically
│           ├── overview.yml
│           └── meta.yml
└── dbt_project.yml

dct serve, dct validate, dct render, and dct impact all discover a package's charts/ directory the moment dbt deps installs it — no config key opts a package in or out.

How package boards appear

A package's boards are namespaced by the package's directory name under dbt_packages/ — the same name dbt derived from the package's own name: when dbt deps installed it. dbt_packages/zendesk/charts/overview.yml serves at /zendesk/overview/, the same way charts/home.yml serves at /. A package board's own index (dbt_packages/zendesk/charts/index.yml) serves at the bare package path, /zendesk/.

If a host charts/zendesk/ directory (or charts/zendesk.yml file) and an installed zendesk package both exist, dct serve refuses to start: the namespace is claimed twice and there's no principled way to pick a winner. Rename one side.

Boards are read-only

dbt_packages/ is regenerated by dbt deps and is not meant to be hand-edited — dbt itself gitignores it. Writing to a package board through any dbt charts surface (the editor, write_file, dct migrate) fails outright rather than silently landing an edit dbt deps would later overwrite. To change a package's boards, change the package.

Sourcing a package board's queries

A package ships with no source: of its own — it doesn't know your project's source names. Instead, a package board's queries resolve against your project's own default source, set the same way any board's does: source: in your host charts/meta.yml.

# File: charts/meta.yml
source: warehouse

With that in place, every package board compiles unmodified. A package board that names its own source: explicitly resolves it against your project's dbt_charts.yml the normal way, and fails with the same ERR-SOURCE-REQUIRED/unknown-source errors a host board would if it doesn't exist.

A package's own meta.yml still applies for everything that isn't a source name — style defaults, shared queries, lint suppressions — layered inside your host charts/meta.yml, so a package default never silently overrides a project-wide one.

Picking up a package update

dct serve notices a dbt deps re-run the same way it notices an edit under charts/ — no restart needed. A Linking Between Boards link: from one of your own boards into a package board that a later dbt deps removes (the package dropped or renamed it) reads as a stale link, the same as linking to any board that no longer exists.

Scope

  • Hub and git packages only. A local:-installed package is a symlink into another directory on disk, outside your project root — the same containment guard that keeps a board from reading a file outside the project excludes it. This is a package-developer workflow, not something a package's users hit; ship the package as a real hub or git dependency and it works normally.
  • packages-install-path overrides are not honored. Discovery assumes the default dbt_packages/ location.
  • Cloud does not discover package boards yet. Cloud reads a project's charts/ directory from its own git-backed store and doesn't run dbt deps, so it can't see dbt_packages/ until it can install packages itself — tracked separately.