Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revisions & additions to Model Versions #3232

Merged
merged 7 commits into from
Apr 26, 2023
Merged

Revisions & additions to Model Versions #3232

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b9049a8
Draft some revisions to model versions
jtcohen6 Apr 20, 2023
cb26fd1
Side-by-side example
jtcohen6 Apr 20, 2023
e263bed
PR feedback
jtcohen6 Apr 24, 2023
8d303df
More feedback
jtcohen6 Apr 24, 2023
8fd1fef
Merge branch 'current' into jerco/more-on-model-versions
mirnawong1 Apr 24, 2023
1ebed2c
PR feedback, self-review
jtcohen6 Apr 25, 2023
1a00757
Final feedbacack
jtcohen6 Apr 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions _redirects
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,6 +278,7 @@ docs/dbt-cloud/using-dbt-cloud/cloud-model-timing-tab /docs/deploy/dbt-cloud-job
/docs/artifacts /docs/dbt-cloud/using-dbt-cloud/artifacts 301
/docs/bigquery-configs /reference/resource-configs/bigquery-configs 301
/reference/resource-properties/docs /reference/resource-configs/docs 301
/reference/resource-properties/latest-version /reference/resource-properties/latest_version 301
/docs/building-a-dbt-project/building-models/bigquery-configs /reference/resource-configs/bigquery-configs 301
/docs/building-a-dbt-project/building-models/configuring-models /reference/model-configs
/docs/building-a-dbt-project/building-models/enable-and-disable-models /reference/resource-configs/enabled 301
Expand Down
2 changes: 1 addition & 1 deletion website/docs/docs/collaborate/govern/model-access.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: "Define model access with group capabilities"
---

:::info New functionality
This functionality is new in v1.5.
This functionality is new in v1.5 — if you have thoughts, participate in [the discussion on GitHub](https://github.com/dbt-labs/dbt-core/discussions/6730)!
:::

## Related documentation
Expand Down
2 changes: 1 addition & 1 deletion website/docs/docs/collaborate/govern/model-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: "Model contracts define a set of parameters validated during transf
---

:::info New functionality
This functionality is new in v1.5.
This functionality is new in v1.5 — if you have thoughts, participate in [the discussion on GitHub](https://github.com/dbt-labs/dbt-core/discussions/6726)!
:::

## Related documentation
Expand Down
344 changes: 318 additions & 26 deletions website/docs/docs/collaborate/govern/model-versions.md
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion website/docs/reference/model-properties.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ models:
[description](description): <markdown_string>
[docs](/reference/resource-configs/docs):
show: true | false
[latest_version](resource-properties/latest-version): <version_identifier>
[latest_version](resource-properties/latest_version): <version_identifier>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i dont understand why an underscore was added here, the actual page is https://docs.getdbt.com/reference/resource-properties/latest-version and a latest_version brings the user to a 'page not found'. suggesting it goes back to the latest-version

Suggested change
[latest_version](resource-properties/latest_version): <version_identifier>
[latest_version](resource-properties/latest-version): <version_identifier>

Copy link
Collaborator Author

@jtcohen6 jtcohen6 Apr 24, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mirnawong1 The name of this resource property is latest_version (underscore). I looked at some other similar properties/configs, and they all have underscores in their file name / id:

So I renamed the page, and added a redirect for it

[access](resource-properties/access): private | protected | public
[config](resource-properties/config):
[<model_config>](model-configs): <config_value>
Expand Down
0 ...nce/resource-properties/latest-version.md → ...nce/resource-properties/latest_version.md
View file
Open in desktop
File renamed without changes.
25 changes: 15 additions & 10 deletions website/docs/reference/resource-properties/versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,15 @@ models:
- v: <version_identifier> # required
defined_in: <file_name> # optional -- default is <model_name>_v<v>
columns:
# include/exclude columns from the top-level model properties
# specify all columns, or include/exclude columns from the top-level model yaml definition
- [include](resource-properties/include-exclude): <include_value>
[exclude](resource-properties/include-exclude): <exclude_list>
# specify additional columns
- name: <column_name> # required
- v: ...

# optional
[latest_version](resource-properties/latest-version): <version_identifier>
[latest_version](resource-properties/latest_version): <version_identifier>
```

</File>
Expand All @@ -35,24 +35,29 @@ The standard convention for naming model versions is `<model_name>_v<v>`. This h

The version identifier for a version of a model. This value can be numeric (integer or float), or any string.

The value of the version identifier is used to order versions of a model relative to one another. If a versioned model does _not_ explicitly configure a [`latest_version`](resource-properties/latest-version), the highest version number is used as the latest version to resolve `ref` calls to the model without a `version` argument.
The value of the version identifier is used to order versions of a model relative to one another. If a versioned model does _not_ explicitly configure a [`latest_version`](resource-properties/latest_version), the highest version number is used as the latest version to resolve `ref` calls to the model without a `version` argument.

In general, we recommend that you use a simple "major versioning" scheme for your models: `v1`, `v2`, `v3`, etc, where each version represents a breaking change from previous versions. However, you are welcome to use other versioning schemes.
In general, we recommend that you use a simple "major versioning" scheme for your models: `1`, `2`, `3`, and so on, where each version reflects a breaking change from previous versions. You are able to use other versioning schemes. dbt will sort your version identifiers alphabetically if the values are not all numeric. You should **not** include the letter `v` in the version identifier, as dbt will do that for you.

### `defined_in`

The name of the model file (excluding the file extension, e.g. `.sql` or `.py`) where the model version is defined.

If `defined_in` is not specified, dbt searches for the definition of a versioned model in a model file named `<model_name>_v<v>`. Model file names must be globally unique, even when defining versioned implementations of a model with a different name.
If `defined_in` is not specified, dbt searches for the definition of a versioned model in a model file named `<model_name>_v<v>`. The **latest** version of a model may also be defined in a file named `<model_name>`, without the version suffix. Model file names must be globally unique, even when defining versioned implementations of a model with a different name.

### Alias
### `alias`

The default `alias` for a versioned model is `<model_name>_v<v>`.
The default resolved `alias` for a versioned model is `<model_name>_v<v>`. The logic for this is encoded in the `generate_alias_name` macro.

This default can be overwritten in two ways:
- Configuring a custom `alias` within the version yaml
- Overwriting dbt's `generate_alias_name` macro, to use different behavior when `node.version`
- Configuring a custom `alias` within the version yaml, or the versioned model's definition
- Overwriting dbt's `generate_alias_name` macro, to use different behavior based on `node.version`

See ["Custom aliases"](https://docs.getdbt.com/docs/build/custom-aliases) for more details.

Setting a different value of `defined_in` does **not** automatically change the `alias` of the model to match. The two are determined independently.
Note that the value of `defined_in` and the `alias` configuration of a model are not coordinated, except by convention. The two are declared and determined independently.

### Our recommendations
- Follow a consistent naming convention for model versions and aliases.
- Use `defined_in` and `alias` only if you have good reason.
- Create a view that always points to the latest version of your model. You can automate this for all versioned models in your project with an `on-run-end` hook. For more details, read the full docs on ["Model versions"](model-versions#configuring-database-location-with-alias)
2 changes: 1 addition & 1 deletion website/sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,7 +459,7 @@ const sidebarSettings = {
"reference/resource-properties/config",
"reference/resource-properties/constraints",
"reference/resource-properties/description",
"reference/resource-properties/latest-version",
"reference/resource-properties/latest_version",
"reference/resource-properties/include-exclude",
"reference/resource-properties/quote",
"reference/resource-properties/tests",
Expand Down