Add persist_docs support for semantic views

[RyutoYoda]

Summary

Implements relation-level persist_docs functionality for semantic views, addressing the "persist_docs not supported" limitation mentioned in the README and resolving the TODO comment in the materialization.

• ✅ Automatically adds model descriptions from schema.yml as COMMENT clauses to Semantic View DDL
• ✅ Detects and avoids conflicts with existing inline COMMENT syntax
• ✅ Follows the existing copy_grants pattern for consistency
• ✅ Includes comprehensive test coverage for enabled and disabled scenarios

Usage Example

# schema.yml
models:
  - name: my_semantic_view
    description: "Customer metrics for analysis"

# model config
{{ config(
    materialized='semantic_view',
    persist_docs={'relation': true}
) }}

Results in DDL with: COMMENT='Customer metrics for analysis'

Test Plan

• Added test model with persist_docs enabled
• Added positive test verifying comment is added when enabled
• Added negative test verifying comment is NOT added when disabled
• Verified existing inline COMMENT syntax is preserved
• Tested on actual Snowflake environment

Changes

• Updated macros/relations/semantic_view/create.sql with new append_comment_if_missing macro
• Modified macros/materializations/semantic_view.sql to remove TODO comment
• Enhanced README with persist_docs documentation and usage examples
• Added integration test model and test cases

[Daniel-Wiszowaty]

Hey @sfc-gh-yutliu could we push this? 🙏🏻

[ahossain-lithic]

This would be great to have!

[RyutoYoda]

Hey @sfc-gh-yutliu 👋 Just checking in — any chance this could get a review when you have a moment? Happy to make any changes if needed. Thanks!

[LizzyHunter]

This is not only nice to have but a feature that can make the difference between keeping on using dbt / metricflow semantic layer VS fully adopting Snowflake solutions and downstream AI capabilities. Any chance this can be pushed? 🙏

[sfc-gh-sarur]

@RyutoYoda please resolve the conflicts in this PR before merging, thanks

[jheath5]

@sfc-gh-sarur @RyutoYoda anything to do to get this merged? Not familiar on how to contribute/finish for this, but as @LizzyHunter said this will increase adoption of Snowflake semantic views for teams like mine that use dbt

[snowflake-security-bot]

Snowflake Security Review

Security grade: A — Passed ✅

This PR was classified as LOW risk by the automated pre-screen.

[arcticowl-ai-review-labs]

🟠 MEDIUM · COMMENT injection via unescaped model description in append_comment_if_missing enables SQL DDL breakout [NEW] · CWE-89

[RyutoYoda]

@sfc-gh-sarur Conflicts are resolved and the PR is mergeable again. The security bot check passed. Your earlier approval was dismissed by the new commits, so this needs another look when you have a moment.

Two things worth knowing before you review.

1. persist_docs was incompatible with the new max_staleness config.

Snowflake requires COMMENT to come before MAX_STALENESS, so appending the comment last produced invalid DDL:

-- rejected: syntax error line 6 at position 0 unexpected 'COMMENT'.
MAX_STALENESS = '1 hour'
COMMENT='...'

-- accepted
COMMENT='...'
MAX_STALENESS = '1 hour'
COPY GRANTS

The macro now appends the trailing clauses in that order.

2. integration_tests/models/semantic_view_with_materializations.sql on main has the same ordering issue.

Its body ends with MAX_STALENESS followed by COMMENT, so the model fails to build today, independently of this PR. I fixed it in a separate commit — happy to drop that commit if you would rather handle it on its own.

Verification

I rendered the DDL that the macro actually emits for each config combination and ran it against Snowflake, then asserted on get_ddl the same way the integration tests do:

config	expected	result
no persist_docs	no COMMENT	pass
persist_docs	description becomes COMMENT	pass
persist_docs + max_staleness	valid clause order	pass
persist_docs + max_staleness + copy_grants	valid clause order	pass
persist_docs + create_or_alter	COMMENT applied	pass
inline COMMENT= in the model body	body wins, nothing appended	pass
no description	no COMMENT	pass

COMMENT is applied on the CREATE OR ALTER path as well, unlike COPY GRANTS — Snowflake accepts it there, and it is part of the view definition rather than a create-time-only option.

Commits

1. Add persist_docs support for semantic views — the original change
2. Merge upstream main and resolve conflicts
3. Emit COMMENT before MAX_STALENESS to match Snowflake DDL clause order
4. Fix clause order in the materializations integration test model

[RyutoYoda]

@sfc-gh-yutliu tagging you as well, since you own most of this area of the package.

Short version: the conflicts with main are resolved, the security bot check passed, and the only thing left is a re-approval — the earlier one was dismissed by the new commits.

The one item that may need your judgement is that integration_tests/models/semantic_view_with_materializations.sql on main ends with MAX_STALENESS followed by COMMENT, which Snowflake rejects, so that model does not build today. I fixed it here in its own commit, but it is unrelated to persist_docs and easy to drop if you would rather fix it separately. Details in the comment above.