diff --git a/website/docs/reference/resource-configs/alias.md b/website/docs/reference/resource-configs/alias.md index 40da45ebcd1..6b7588ecaf7 100644 --- a/website/docs/reference/resource-configs/alias.md +++ b/website/docs/reference/resource-configs/alias.md @@ -1,33 +1,50 @@ --- 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 --- -:::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. -::: + + -## Definition +Specify a custom alias for a model in your `dbt_project.yml` file or config block. -Optionally specify a custom alias for a [model](/docs/build/models) or [seed](/docs/build/seeds). +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: -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. +```yml +models: + your_project: + sales_total: + +alias: sales_dashboard +``` + -To learn more about changing the way that dbt generates a relation's `identifier`, read [Using Aliases](/docs/build/custom-aliases). +This would return `analytics.finance.sales_dashboard` in the database, instead of the default `analytics.finance.sales_total`. + + + -## Usage -### 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. -The seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. +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. + +In the following second example, the seed at `seeds/country_codes.csv` will be built as a named `country_mappings`. @@ -40,3 +57,68 @@ seeds: ``` + + + + + + +Configure a seed's alias in your `dbt_project.yml` file or config block. + +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: your_snapshot + config: + target_database: analytics + target_schema: finance + unique_key: id + strategy: timestamp + updated_at: updated_at + alias: your_snapshot +``` + +This would return the name `analytics.finance.your_snapshot` in the database. + + + + + + +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: + - name: orders + columns: + - name: order_id + tests: + - unique + alias: unique_order_id_test +``` + +When using `--store-failures`, 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 9c63b0ca457..7d91358ff01 100644 --- a/website/docs/reference/resource-configs/database.md +++ b/website/docs/reference/resource-configs/database.md @@ -2,38 +2,85 @@ 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." --- -:::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. -## Definition +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: -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)). + -When dbt creates a relation (/) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments` +```yml +models: + your_project: + sales_metrics: + +database: reporting +``` + -The standard behavior of dbt is: -* If a custom database is _not_ specified, the database of the relation is the target database (`{{ target.database }}`). -* If a custom database is specified, the database of the relation is the `{{ database }}` value. +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. + -To learn more about changing the way that dbt generates a relation's `database`, read [Using Custom Databases](/docs/build/custom-databases) + + +Configure a database in your `dbt_project.yml` file. -## Usage +For example, to load a seed into a database called `staging` instead of the target database, you can configure it like this: -### Load seeds into the RAW database ```yml seeds: - +database: RAW + 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`. + + + + + + +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`. + + + + + +## Definition + +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` + +The standard behavior of dbt is: +* If a custom database is _not_ specified, the database of the relation is the target database (`{{ target.database }}`). +* If a custom database is specified, the database of the relation is the `{{ database }}` value. + +To learn more about changing the way that dbt generates a relation's `database`, read [Using Custom Databases](/docs/build/custom-databases) + + ## 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 c976bf6502a..3852ee4e639 100644 --- a/website/docs/reference/resource-configs/schema.md +++ b/website/docs/reference/resource-configs/schema.md @@ -1,14 +1,70 @@ --- 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 --- -:::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`. + + + + + +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)).