fix: resolve doc() docs blocks in metric_view model bodies#1504
Open
wxy-zzz wants to merge 1 commit into
Open
Conversation
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>
7ba7e1e to
948864e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_viewbody is YAML that dbt-core renders through its model render context. Unlike the schema-YAML context, that context does not exposedoc(), so{{ doc('my_block') }}in a metric view'scomment:/display_name:fields fails to compile:ref(),source(),config(),var()and custom macros all work in the same body — onlydoc()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
docin the model render context — and that solving this purely inside the adapter is a workaround. Being able to usedoc()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
docmacro that bridges to a newadapter.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.doc()— existingdescription:rendering is unchanged.executeguard makes the macro a no-op during parse (the doc lookup is not built yet).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
docmacro (tests/unit/macros/etc/test_doc_macro.py).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 viaMEASURE().databricks_uc_sql_endpoint).comment:/display_name:fields require YAML specversion: 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
CHANGELOG.mdand added information about my change to the "dbt-databricks next" section.