Add groups to your DAG

A group is a collection of nodes within a dbt DAG. Groups are named, and every group has an owner. They enable intentional collaboration within and across teams by restricting access to private models.

Group members may include models, tests, seeds, snapshots, analyses, and metrics. (Not included: sources and exposures.) Each node may belong to only one group.

Declaring a group

Groups are defined in .yml files, nested under a groups: key.

Centrally defining a group

To centrally define a group in your project, there are two options:

• Create one _groups.yml file in the root of the models directory.

• Create one _groups.yml file in the root of a groups directory. For this option, you also need to configure model-paths in the dbt_project.yml file:

  model-paths: ["models", "groups"]

Adding a model to a group

Use the group configuration to add one or more models to a group.

Project-level

dbt_project.yml

models:
  marts:
    finance:
      +group: finance

Model-level

models/schema.yml

models:
  - name: model_name
    config:
      group: finance

In-file

models/model_name.sql

{{ config(group = 'finance') }}

select ...

Referencing a model in a group

By default, all models within a group have the protected access modifier. This means they can be referenced by downstream resources in any group in the same project, using the ref function. If a grouped model's access property is set to private, only resources within its group can reference it.

models/schema.yml

models:
  - name: finance_private_model
    config:
      access: private # changed to config in v1.10
      group: finance

  # in a different group!
  - name: marketing_model
    config:
      group: marketing

models/marketing_model.sql

select * from {{ ref('finance_private_model') }}

$ dbt run -s marketing_model
...
dbt.exceptions.DbtReferenceError: Parsing Error
  Node model.jaffle_shop.marketing_model attempted to reference node model.jaffle_shop.finance_private_model, 
  which is not allowed because the referenced node is private to the finance group.

Related docs

• Model Access
• Group configuration
• Group selection