From bf5b7fcf174d434aae475ebfdad7556e3204dd55 Mon Sep 17 00:00:00 2001
From: Jack Sandom <jack.sandom@databricks.com>
Date: Mon, 11 May 2026 16:22:46 +0100
Subject: [PATCH] docs(skill/databricks-metric-views): add Update section + UDF
 gotcha
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two additive doc fixes for non-MCP metric view authoring on experimental:

1. New "Update an Existing Metric View" subsection under SQL Operations.
   Metric views don't support ALTER VIEW ... ADD MEASURE — the only path
   is CREATE OR REPLACE VIEW with the complete updated YAML. Includes a
   worked example (adding Average Order Value to orders_metrics) with
   line-by-line ← unchanged / ← new annotations so the full-replacement
   requirement is visually obvious.

2. New row in Common Issues: Python UDFs are not supported in measure
   expressions (use built-in SQL aggregates or SQL UDFs; for custom
   logic push into the source or wrap as a SQL UDF in UC).

stf compare A/B vs origin/experimental (L3 static + L5 output,
agent-model claude-sonnet-4-6 via Anthropic OAuth):

  Composite: A=0.641 vs B=0.617  (+0.024)
  L3 static: A=0.8753 vs B=0.8752  (≈0)
  L5 output: A=0.407  vs B=0.359  (+0.047)
  Feedback pass rate: 166/250 vs 146/249  (66% vs 59%, +8 pts)

Both targeted test cases improved:
  metric-views_alter_010:           4/8 vs 2/8  (+25 pts)
  metric-views_udf_not_supported_021: 9/10 vs 7/10 (+20 pts)

Judge verdict: TIE (low confidence 0.20) — judge sampled a single test
case where artifacts were near-identical. Aggregated pass-rate across all
250 feedback rows shows the small but consistent positive lift above.

Composite below 0.7 gate on both branches is due to (a) an install-banner
hook polluting agent subprocess responses (separate bug worth filing) and
(b) ground_truth scaffold staleness, not the fix itself.

Co-authored-by: Isaac
---
 .../databricks-metric-views/SKILL.md          | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/databricks-skills/databricks-metric-views/SKILL.md b/databricks-skills/databricks-metric-views/SKILL.md
index c8b57a34..273726e1 100644
--- a/databricks-skills/databricks-metric-views/SKILL.md
+++ b/databricks-skills/databricks-metric-views/SKILL.md
@@ -118,6 +118,41 @@ AS $$
 $$;
 ```
 
+### Update an Existing Metric View
+
+Metric views do **not** support `ALTER VIEW … ADD MEASURE` syntax — there's no in-place way to append a single dimension or measure. To update one, re-issue `CREATE OR REPLACE VIEW` with the **complete** updated YAML (every existing dimension/measure plus the new one). Omitting an existing entry deletes it.
+
+Adding a new measure `Average Order Value` to the `orders_metrics` view above:
+
+```sql
+CREATE OR REPLACE VIEW catalog.schema.orders_metrics
+WITH METRICS
+LANGUAGE YAML
+AS $$
+  version: 1.1
+  comment: "Orders KPIs for sales analysis"
+  source: catalog.schema.orders
+  filter: order_date > '2020-01-01'
+  dimensions:                          # ← unchanged, repeated verbatim
+    - name: Order Month
+      expr: DATE_TRUNC('MONTH', order_date)
+      comment: "Month of order"
+    - name: Order Status
+      expr: status
+  measures:
+    - name: Order Count                # ← unchanged
+      expr: COUNT(1)
+    - name: Total Revenue              # ← unchanged
+      expr: SUM(total_price)
+      comment: "Sum of total price"
+    - name: Average Order Value        # ← new
+      expr: SUM(total_price) / COUNT(1)
+      comment: "Revenue divided by order count"
+$$;
+```
+
+To get the current definition before editing (so you don't accidentally drop entries), run `SHOW CREATE TABLE catalog.schema.orders_metrics` — see [Describe Metric View](#describe-metric-view) below.
+
 ### Query Metric View
 
 ```sql
@@ -277,6 +312,7 @@ materialization:                # Optional (experimental)
 | **MEASURE() required** | All measure references must be wrapped: `MEASURE(\`name\`)` |
 | **DBR version error** | Requires Runtime 17.2+ for YAML v1.1, or 16.4+ for v0.1 |
 | **Materialization not working** | Requires serverless compute enabled; currently experimental |
+| **Python UDFs in measure expressions** | Not supported. Measure `expr` must use built-in SQL aggregates (`SUM`, `COUNT`, `AVG`, etc.) or SQL UDFs — Python UDFs (`@udf`, `pandas_udf`) are rejected. For custom logic, push the transformation into the source table or wrap in a SQL UDF defined separately in UC. |
 
 ## Integrations