# Model groups

## Groups <a href="#groups" id="groups"></a>

Models can be grouped under a common designation with a shared owner. For example, you could group together all models owned by a particular team, or related to modeling a specific data source (`hubspot`).

* Groups transforms implicit relationships into explicit groupings with a defined owner. By defining interface boundaries between groups, you can create a cleaner, less entangled DAG.
* This approach allows you to designate certain models as having "private" access, intended for exclusive use within that group. Other models will be restricted from referencing or depending on these private models. Eventually, these private models won't be visible to other teams relying on your project—only the "public" models will be accessible.

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 ](https://docs.paradime.io/app-help/~/changes/rDjfrwa4QH3nWWrOItTq/best-practices/data-mesh-setup/model-access)models.

{% hint style="info" %}
Group members may include models, tests, seeds, snapshots, analyses, and metrics. (Not included: sources and exposures.) Each node may belong to only one group.
{% endhint %}

### Declaring a group <a href="#declaring-a-group" id="declaring-a-group"></a>

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

{% code title="models/marts/finance/finance.yml" %}

```yaml
groups:
  - name: finance
    owner:
      # 'name' or 'email' is required; additional properties allowed
      email: finance@acme.com
      slack: finance-data
      github: finance-data-team
```

{% endcode %}

### Adding a model to a group[​](https://docs.getdbt.com/docs/build/groups#adding-a-model-to-a-group) <a href="#adding-a-model-to-a-group" id="adding-a-model-to-a-group"></a>

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

{% tabs %}
{% tab title="Project-level" %}
{% code title="dbt\_project.yml" %}

```yaml
models:
  marts:
    finance:
      +group: finance
```

{% endcode %}
{% endtab %}

{% tab title="Model-level" %}
{% code title="models/schema.yml" %}

```yaml
models:
  - name: model_name
    config:
      group: finance
```

{% endcode %}
{% endtab %}

{% tab title="In-file" %}
{% code title="models/orders.sql" %}

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

select ...
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Referencing a model in a group

By default, all models within a group have the `protected` [access modifier](https://docs.paradime.io/app-help/~/changes/rDjfrwa4QH3nWWrOItTq/best-practices/data-mesh-setup/model-access). 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.

{% code title="models/schema.yml" %}

```yaml
models:
  - name: finance_private_model
    access: private
    config:
      group: finance

  # in a different group!
  - name: marketing_model
    config:
      group: marketingmodels:
  - name: finance_private_model
    access: private
    config:
      group: finance

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

{% endcode %}

{% hint style="info" %}
Each model can only belong to one `group`, and groups cannot be nested. If you set a different `group` in that model's YAML or in-file config, it will override the `group` applied at the project level.
{% endhint %}