Skip to content

Commit

Permalink
clarify macro properties aren't supported in dbt_project.yml (#3989)
Browse files Browse the repository at this point in the history
After convo with jerco and [per slack
convo](https://getdbt.slack.com/archives/C2JRRQDTL/p1693287414438449),
clarify in the docs that macro properties aren't support in
dbt_project.yml file.

adding a note in the following pages:
 
- https://docs.getdbt.com/reference/dbt_project.yml
- https://docs.getdbt.com/reference/resource-configs/docs
- https://docs.getdbt.com/reference/macro-properties

note - not sure how semantic models/metrics are added here
  • Loading branch information
mirnawong1 authored Dec 18, 2023
2 parents ee9f05f + 9225af1 commit cb5c283
Show file tree
Hide file tree
Showing 2 changed files with 9 additions and 9 deletions.
10 changes: 4 additions & 6 deletions website/docs/reference/configs-and-properties.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Configs, properties, what are they?
---

Resources in your project—models, snapshots, seeds, tests, and the rest—can have a number of declared **properties**. Resources can also define **configurations**, which are a special kind of property that bring extra abilities. What's the distinction?
- Properties are declared for resources one-by-one in `.yml` files. Configs can be defined there, nested under a `config` property. They can also be set one-by-one via a `config()` macro (right within `.sql` files), and for many resources at once in `dbt_project.yml`.
- Properties are declared for resources one-by-one in `properties.yml` files. Configs can be defined there, nested under a `config` property. They can also be set one-by-one via a `config()` macro (right within `.sql` files), and for many resources at once in `dbt_project.yml`.
- Because configs can be set in multiple places, they are also applied hierarchically. An individual resource might _inherit_ or _override_ configs set elsewhere.
- You can select resources based on their config values using the `config:` selection method, but not the values of non-config properties

Expand Down Expand Up @@ -46,9 +46,7 @@ Most configurations are "clobbered" when applied hierarchically. Whenever a more

## Where can I define properties?

In dbt, properties are declared in `.yml` files, in the same directory as your resources.

You can name these files `whatever_you_want.yml` and nest them arbitrarily deeply in subfolders within each directory.
In dbt, you can use `properties.yml` files to define properties for resources. You can declare properties in `.yml` files, in the same directory as your resources. You can name these files `whatever_you_want.yml` and nest them arbitrarily in sub-folders within each directory.

We highly recommend that you define properties in dedicated paths alongside the resources they're describing.

Expand All @@ -58,13 +56,13 @@ We highly recommend that you define properties in dedicated paths alongside the

Previous versions of the docs referred to these as `schema.yml` files — we've moved away from that terminology since the word `schema` is used to mean other things when talking about databases, and people often thought that you _had_ to name these files `schema.yml`.

(Of course, you're still free to name your files `schema.yml`)
Instead, we now refer to these files as `properties.yml` files. (Of course, you're still free to name your files `schema.yml`)

:::

### Which properties are _not_ also configs?

dbt has the ability to define node configs in `.yml` files, in addition to `config()` blocks and `dbt_project.yml`. But the reverse isn't always true: there are some things in `.yml` files that can _only_ be defined there.
In dbt, you can define node configs in `properties.yml` files, in addition to `config()` blocks and `dbt_project.yml`. However, some special properties can only be defined in the `.yml` file and you cannot configure them using `config()` blocks or the `dbt_project.yml` file:

Certain properties are special, because:

Expand Down
8 changes: 5 additions & 3 deletions website/docs/reference/dbt_project.yml.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,15 @@ Starting from dbt v1.5 and higher, you can specify your dbt Cloud project ID in

</VersionBlock>

The following is a list of all available configurations in the `dbt_project.yml` file.

:::info YAML syntax
dbt uses YAML in a few different places. If you're new to YAML, it would be worth taking the time to learn how arrays, dictionaries and strings are represented.
dbt uses YAML in a few different places. If you're new to YAML, it would be worth taking the time to learn how arrays, dictionaries, and strings are represented.
:::


Something to note, you can't set up a "property" in the `dbt_project.yml` file if it's not a config (an example is [macros](/reference/macro-properties)). This applies to all types of resources. Refer to [Configs and properties](/reference/configs-and-properties) for more detail.

The following example is a list of all available configurations in the `dbt_project.yml` file:

<VersionBlock firstVersion="1.7">

<File name='dbt_project.yml'>
Expand Down

0 comments on commit cb5c283

Please sign in to comment.