knowledge_base: apply review feedback to metric_view examples

Apply Julia's PR #156 inline suggestions (and parallel changes for the
metric_view_dbt variant) plus a few related cleanups surfaced by a
clean-context review:

- Drop the dbt-variant cross-link from metric_view/README.md (don't
  advertise dbt from the canonical example). Keep the inverse link.
- Drop the `workspace:` block (and prod root_path / permissions
  placeholders) from both databricks.yml — let the user's profile pin
  the host.
- Tighten databricks.yml comments: drop the dbt-PR/version reference,
  drop "Bundles do not yet support" staleness risk.
- Periods on variable descriptions.
- README structure: drop redundant subheaders, `## Get started` (not
  "Getting Started With This Project"), `## Learn more` (sentence case),
  `### Notes` instead of `## Advanced Topics`.
- Snippet matches query (no undefined fields), placeholder consistency
  (<catalog>.<your_schema>, no main.<your_schema> mix-up).
- Drop `aws/en/` from doc URLs (also in dbt model file).
- "Once registered" instead of "Once deployed" — accurate, matches
  Julia's suggestion.
- Unify prod schema across variants (dbt prod schema was `default`,
  SQL was `prod` — now both `prod`).
- Drop redundant "view integrates seamlessly with..." marketing line.
- Individual code blocks per command for easy copy-paste.

Co-authored-by: Isaac

Author: lennartkats-db

knowledge_base/metric_view/README.md

@@ -1,9 +1,6 @@
 # Unity Catalog Metric View
 
