Skip to content

fix: resolve doc() docs blocks in metric_view model bodies#1504

Open
wxy-zzz wants to merge 1 commit into
databricks:mainfrom
wxy-zzz:fix/metric-view-doc-1501
Open

fix: resolve doc() docs blocks in metric_view model bodies#1504
wxy-zzz wants to merge 1 commit into
databricks:mainfrom
wxy-zzz:fix/metric-view-doc-1501

Conversation

@wxy-zzz

@wxy-zzz wxy-zzz commented Jun 8, 2026

Copy link
Copy Markdown

Resolves #1501

Description

First off — thank you for dbt-databricks! Being able to manage Databricks metric views through dbt has been fantastic, and I'm genuinely happy to be able to version-control and document them like any other model.

The problem

A metric_view body is YAML that dbt-core renders through its model render context. Unlike the schema-YAML context, that context does not expose doc(), so {{ doc('my_block') }} in a metric view's comment: / display_name: fields fails to compile:

Compilation Error in model my_metric_view
  'doc' is undefined. This can happen when calling a macro that does not exist.

ref(), source(), config(), var() and custom macros all work in the same body — only doc() is missing. This breaks documentation parity: a description maintained once as a doc block cannot be reused in a metric view.

A caveat on the approach (please read 🙏)

I understand that the correct fix most likely belongs in dbt-core — exposing doc in the model render context — and that solving this purely inside the adapter is a workaround. Being able to use doc() for metric views would be so valuable to me that I went ahead and implemented it in the adapter anyway.

The mechanism this PR relies on is that Jinja falls back to a same-named macro when a name is absent from the render context. So it defines a doc macro that bridges to a new adapter.resolve_doc, which resolves the block via the manifest's doc lookup. In other words, it "forces" doc() to work by leaning on that macro-fallback behavior.

  • The schema-YAML render context carries no macro namespace, so it keeps using dbt-core's built-in doc() — existing description: rendering is unchanged.
  • An execute guard makes the macro a no-op during parse (the doc lookup is not built yet).
  • As a side effect, doc() now resolves in all model bodies on Databricks, not just metric views.

If this approach is misguided or not something you'd want to maintain in the adapter, I completely understand — please feel free to close this PR, and I'm sorry in advance for any trouble it may cause.

Testing

  • Added unit tests for the doc macro (tests/unit/macros/etc/test_doc_macro.py).
  • Added a functional regression test TestMetricViewWithDoc, verified against a real Unity Catalog SQL warehouse: the doc block is substituted into the compiled metric view body, and the resulting view is queryable via MEASURE().
  • Tested environment: UC SQL Warehouse (databricks_uc_sql_endpoint).
  • Note: metric view comment: / display_name: fields require YAML spec version: 1.1+ (matching the original issue).

Finally, I'm fairly new to contributing to open source, so if I've gotten any conventions or design choices wrong, I'd really appreciate your patience and guidance. Thank you for taking the time to look at this!

Checklist

  • I have run this code in development and it appears to resolve the stated issue
  • This PR includes tests, or tests are not required/relevant for this PR
  • I have updated the CHANGELOG.md and added information about my change to the "dbt-databricks next" section.

@wxy-zzz wxy-zzz requested review from jprakash-db and sd-db as code owners June 8, 2026 07:23
dbt-core only registers doc() in the schema-YAML render context
(DocsRuntimeContext), not the model render context, so a metric_view
body -- which is YAML rendered as model SQL -- failed to compile with
"'doc' is undefined" when using {{ doc(...) }} in comment: /
display_name: fields.

Add a `doc` Jinja macro that the model render context falls back to
(it has no `doc` member), bridging to a new adapter.resolve_doc that
looks up the block via the manifest. The schema-YAML context keeps
dbt-core's built-in doc() (it carries no macro namespace), so existing
description: rendering is unchanged. An execute guard makes the macro a
no-op during parse, before the doc lookup is built.

As a side effect doc() now resolves in all model bodies on Databricks.

Signed-off-by: WADA Yusuke <y_wada@ivry.jp>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@wxy-zzz wxy-zzz force-pushed the fix/metric-view-doc-1501 branch from 7ba7e1e to 948864e Compare June 8, 2026 07:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Metric Views: doc() is undefined when compiling metric_view models in 1.12

1 participant