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

To customize a package board, copy it into your own charts/<pkg>/: dbt_packages/zendesk/charts/overview.yml becomes charts/zendesk/overview.yml. Both claim the slug zendesk/overview, and your copy replaces the package's: it is the one that is listed, searched, rendered, and linked to, and the package's board with that slug disappears. Package boards you haven't copied keep appearing under zendesk/.... Your copy gets your project's meta.yml layers only, as any board of your own does.

Editing a package board

dbt_packages/ is regenerated by dbt deps, so dbt Charts never writes into it. Editing a package board through the editor, write_file, or an agent saves your own copy at charts/<pkg>/<path> instead, and that copy replaces the package's board (see above). Later edits change your copy. Bulk rewriters such as dct migrate don't copy: pointing one at a package board is an error.

Sourcing a package board's queries

A package ships with no source: of its own — it doesn't know your project's source names. Its boards' queries run against your project's default source instead, the same one a sourceless board of your own would use.

In a dbt project that declares no sources:, there is nothing to set. dbt Charts adds one source named after the profile: in your dbt_project.yml, and package boards run against it: the same warehouse dbt run builds into. See No dbt_charts.yml needed inside a dbt project.

If your dbt_charts.yml declares sources:, name the default in your host charts/meta.yml:

# File: charts/meta.yml
source: warehouse

Without it, a package board's queries fail with ERR-SOURCE-REQUIRED: dbt Charts does not pick one of your sources for you.

With either setup 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 an unknown-source error 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 serves boards for supported Fivetran quickstart packages only. Cloud doesn't run dbt deps, so it reads the versions your project pins in a committed package-lock.yml (or an exact version: in packages.yml when there is no lock). For a supported package at a supported version, such as fivetran/zendesk 1.8.x, its boards appear under /<package>/<board>/ like any other board. Other packages, and versions outside the supported range, show no boards on Cloud. Editing a package board on Cloud saves your copy as charts/<package>/<board>.yml, which then replaces the package's.