dbt model access and groups

1.What model governance controls

Once other teams build on your models, those models become interfaces, and model governance is how dbt lets you manage them that way. It answers three questions about a model: who is allowed to ref it, what shape it is guaranteed to have, and how it may change over time. Each question has its own feature. All of them work in dbt v1 and on the dbt platform except project dependencies, which need an Enterprise-tier plan.

Cross-project references are built on access. A downstream project can only reach the models its producer has marked access: public, and that marker is the intentional interface the maintainer has designated. Wiring up the dependency itself is covered under [setting up additional projects](lesson:7.1). This lesson is about the governance that decides what the dependency is allowed to see.

Governance has a cost, so adopt it on purpose. Access, contracts and versions add structure, and structure makes some rollbacks harder: once consumers depend on a public model, removing that access breaks them. If you add governance while models are still being reshaped every week, every reshape turns into a negotiation. Put it on models that have settled.

Governance applies only to models. Snapshots, seeds and sources cannot be made public, contracted or versioned. Their structure can change over time (a snapshot captures evolving history, for example), so they don't suit those guarantees.

Sources12

2.Groups define ownership boundaries

A group is a named collection of nodes in the DAG, and every group has an owner. Groups do two things. They turn an implicit relationship, such as "these are the finance models", into an explicit one with someone responsible for it. They also give private access its meaning: a private model can be referenced only from inside its own group. Thinking about the interfaces between groups tends to produce a less tangled DAG, and those interfaces are natural candidates for the seams between separate projects later on.

Groups are declared in YAML under a groups: key. Each one needs a name that is unique in the project and an owner with at least a name: or email:. From v1.10 a group can also take a description and config.meta, for things like a cost centre or a data classification. To keep the definitions in one place, use a single _groups.yml at the root of the models directory. Alternatively, put it at the root of a groups directory and add that directory to model-paths.

You can assign membership at three levels: in dbt_project.yml for a whole folder, in a model's YAML, or in a config() block inside the SQL file. Most well-structured projects already use subdirectories, so the project-level form usually does most of the work:

models:
  my_project_name:
    marts:
      customers:
        +group: customer_success
      finance:
        +group: finance

Membership is strict. A node belongs to at most one group, and groups cannot be nested. Models, tests, seeds, snapshots, analyses and metrics can be members. Sources and exposures cannot. A group set in a model's YAML or in-file config overrides the folder-level assignment, so one model can be moved out of its folder's group without restructuring the directory.

Sources34

3.Private, protected and public access

The access modifier sets how far a model's ref reaches. There are three levels, and each one widens the audience of the one before it.

Protected is the default so that existing projects don't break when groups are introduced, because their references may already cross the new boundaries. For new models, set private instead. That stops other parts of the project from depending on a model nobody designed for sharing. Promote a model to public when it really is a product, and rerun a production job afterwards so the change takes effect.

# First, define the group and owner
groups:
  - name: customer_success
    owner:
      name: Customer Success Team
      email: cx@jaffle.shop

# Then, add 'group' + 'access' modifier to specific models
models:
  # This is a public model -- it's a stable & mature interface for other teams/projects
  - name: dim_customers
    config:
      group: customer_success # changed to config in v1.10
      access: public # changed to config in v1.10

  # This is a private model -- it's an intermediate transformation intended for use in this context *only*
  - name: int_customer_history_rollup
    config:
      group: customer_success # changed to config in v1.10
      access: private # changed to config in v1.10

dbt enforces access at parse time. If marketing_model in the marketing group refs a model that is private to finance, the run stops with a DbtReferenceError saying the referenced node is private to the finance group. No SQL reaches the warehouse. There is one more restriction to know: a model with materialized='ephemeral' cannot be public, and dbt parse rejects that combination as an invalid value for the access field.

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

Sources43

4.Where access rules stop

Access controls who may build on a model in dbt. It does not control who can query the data. Setting public signals that other teams may take a dependency, on the assumption that they have asked for and been granted select on the underlying dataset. You grant that separately. Typical moves are to use the grants config to open public models to downstream queriers, and to restrict private ones by revoking default grants or landing them in a different schema.

Inside the dbt account, access lines up with development permissions. Anyone who can develop in a project can see and change every model in it, private ones included. A user in the same account who can't develop there can't see its private models and can depend only on its public ones.

There are two places where dbt does not enforce access at all, and both catch people out:

- **dbt run-operation.** A macro invoked this way can ref() any model, private and protected included, because group and access controls are not enforced. - Package dependencies. When another project is installed as a package, its source code becomes part of your runtime. Access restrictions are off by default, so protected models can be referenced as if they were your own, and private ones too when your model shares their group.

A package maintainer can close that gap from their own dbt_project.yml. With the flag below set, any ref from outside the package to a protected or private model fails, and only public models can be reached. Project dependencies on dbt Enterprise behave differently: they resolve refs through a metadata service, and only public models are reachable.

restrict-access: True  # default is False

Sources4

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Models with no access setting are private to their group.Why is that wrong?

   The default is protected, so any model in the same project can ref them. Set private explicitly on new models that shouldn't be shared.

   Covered in Private, protected and public access

2. 2.Marking a model access: public grants downstream users select on it in the warehouse.Why is that wrong?

   Access only governs who may ref the model in dbt. Warehouse permissions are managed separately, for example with the grants config.

   Covered in Where access rules stop

3. 3.Any model, including an ephemeral one, can be published as public.Why is that wrong?

   Ephemeral models cannot have public access. dbt parse fails with an invalid value error for the access field.

   Covered in Private, protected and public access