From 278840679d1a39c127eb95653ef69643b3473f35 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Mon, 6 Nov 2023 11:23:02 +0000 Subject: [PATCH 1/4] remove callout and add tabs as examples --- .../docs/reference/resource-configs/alias.md | 46 ++++++++++++-- .../reference/resource-configs/database.md | 43 ++++++++++++- .../docs/reference/resource-configs/schema.md | 62 ++++++++++++++++++- 3 files changed, 140 insertions(+), 11 deletions(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 40da45ebcd1..9adfe0b1870 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -4,10 +4,47 @@ description: "Read this guide to understand the alias configuration in dbt." datatype: string --- -:::caution Heads up! -This is a work in progress document. While this configuration applies to multiple resource types, the documentation has only been written for seeds. -::: + + + +Specify a custom alias for a model in your `dbt_project.yml` file. + +For example, if you have a model that calculates `sales_metric`s and want to give it a more user-friendly alias, you can alias it like this: + + + +```yml +models: + your_project: + sales_metrics: + +alias: sales_dashboard +``` + + +This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_metrics`. + + + + +Configure a seed's alias in your `dbt_project.yml` file. + +For example, if you have a seed that represents `product_categories` and want to alias it as `categories_data`, you would alias like this: + + + +```yml +seeds: + your_project: + product_categories: + +alias: categories_data +``` + +This would return the name `analytics.finance.categories_data` in the database. + + + + ## Definition @@ -25,9 +62,8 @@ To learn more about changing the way that dbt generates a relation's `identifier ## Usage ### Seeds -Configure a seed's alias in your `dbt_project.yml` file. -The seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. +In this example, the seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. diff --git a/website/docs/reference/resource-configs/database.md b/website/docs/reference/resource-configs/database.md index 9c63b0ca457..6532483db9d 100644 --- a/website/docs/reference/resource-configs/database.md +++ b/website/docs/reference/resource-configs/database.md @@ -5,10 +5,47 @@ datatype: string description: "Read this guide to understand the database configuration in dbt." --- -:::caution Heads up! -This is a work in progress document. While this configuration applies to multiple resource types, the documentation has only been written for seeds. + + + +Specify a custom database for a model in your `dbt_project.yml` file. + +For example, if you have a model that you want to load into a database other than the target database, you can configure it like this: + + + +```yml +models: + your_project: + sales_metrics: + +database: reporting +``` + + +This would result in the generated relation being located in the `reporting` database, so the full relation name would be `reporting.finance.sales_metrics` instead of the default target database. + + + + +Configure a database in your `dbt_project.yml` file. + +For example, to load a seed into a database called `staging` instead of the target database, you can configure it like this: + + + +```yml +seeds: + your_project: + product_categories: + +database: staging +``` + +This would result in the generated relation being located in the `staging` database, so the full relation name would be `staging.finance.product_categories_data`. + + + + -::: ## Definition diff --git a/website/docs/reference/resource-configs/schema.md b/website/docs/reference/resource-configs/schema.md index c976bf6502a..9b6e2598893 100644 --- a/website/docs/reference/resource-configs/schema.md +++ b/website/docs/reference/resource-configs/schema.md @@ -5,10 +5,66 @@ description: "Schema - Read this in-depth guide to learn about configurations in datatype: string --- -:::caution Heads up! -This is a work in progress document. While this configuration applies to multiple resource types, the documentation has only been written for seeds. + + -::: +Specify a custom schema for a group of models in your `dbt_project.yml` file or a [config block](/reference/resource-configs/schema#models). + +For example, if you have a group of marketing-related models and you want to place them in a separate schema called `marketing`, you can configure it like this: + + + +```yml +models: + your_project: + marketing: # Grouping or folder for set of models + +schema: marketing +``` + + +This would result in the generated relations for these models being located in the `marketing` schema, so the full relation names would be `analytics.marketing.model_name`. + + + + +Configure a custom schema in your `dbt_project.yml` file. + +For example, if you have a seed that should be placed in a separate schema called `mappings`, you can configure it like this: + + + +```yml +seeds: + your_project: + product_mappings: + +schema: mappings +``` + +This would result in the generated relation being located in the `mappings` schema, so the full relation name would be `analytics.mappings.product_mappings_data`. + + + + + +Customize the schema for storing test results in your `dbt_project.yml` file. + +For example, to save test results in a specific schema, you can configure it like this: + + + + +```yml +tests: + +store_failures: true + +schema: test_results +``` + +This would result in the test results being stored in the `test_results` schema. + + + + +Refer to [Usage](#usage) for more examples. ## Definition Optionally specify a custom schema for a [model](/docs/build/sql-models) or [seed](/docs/build/seeds). (To specify a schema for a [snapshot](/docs/build/snapshots), use the [`target_schema` config](/reference/resource-configs/target_schema)). From cfac223f3cf153e6aeff48dc2a2b42737c35e07d Mon Sep 17 00:00:00 2001 From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com> Date: Tue, 7 Nov 2023 09:06:02 +0000 Subject: [PATCH 2/4] Update website/docs/reference/resource-configs/database.md Co-authored-by: Joel Labes --- website/docs/reference/resource-configs/database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/reference/resource-configs/database.md b/website/docs/reference/resource-configs/database.md index 6532483db9d..0586f69e351 100644 --- a/website/docs/reference/resource-configs/database.md +++ b/website/docs/reference/resource-configs/database.md @@ -2,7 +2,7 @@ sidebar_label: "database" resource_types: [models, seeds, tests] datatype: string -description: "Read this guide to understand the database configuration in dbt." +description: "Override the default database when dbt creates resources in your data platform." --- From d434148af12894b8dcd2d13510f8e33ae5ed9185 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Tue, 7 Nov 2023 13:22:21 +0000 Subject: [PATCH 3/4] joel's feedback --- .../docs/reference/resource-configs/alias.md | 87 ++++++++++++++----- .../reference/resource-configs/database.md | 34 +++++--- .../docs/reference/resource-configs/schema.md | 2 +- 3 files changed, 89 insertions(+), 34 deletions(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 9adfe0b1870..94eb9b34561 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -1,32 +1,33 @@ --- resource_types: [models, seeds, snapshots, tests] -description: "Read this guide to understand the alias configuration in dbt." +description: "Aliasing a resource lets you give it a custom name in the database instead of using the filename." datatype: string --- - + Specify a custom alias for a model in your `dbt_project.yml` file. -For example, if you have a model that calculates `sales_metric`s and want to give it a more user-friendly alias, you can alias it like this: +For example, if you have a model that calculates `sales_total` and want to give it a more user-friendly alias, you can alias it like this: ```yml models: your_project: - sales_metrics: + sales_total: +alias: sales_dashboard ``` -This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_metrics`. +This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_total`. + Configure a seed's alias in your `dbt_project.yml` file. For example, if you have a seed that represents `product_categories` and want to alias it as `categories_data`, you would alias like this: @@ -42,37 +43,81 @@ seeds: This would return the name `analytics.finance.categories_data` in the database. +In the following second example, the seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. + + + +```yml +seeds: + jaffle_shop: + country_codes: + +alias: country_mappings + +``` + + + - -## Definition + -Optionally specify a custom alias for a [model](/docs/build/models) or [seed](/docs/build/seeds). +Configure a seed's alias in your `dbt_project.yml` file. -When dbt creates a relation (/) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments` +For example, if you have a snapshot that represents `my_snapshot` and want to alias it as `updated_at_id`, you would alias like this: -The standard behavior of dbt is: -* If a custom alias is _not_ specified, the identifier of the relation is the resource name (i.e. the filename). -* If a custom alias is specified, the identifier of the relation is the `{{ alias }}` value. + -To learn more about changing the way that dbt generates a relation's `identifier`, read [Using Aliases](/docs/build/custom-aliases). +```yml +snapshots: + - name: my_snapshot + config: + target_database: analytics + target_schema: finance + unique_key: id + strategy: timestamp + updated_at: updated_at + +alias: updated_at_id +``` +This would return the name `analytics.finance.updated_at_id` in the database. -## Usage + + + + -### Seeds +Configure a test's alias in your `dbt_project.yml` file. -In this example, the seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. +For example, to add a unique test to the `order_id` column and give it an alias `unique_order_id_test` to identify this specific test, you would alias like this: ```yml -seeds: - jaffle_shop: - country_codes: - +alias: country_mappings - +models: + - name: orders + columns: + - name: order_id + tests: + - unique + +alias: unique_order_id_test ``` +This would return the name `analytics.finance.orders_order_id_unique_order_id_test` in the database. + + + + +## Definition + +Optionally specify a custom alias for a [model](/docs/build/models), [tests](/docs/build/tests), [snapshots](/docs/build/snapshots), or [seed](/docs/build/seeds). + +When dbt creates a relation (/) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments` + +The standard behavior of dbt is: +* If a custom alias is _not_ specified, the identifier of the relation is the resource name (i.e. the filename). +* If a custom alias is specified, the identifier of the relation is the `{{ alias }}` value. + +To learn more about changing the way that dbt generates a relation's `identifier`, read [Using Aliases](/docs/build/custom-aliases). + diff --git a/website/docs/reference/resource-configs/database.md b/website/docs/reference/resource-configs/database.md index 0586f69e351..0a8ee8ab991 100644 --- a/website/docs/reference/resource-configs/database.md +++ b/website/docs/reference/resource-configs/database.md @@ -42,6 +42,27 @@ seeds: This would result in the generated relation being located in the `staging` database, so the full relation name would be `staging.finance.product_categories_data`. + + + + + +Configure a database in your `dbt_project.yml` file. + +For example, to load a test into a database called `reporting` instead of the target database, you can configure it like this: + + + +```yml +tests: + - my_not_null_test: + column_name: order_id + type: not_null + +database: reporting +``` + +This would result in the generated relation being located in the `reporting` database, so the full relation name would be `reporting.finance.my_not_null_test`. + @@ -49,7 +70,7 @@ This would result in the generated relation being located in the `staging` datab ## Definition -Optionally specify a custom database for a [model](/docs/build/sql-models) or [seed](/docs/build/seeds). (To specify a database for a [snapshot](/docs/build/snapshots), use the [`target_database` config](/reference/resource-configs/target_database)). +Optionally specify a custom database for a [model](/docs/build/sql-models), [seed](/docs/build/seeds), or [tests](/docs/build/tests). (To specify a database for a [snapshot](/docs/build/snapshots), use the [`target_database` config](/reference/resource-configs/target_database)). When dbt creates a relation (/) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments` @@ -59,18 +80,7 @@ The standard behavior of dbt is: To learn more about changing the way that dbt generates a relation's `database`, read [Using Custom Databases](/docs/build/custom-databases) -## Usage -### Load seeds into the RAW database - - -```yml -seeds: - +database: RAW - -``` - - ## Warehouse specific information * BigQuery: `project` and `database` are interchangeable diff --git a/website/docs/reference/resource-configs/schema.md b/website/docs/reference/resource-configs/schema.md index 9b6e2598893..1f6e10195ad 100644 --- a/website/docs/reference/resource-configs/schema.md +++ b/website/docs/reference/resource-configs/schema.md @@ -1,7 +1,7 @@ --- sidebar_label: "schema" resource_types: [models, seeds, tests] -description: "Schema - Read this in-depth guide to learn about configurations in dbt." +description: "Override the default schema when dbt creates resources in your data platform." datatype: string --- From 9d76e141b2cb1d25cedb97aeafefb141999ccac0 Mon Sep 17 00:00:00 2001 From: mirnawong1 Date: Wed, 8 Nov 2023 13:02:43 +0000 Subject: [PATCH 4/4] fold in joel's comments --- .../docs/reference/resource-configs/alias.md | 23 ++++++++++--------- .../reference/resource-configs/database.md | 2 +- .../docs/reference/resource-configs/schema.md | 2 +- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 94eb9b34561..6b7588ecaf7 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -8,7 +8,7 @@ datatype: string -Specify a custom alias for a model in your `dbt_project.yml` file. +Specify a custom alias for a model in your `dbt_project.yml` file or config block. For example, if you have a model that calculates `sales_total` and want to give it a more user-friendly alias, you can alias it like this: @@ -23,12 +23,13 @@ models: This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_total`. + -Configure a seed's alias in your `dbt_project.yml` file. +Configure a seed's alias in your `dbt_project.yml` file or config block. For example, if you have a seed that represents `product_categories` and want to alias it as `categories_data`, you would alias like this: @@ -62,36 +63,36 @@ seeds: -Configure a seed's alias in your `dbt_project.yml` file. +Configure a seed's alias in your `dbt_project.yml` file or config block. -For example, if you have a snapshot that represents `my_snapshot` and want to alias it as `updated_at_id`, you would alias like this: +For example, if you have a snapshot that represents `your_snapshot` and want to alias it as `updated_at_id`, you would alias like this: ```yml snapshots: - - name: my_snapshot + - name: your_snapshot config: target_database: analytics target_schema: finance unique_key: id strategy: timestamp updated_at: updated_at - +alias: updated_at_id + alias: your_snapshot ``` -This would return the name `analytics.finance.updated_at_id` in the database. +This would return the name `analytics.finance.your_snapshot` in the database. -Configure a test's alias in your `dbt_project.yml` file. +Configure a test's alias in your `schema.yml` file or config block. For example, to add a unique test to the `order_id` column and give it an alias `unique_order_id_test` to identify this specific test, you would alias like this: - + ```yml models: @@ -100,10 +101,10 @@ models: - name: order_id tests: - unique - +alias: unique_order_id_test + alias: unique_order_id_test ``` -This would return the name `analytics.finance.orders_order_id_unique_order_id_test` in the database. +When using `--store-failures`, this would return the name `analytics.finance.orders_order_id_unique_order_id_test` in the database. diff --git a/website/docs/reference/resource-configs/database.md b/website/docs/reference/resource-configs/database.md index 0a8ee8ab991..7d91358ff01 100644 --- a/website/docs/reference/resource-configs/database.md +++ b/website/docs/reference/resource-configs/database.md @@ -40,7 +40,7 @@ seeds: +database: staging ``` -This would result in the generated relation being located in the `staging` database, so the full relation name would be `staging.finance.product_categories_data`. +This would result in the generated relation being located in the `staging` database, so the full relation name would be `staging.finance.product_categories`. diff --git a/website/docs/reference/resource-configs/schema.md b/website/docs/reference/resource-configs/schema.md index 1f6e10195ad..3852ee4e639 100644 --- a/website/docs/reference/resource-configs/schema.md +++ b/website/docs/reference/resource-configs/schema.md @@ -40,7 +40,7 @@ seeds: +schema: mappings ``` -This would result in the generated relation being located in the `mappings` schema, so the full relation name would be `analytics.mappings.product_mappings_data`. +This would result in the generated relation being located in the `mappings` schema, so the full relation name would be `analytics.mappings.product_mappings`.