Allow custom check messages by ghanse · Pull Request #1092 · databrickslabs/dqx

ghanse · 2026-03-20T22:22:02Z

Changes

Add an optional message_expr parameter to DQRule that allows users to define custom check failure messages as Spark Column objects or SQL expression strings. When message is None (the default), the default message behavior is preserved. When provided, the custom message replaces the default message for failed rows.

Skipped violation test helper
Introduces a build_skipped_violation method for testing skipped checks (e.g. due to invalid expressions, column references, or custom messages).

Linked issues

Resolves #958

Tests

manually tested
added unit tests
added integration tests

Co-authored-by: Isaac

github-actions · 2026-03-20T23:11:35Z

✅ 735/735 passed, 43 skipped, 6h25m21s total

_{Running from acceptance #4775}

…eholders The custom-message field is renamed to message_expr and now accepts either a Spark SQL expression string or a Spark Column object. The expression is evaluated as-is — DQX no longer substitutes {rule_name}, {check_func_name}, or {column_value} placeholders. Callers reference columns and identifiers directly inside the expression. - DQRule / DQForEachColRule: rename message -> message_expr (str | Column | None) - to_dict serialises message_expr only when it is a string (Column is in-process) - DQRuleManager._build_message_col simplified: F.expr(str) or use Column directly - checks_serializer: read message_expr key from metadata, pass to constructors - Unit tests rewritten for the new attribute name and Column variant - Integration tests rewritten without placeholders; the existing test_apply_checks_without_custom_message_unchanged is dropped (the Engine's no-message default path is already covered by surrounding tests) - Docs (quality_checks.mdx) rewritten to drop the placeholder section, add a Column-based Python example, and annotate each example with the rendered message string Co-authored-by: Isaac

mwojtyczka

Small, well-isolated change with good happy-path test coverage. Posting 11 inline comments below covering: a security exposure (arbitrary F.expr evaluation of strings sourced from YAML/metadata), a UX trap with unquoted strings, several maintainability/polish items, and one test bug.

One non-inline issue: PR description doesn't match the implementation.

The description says:

Add an optional message callable parameter ... that allows users to define custom check failure messages. The callable receives rule context (rule_name, check_func_name, check_func_args, column_value) and returns a Spark Column expression…

But the actual API is message_expr: str | Column | None — no callable, no rule context. Either the description should be rewritten to match what shipped, or the implementation should provide the callable form the description promises. Reviewers (and future readers running git log / GitHub PR archeology) rely on the description for context.

Copilot

Pull request overview

This PR introduces support for overriding default DQX check failure messages via a new optional message_expr field on rules, allowing users to supply either a Spark SQL expression string or a Spark Column expression to generate custom messages for failed checks.

Changes:

Add message_expr: str | Column | None to DQRule and propagate it through DQForEachColRule.
Update result-building to use message_expr as the failure message when provided.
Extend metadata deserialization to accept message_expr, and add unit/integration tests plus docs for the new behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/unit/test_custom_messages.py	Adds unit tests for `message_expr` acceptance/propagation/serialization behavior.
tests/integration/test_custom_messages.py	Adds integration coverage verifying custom messages appear in results for class-based and metadata-based checks.
src/databricks/labs/dqx/rule.py	Adds `message_expr` field to rules and ensures it is propagated/serialized (string-only).
src/databricks/labs/dqx/manager.py	Uses a dedicated builder to select between default messages and custom `message_expr`.
src/databricks/labs/dqx/checks_serializer.py	Deserializes `message_expr` from metadata and passes it into created rules.
docs/dqx/docs/reference/quality_checks.mdx	Documents how to use `message_expr` from Python and YAML.

Comments suppressed due to low confidence (1)

src/databricks/labs/dqx/checks_serializer.py:276

message_expr is now deserialized from metadata, but checks persisted via the table storage path won’t round-trip it: CHECKS_TABLE_SCHEMA / DataFrameConverter.to_dataframe() / from_dataframe() (in checks_storage.py) currently have no place to store/read message_expr. This means saving checks with message_expr to a table will silently drop it on load, and can also cause rule_set_fingerprint/idempotency mismatches because fingerprints include message_expr while the stored rows do not.

            criticality = check_def.get("criticality", "error")
            filter_str = check_def.get("filter")
            user_metadata = check_def.get("user_metadata")
            message_expr = check_def.get("message_expr")

            # Exclude `column` and `columns` from check_func_kwargs
            # as these are always included in the check function call
            check_func_kwargs = {k: v for k, v in func_args.items() if k not in {"column", "columns"}}

            # treat non-registered function as row-level checks

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

        # or use literal run time if explicitly overridden
        run_time_expr = F.current_timestamp() if self.run_time_overwrite is None else F.lit(self.run_time_overwrite)

+        message_col = self._build_message_col(condition)


mwojtyczka

Re-review of custom check messages. Solid, well-tested feature with clean null-preservation semantics. One higher-impact concern around the safety check producing false positives on ordinary message text, plus a few smaller notes left inline.

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

+* Wrap column references with `coalesce` to avoid null messages. In Spark SQL, `concat(..., null)` returns `null`.
+* Pass literal string values with quotes (e.g. `'Email must not be null'`) to ensure they are not evaluated as SQL expressions.
+* Avoid long messages or referencing unbounded string columns. Message text is **truncated at 500 characters**.
+* Avoid unquoted SQL keywords that may be executed naively (e.g. `DELETE` or `TRUNCATE`).


+        if isinstance(self.message_expr, str):
+            self._validate_message_expression(self.message_expr)


            user_metadata = check_def.get("user_metadata")
+            message_expr = check_def.get("message_expr")


mwojtyczka

LGTM

feat: add message callable to DQRule for custom check messages

c28d041

Co-authored-by: Isaac

ghanse requested a review from a team as a code owner March 20, 2026 22:22

ghanse requested review from gergo-databricks and removed request for a team March 20, 2026 22:22

ghanse temporarily deployed to tool March 20, 2026 22:22 — with GitHub Actions Inactive

ghanse had a problem deploying to tool March 20, 2026 22:22 — with GitHub Actions Failure

ghanse changed the title ~~feat: add message callable to DQRule for custom check messages~~ Allow custom check messages Mar 21, 2026

Refactor

6721317

ghanse had a problem deploying to tool March 21, 2026 01:40 — with GitHub Actions Failure

ghanse temporarily deployed to tool March 21, 2026 01:40 — with GitHub Actions Inactive

ghanse had a problem deploying to tool March 21, 2026 01:40 — with GitHub Actions Failure

Update documentation and tests

ab9a4ff

ghanse had a problem deploying to tool March 23, 2026 15:19 — with GitHub Actions Failure

ghanse had a problem deploying to tool March 23, 2026 15:19 — with GitHub Actions Error

Fix tests

05baafb

ghanse and others added 3 commits May 3, 2026 13:44

Update docs

52cd2df

Merge branch 'main' into ghanse/issue-958-custom-check-messages

4560ac6

mwojtyczka reviewed May 8, 2026

View reviewed changes

Comment thread src/databricks/labs/dqx/manager.py Outdated

ghanse and others added 3 commits May 30, 2026 14:50

Merge branch 'main' into ghanse/issue-958-custom-check-messages

f73a57d

Merge branch 'main' into ghanse/issue-958-custom-check-messages

c9a62a0

Format tests

49c9a59

Copilot AI reviewed Jun 3, 2026

View reviewed changes

ghanse and others added 10 commits June 4, 2026 00:05

Fix unit tests

237a572

Format

7d2ec21

Add validation safety

7172765

Fix expression

2891bf0

Update edge case handling and widen tests

80bcd2e

Add documentation of edge cases and best practices

ec8dfd6

Improve docstring and fix tests

ebdf61e

Note validation behavior in documentation

a78bd20

Merge branch 'main' into ghanse/issue-958-custom-check-messages

1e169ea

Merge branch 'main' into ghanse/issue-958-custom-check-messages

0971779

mwojtyczka reviewed Jun 5, 2026

View reviewed changes

Comment thread src/databricks/labs/dqx/manager.py Outdated

Comment thread src/databricks/labs/dqx/rule.py

Comment thread src/databricks/labs/dqx/manager.py Outdated

ghanse added 4 commits June 7, 2026 10:05

Remove usage of is_sql_query_safe and add documentation

7170d09

Format, update docs, and update tests

a950d73

Add handling for invalid message expressions

dbf5137

Handle invalid message expressions

243002c

Copilot AI reviewed Jun 8, 2026

View reviewed changes

Merge branch 'main' into ghanse/issue-958-custom-check-messages

0ff2415

mwojtyczka approved these changes Jun 9, 2026

View reviewed changes

		if isinstance(self.message_expr, str):
		self._validate_message_expression(self.message_expr)

		user_metadata = check_def.get("user_metadata")
		message_expr = check_def.get("message_expr")

Uh oh!

Conversation

ghanse commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Linked issues

Tests

Uh oh!

github-actions Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mwojtyczka left a comment

Choose a reason for hiding this comment

One non-inline issue: PR description doesn't match the implementation.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mwojtyczka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mwojtyczka left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ghanse commented Mar 20, 2026 •

edited

Loading

github-actions Bot commented Mar 20, 2026 •

edited

Loading