Required Permissions for Creating Custom SQL Assertions in DataHub Cloud – DataHub Customer Support Portal

Area: Product Issues

Sub-Area: Permissions & Access Control — Observability / Assertions

Issue

Users with standard Editor-level access encounter permissions errors when attempting to create custom SQL assertions in DataHub Cloud, even though other assertion types (freshness, volume, column, schema) work without issue. This happens because creating a custom SQL assertion requires a specific privilege — Edit SQL Assertion Monitors — that is not included in typical editor metadata policies by default. Administrators do not hit this error because their platform policy implicitly covers monitor management, masking the gap for non-admin users.

Error Messages

Failed to update assertion monitor!
Permission denied: insufficient privileges to create SQL assertion monitor

You Might Be Asking

Why can my editors create freshness or volume assertions but not custom SQL assertions?
What permissions do I need to grant so users can create any type of data quality assertion?
Is there a single canned policy in DataHub that enables all assertion types?
Will granting SQL assertion permissions affect my read-only users?

Solution

Creating custom SQL assertions requires all three of the following Metadata Privileges to be present on a policy that applies to the user:

Edit Assertions — allows creating and editing assertions on entities
Edit Monitors — required for the underlying monitor service that powers assertions
Edit SQL Assertion Monitors — specifically required for custom SQL assertions; this is the privilege most commonly missing

There is no single pre-built policy that bundles all three. You have two options depending on your desired scope:

Option A: Add the missing privilege to your existing editor policy (recommended — narrowest scope)

Navigate to Settings → Permissions → Policies in the DataHub UI.
Locate the metadata policy that already grants Edit Assertions and Edit Monitors to your editor group (e.g., your "Editors - Metadata Policy" or equivalent).
If the policy is editable, click it, scroll to the privileges section, and add Edit SQL Assertion Monitors. Save the policy.
If the existing policy is not editable, proceed to Option B and create a new supplementary policy.

Option B: Create a new metadata policy scoped to your editor group

Navigate to Settings → Permissions → Policies.
Click + New Policy and select Metadata Policy.
Set the Actors to your editor group(s) — do not set this to All Users if you want to preserve read-only access for reader-role users.
Set the Resource filter to All (or scope to specific datasets if desired).
Add the following three privileges:
- Edit Assertions
- Edit Monitors
- Edit SQL Assertion Monitors
Save and activate the policy.

Option C: Apply via GraphQL mutation (programmatic setup)

mutation createSQLAssertionEditPolicy {
  createPolicy(input: {
    type: METADATA
    name: "Editors - Edit SQL Assertion Monitors"
    description: "Allows editor-group users to create and edit custom SQL assertion monitors"
    state: ACTIVE
    actors: {
      groups: ["<your-editor-group-urn>"]
    }
    resources: {
      filter: {
        criteria: []
      }
    }
    privileges: [
      "EDIT_ENTITY_ASSERTIONS",
      "EDIT_ENTITY_MONITORS",
      "EDIT_ENTITY_SQL_ASSERTION_MONITORS"
    ]
  })
}

Replace <your-editor-group-urn> with the URN of your editor group (e.g., urn:li:corpGroup:editors).

Verify the fix

After saving the policy, wait up to 2 minutes for the policy cache to refresh (no logout required — a page refresh is sufficient).
Have an affected user navigate to a dataset, open the Assertions tab, and attempt to create a new custom SQL assertion.
If the error persists after 2 minutes, confirm the user's account is a member of the group(s) targeted by the new policy.

Additional Notes

Do not use All Users as the actor if your environment has read-only users (e.g., a Reader role). Granting Edit SQL Assertion Monitors to All Users would give edit-level access to everyone, including readers. Scope the policy to your editor group(s) instead, and verify group membership controls access going forward.
Security consideration: The Edit SQL Assertion Monitors privilege allows users to run arbitrary SQL against the connected data source through the custom assertion builder. This is by design — custom SQL assertions execute user-supplied queries — but it is broader than other assertion privileges. Grant it deliberately and only to users who should have query-level access to the underlying sources.
Admins are not affected because the Admin platform role implicitly includes Manage Monitors, which covers all monitor and assertion operations. This makes the gap invisible during initial setup if only admins are testing the feature.
Policy cache: By default, DataHub's policy cache refreshes on a two-minute interval. Changes take effect within a few minutes without requiring user logout.
Platform Privilege alternative: Granting the Manage Monitors Platform Privilege also resolves the issue and provides the broadest possible monitor management access. However, this is a platform-level privilege rather than a metadata-level one, and should only be granted to users who need administrative control over monitors across the entire instance.
This behavior has been consistent across DataHub Cloud versions. The root cause is a documentation and UI gap — the assertion creation UI does not clearly indicate which privileges are required per assertion type, making it easy to configure an incomplete policy that appears valid.