-This project demonstrates how to create a [Unity Catalog Metric View](https://docs.databricks.com/aws/en/metric-views/) using Declarative Automation Bundles. Once registered, the metric view becomes available to analysts and BI tools across your workspace, queryable via the `MEASURE()` SQL function.
-
-
-## Concrete example: Definition and Usage
+This project demonstrates how to create a [Unity Catalog Metric View](https://docs.databricks.com/metric-views/) using Declarative Automation Bundles. Once registered, the metric view becomes available to analysts and BI tools across your workspace, queryable via the `MEASURE()` SQL function.
 
 ## `bookings_kpis` metric view
 
@@ -32,29 +29,19 @@ $$;
 
 `{{catalog}}` and `{{schema}}` in the SQL file are substituted from job parameters at run time.
 
-### SQL Usage
-
 Once registered, query the metric view from any SQL editor:
 
 ```sql
 SELECT
   check_in_month,
-  MEASURE(total_bookings)    AS bookings,
-  MEASURE(total_revenue)     AS revenue,
-  MEASURE(avg_booking_value) AS aov
-FROM main.<your_schema>.bookings_kpis
-WHERE check_in_date >= '2024-01-01'
+  MEASURE(total_bookings) AS bookings,
+  MEASURE(total_revenue)  AS revenue
+FROM <catalog>.<your_schema>.bookings_kpis
 GROUP BY check_in_month
 ORDER BY check_in_month;
 ```
 
-The view integrates seamlessly with:
-
-- SQL editors and notebooks
-- Databricks SQL dashboards / AI/BI Genie
-- Any BI tool that connects to your workspace
-
-## Getting Started With This Project
+## Get started
 
 ### Prerequisites
 
@@ -64,20 +51,28 @@ The view integrates seamlessly with:
 
 ### Setup
 
-1. In `databricks.yml`, replace `https://company.databricks.com` with your workspace URL, and replace `<your-warehouse-id>` with one of your warehouse IDs (`databricks warehouses list`).
-2. If you don't have write access to `main`, change `catalog:` under `targets.dev.variables` to a catalog you can write to.
+1. In `databricks.yml`, replace `<your-warehouse-id>` (in both `targets.dev` and `targets.prod`) with one of your warehouse IDs (`databricks warehouses list`).
+2. If you don't have write access to `main`, change `catalog:` under `variables` to a catalog you can write to.
 
 ### Deployment
 
 Deploy to dev:
+
 ```bash
 databricks bundle deploy --target dev
+```
+
+```bash
 databricks bundle run bookings_kpis_metric_view --target dev
 ```
 
 Deploy to production:
+
 ```bash
 databricks bundle deploy --target prod
+```
+
+```bash
 databricks bundle run bookings_kpis_metric_view --target prod
 ```
 
@@ -86,10 +81,9 @@ The metric view will be created at `<catalog>.<your_username>.bookings_kpis` (de
 ### Notes
 
 - The job has a daily `periodic` trigger so the view definition is re-applied in production. [Development-mode](https://docs.databricks.com/dev-tools/bundles/deployment-modes.html) pauses the trigger automatically, so it only fires after `bundle deploy --target prod`.
-
 - Set `source:` in the YAML body to any UC table you read from. The sample `samples.wanderbricks.bookings` is convenient for getting started. For production, use a table from your own pipeline.
 
-## Learn More
+## Learn more
 
 - [Unity Catalog Metric Views](https://docs.databricks.com/metric-views/) — Official documentation
 - [Metric View YAML Reference](https://docs.databricks.com/metric-views/yaml-ref)

knowledge_base/metric_view/databricks.yml

@@ -1,12 +1,8 @@
 # This example bundle defines a job that creates a Unity Catalog Metric View.
 #
-# Metric Views are a Unity Catalog feature 
-# that let you declare reusable dimensions and measures over a base table, queryable
-# via the MEASURE() SQL function. Bundles do not yet support metric views as
-# a resource type, so this example uses a SQL task in a job to run
-# `CREATE OR REPLACE VIEW ... WITH METRICS LANGUAGE YAML`.
-#
-# See also the dbt-based variant at ../metric_view-dbt.
+# Metric Views are a Unity Catalog feature that let you declare reusable
+# dimensions and measures over a base table, queryable via the MEASURE() SQL
+# function.
 #
 # Docs:
 #   https://docs.databricks.com/metric-views/
@@ -20,31 +16,23 @@ include:
 
 variables:
   catalog:
-    description: The Unity Catalog where the metric view will be created
+    description: The Unity Catalog where the metric view will be created.
   schema:
-    description: The schema where the metric view will be created
+    description: The schema where the metric view will be created.
   warehouse_id:
     description: SQL warehouse ID used to run the CREATE VIEW statement. To list available warehouses, use `databricks warehouses list`.
 
 targets:
   dev:
     mode: development
     default: true
-    workspace:
-      host: https://company.databricks.com
     variables:
       catalog: main
       schema: ${workspace.current_user.short_name}
       warehouse_id: <your-warehouse-id>
   prod:
     mode: production
-    workspace:
-      host: https://company.databricks.com
-      root_path: /Workspace/Users/user@company.com/.bundle/${bundle.name}/${bundle.target}
     variables:
       catalog: main
       schema: prod
       warehouse_id: <your-warehouse-id>
-    permissions:
-      - user_name: user@company.com
-        level: CAN_MANAGE

knowledge_base/metric_view/src/bookings_kpis.metric_view.sql

@@ -3,7 +3,7 @@
 --
 -- Once deployed and run, query the metric view from any SQL editor with:
 --   SELECT MEASURE(total_bookings), MEASURE(total_revenue)
---   FROM <catalog>.<schema>.bookings_kpis
+--   FROM <catalog>.<your_schema>.bookings_kpis
 --   WHERE check_in_month >= '2024-01-01'
 --   GROUP BY check_in_month;
 

knowledge_base/metric_view_dbt/README.md

@@ -1,15 +1,13 @@
 # Unity Catalog Metric View using dbt
 
-This project demonstrates how to materialize a [Unity Catalog Metric View](https://docs.databricks.com/metric-views/) via dbt-databricks using Declarative Automation Bundles. The metric view is defined as a dbt model with the [`metric_view` materialization](https://github.com/databricks/dbt-databricks/pull/1285) added in **dbt-databricks 1.12.0**.
+This project demonstrates how to materialize a [Unity Catalog Metric View](https://docs.databricks.com/metric-views/) via dbt-databricks using Declarative Automation Bundles. The metric view is defined as a dbt model with the [`metric_view` materialization](https://github.com/databricks/dbt-databricks/pull/1285) added in dbt-databricks 1.12.0.
 
-**Learn more:** [Unity Catalog Metric Views](https://docs.databricks.com/aws/en/metric-views/) · SQL-job variant: [`../metric_view`](../metric_view)
+For the SQL-job variant, see [`../metric_view`](../metric_view).
 
-## Concrete example: Definition and Usage
+## `bookings_kpis` metric view
 
 This project defines `bookings_kpis`, a metric view over the public sample dataset `samples.wanderbricks.bookings`.
 
-### Metric View Definition (dbt model)
-
 The model lives in [`src/models/bookings_kpis.sql`](src/models/bookings_kpis.sql):
 
 ```sql
@@ -30,68 +28,62 @@ measures:
 
 The `{{ config(materialized='metric_view') }}` line is the only jinja; everything below it is the metric view YAML body. dbt-databricks issues the equivalent `CREATE OR REPLACE VIEW … WITH METRICS LANGUAGE YAML` against the warehouse at `dbt run` time.
 
-### SQL Usage
-
 Once materialized, query the metric view from any SQL editor:
 
 ```sql
 SELECT
   check_in_month,
-  MEASURE(total_bookings)    AS bookings,
-  MEASURE(total_revenue)     AS revenue,
-  MEASURE(avg_booking_value) AS aov
-FROM main.<your_schema>.bookings_kpis
-WHERE check_in_date >= '2024-01-01'
+  MEASURE(total_bookings) AS bookings,
+  MEASURE(total_revenue)  AS revenue
+FROM <catalog>.<your_schema>.bookings_kpis
 GROUP BY check_in_month
 ORDER BY check_in_month;
 ```
 
-The view integrates seamlessly with:
-
-- SQL editors and notebooks
-- Databricks SQL dashboards / AI/BI Genie
-- Any BI tool that connects to your workspace
-
-## Getting Started With This Project
+## Get started
 
 ### Prerequisites
 
 * Databricks workspace with Unity Catalog enabled
-* A SQL warehouse on a runtime that supports Unity Catalog metric views (Public Preview; any recent serverless or PRO warehouse)
+* A SQL warehouse on a runtime that supports Unity Catalog metric views
 * Databricks CLI installed and configured
 
 ### Setup
 
-1. In `databricks.yml`, replace `https://company.databricks.com` with your workspace URL.
-2. In `dbt_profiles/profiles.yml`, set `http_path` to one of your warehouses (`databricks warehouses list`) and update `catalog` to one you can write to (the default `main` is often not writable).
+1. In `dbt_profiles/profiles.yml`, set `http_path` (in both `dev` and `prod`) to one of your warehouses (`databricks warehouses list`) and update `catalog` to one you can write to (the default `main` is often not writable).
 
 ### Deployment
 
 Deploy to dev:
+
 ```bash
 databricks bundle deploy --target dev
+```
+
+```bash
 databricks bundle run metric_view_dbt_job --target dev
 ```
 
 Deploy to production:
+
 ```bash
 databricks bundle deploy --target prod
-databricks bundle run metric_view_dbt_job --target prod
 ```
 
-The metric view will be created at `<catalog>.<your_username>.bookings_kpis` (dev) or `<catalog>.default.bookings_kpis` (prod).
-
-## Advanced Topics
-
-**Scheduling:** The job has a daily `periodic` trigger so `dbt run` re-applies the view definition in production. [Development-mode](https://docs.databricks.com/dev-tools/bundles/deployment-modes.html) deploys pause the trigger automatically, so it only fires after `bundle deploy --target prod`.
+```bash
+databricks bundle run metric_view_dbt_job --target prod
+```
 
-**dbt-databricks version:** Requires `dbt-databricks >= 1.12.0` (the `metric_view` materialization). The job pins this in its task environment (`resources/metric_view_dbt.job.yml`).
+The metric view will be created at `<catalog>.<your_username>.bookings_kpis` (dev) or `<catalog>.prod.bookings_kpis` (prod).
 
-**File extension:** The model file is `.sql` even though its body is YAML — dbt model files must use `.sql`. dbt-databricks wraps the body in `CREATE OR REPLACE VIEW … LANGUAGE YAML AS $$ … $$` at run time.
+### Notes
 
-**Custom source table:** Point `source:` in the YAML body at any UC table you read from. For production, replace the public `samples.wanderbricks.bookings` with a curated table from your own pipeline.
+- The job has a daily `periodic` trigger so `dbt run` re-applies the view definition in production. [Development-mode](https://docs.databricks.com/dev-tools/bundles/deployment-modes.html) pauses the trigger automatically, so it only fires after `bundle deploy --target prod`.
+- Requires `dbt-databricks >= 1.12.0` (the version that introduced the `metric_view` materialization). The job pins this in its task environment.
+- The model file is `.sql` even though its body is YAML — dbt model files must use `.sql`. dbt-databricks wraps the body in `CREATE OR REPLACE VIEW … LANGUAGE YAML AS $$ … $$` at run time.
+- Set `source:` in the YAML body to any UC table you read from. For production, replace `samples.wanderbricks.bookings` with a table from your own pipeline.
 
-## Learn More
+## Learn more
 
 - [Unity Catalog Metric Views](https://docs.databricks.com/metric-views/) — Official documentation
 - [Metric View YAML Reference](https://docs.databricks.com/metric-views/yaml-ref)

knowledge_base/metric_view_dbt/databricks.yml

@@ -1,15 +1,14 @@
-# This bundle creates a Unity Catalog Metric View using dbt-databricks.
+# This example bundle materializes a Unity Catalog Metric View using dbt-databricks.
 #
-# Metric Views are a Unity Catalog feature (Public Preview, Databricks Runtime 16.4+)
-# that let you declare reusable dimensions and measures over a base table, queryable
-# via the MEASURE() SQL function. dbt-databricks added a first-class `metric_view`
-# materialization in v1.12.0 (https://github.com/databricks/dbt-databricks/pull/1285).
+# Metric Views are a Unity Catalog feature that let you declare reusable
+# dimensions and measures over a base table, queryable via the MEASURE() SQL
+# function.
 #
 # See also the SQL-job variant at ../metric_view.
 #
 # Docs:
-#   https://docs.databricks.com/aws/en/metric-views/
-#   https://docs.databricks.com/aws/en/metric-views/yaml-ref
+#   https://docs.databricks.com/metric-views/
+#   https://docs.databricks.com/metric-views/yaml-ref
 #   https://docs.getdbt.com/reference/resource-configs/databricks-configs
 
 bundle:
@@ -19,24 +18,10 @@ include:
   - resources/*.yml
 
 # Deployment targets.
-# The default schema/catalog for dbt are in dbt_profiles/profiles.yml.
+# The schema and catalog for dbt are configured in dbt_profiles/profiles.yml.
 targets:
   dev:
-    # 'mode: development' creates a development copy:
-    # - Deployed resources are prefixed with '[dev my_user_name]'.
-    # - Job schedules/triggers are paused by default.
-    # See https://docs.databricks.com/dev-tools/bundles/deployment-modes.html.
     mode: development
     default: true
-    workspace:
-      host: https://company.databricks.com
-
   prod:
     mode: production
-    workspace:
-      host: https://company.databricks.com
-      # Pin the deploy root so a single copy of the bundle lives in production.
-      root_path: /Workspace/Users/user@company.com/.bundle/${bundle.name}/${bundle.target}
-    permissions:
-      - user_name: user@company.com
-        level: CAN_MANAGE

knowledge_base/metric_view_dbt/dbt_profiles/profiles.yml

@@ -24,7 +24,7 @@ metric_view_dbt:
       type: databricks
       method: http
       catalog: main
-      schema: default
+      schema: prod
 
       http_path: /sql/1.0/warehouses/abcdef1234567890
 

knowledge_base/metric_view_dbt/src/models/bookings_kpis.sql

@@ -2,7 +2,7 @@
   A Unity Catalog Metric View, materialized by dbt-databricks.
 
   Everything below the `config(...)` line is the metric-view YAML body (see
-  https://docs.databricks.com/aws/en/metric-views/yaml-ref). The metric_view
+  https://docs.databricks.com/metric-views/yaml-ref). The metric_view
   materialization wraps it in:
 
       CREATE OR REPLACE VIEW <relation> WITH METRICS LANGUAGE YAML AS <yaml>
@@ -18,7 +18,7 @@
         MEASURE(total_bookings)    AS bookings,
         MEASURE(total_revenue)     AS revenue,
         MEASURE(avg_booking_value) AS aov
-      FROM main.<your_schema>.bookings_kpis
+      FROM <catalog>.<your_schema>.bookings_kpis
       WHERE check_in_date >= '2024-01-01'
       GROUP BY check_in_month
       ORDER BY check_in_month;