remove callout and add tabs as examples (#4402)

addressing @joellabes' request to remove old callouts for alias, database, and schema pages. also added example tabs at the beginning to help provide users with more example at the beginning of the doc
dbt-labs · Nov 8, 2023 · aebba3c · aebba3c
2 parents 050ae3e + 1e7faba
commit aebba3c
Show file tree

Hide file tree

Showing 3 changed files with 218 additions and 33 deletions.
diff --git 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.
 
-:::
+<Tabs>
+<TabItem value="model" label="Models">
 
-## 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 (<Term id="table" />/<Term id="view" />) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments`
+<File name='dbt_project.yml'>
 
-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
+```
+</File>
 
-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`.
+
+</TabItem>
 
+<TabItem value="seeds" label="Seeds">
 
-## 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 <Term id="table" /> 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:
+
+<File name='dbt_project.yml'>
+
+```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 <Term id="table" /> named `country_mappings`.
 
 <File name='dbt_project.yml'>
 
@@ -40,3 +57,68 @@ seeds:
 ```
 
 </File>
+
+</File>
+</TabItem>
+
+<TabItem value="snapshot" label="Snapshots">
+
+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:
+
+<File name='dbt_project.yml'>
+
+```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.
+
+</File>
+</TabItem>
+
+<TabItem value="test" label="Tests">
+
+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:
+
+<File name='schema.yml'>
+
+```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.
+
+</File>
+</TabItem>
+</Tabs>
+
+## 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 (<Term id="table" />/<Term id="view" />) 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
@@ -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.
+<Tabs>
+<TabItem value="model" label="Model">
 
-:::
+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)).
+<File name='dbt_project.yml'>
 
-When dbt creates a relation (<Term id="table" />/<Term id="view" />) in a database, it creates it as: `{{ database }}.{{ schema }}.{{ identifier }}`, e.g. `analytics.finance.payments`
+```yml
+models:
+  your_project:
+    sales_metrics:
+      +database: reporting
+```
+</File>
 
-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.
+</TabItem>
 
-To learn more about changing the way that dbt generates a relation's `database`, read [Using Custom Databases](/docs/build/custom-databases)
+<TabItem value="seeds" label="Seeds">
+
+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
 <File name='dbt_project.yml'>
 
 ```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`.
+
+</File>
+</TabItem>
+
+<TabItem value="test" label="Tests">
+
+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:
 
+<File name='dbt_project.yml'>
+
+```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`.
+
 </File>
+</TabItem>
+</Tabs>
+
+
+## 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 (<Term id="table" />/<Term id="view" />) 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
@@ -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.
+<Tabs>
+<TabItem value="model" label="Model">
 
-:::
+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:
+
+<File name='dbt_project.yml'>
+
+```yml
+models:
+  your_project:
+    marketing: #  Grouping or folder for set of models
+      +schema: marketing
+```
+</File>
+
+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`. 
+</TabItem>
+
+<TabItem value="seeds" label="Seeds">
+
+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:
+
+<File name='dbt_project.yml'>
+
+```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`. 
+</File>
+</TabItem>
+
+<TabItem value="tests" label="Test">
+
+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:
+
+
+<File name='dbt_project.yml'>
+
+```yml
+tests:
+  +store_failures: true
+  +schema: test_results
+```
+
+This would result in the test results being stored in the `test_results` schema.
+</File>
+</TabItem>
+</Tabs>
+
+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)).