From 4b73419f61b5bd52b342b6e8c3196b65fceeb6fa Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Wed, 18 Feb 2026 13:46:09 -0500 Subject: [PATCH 1/3] Clarify Manage Custom SQL vs Manage SQL Runner permissions Addresses customer confusion about the difference between these two permission scopes in custom roles. Adds explanatory section to the roles reference and cross-links from the custom roles page. Co-Authored-By: Claude Opus 4.6 --- references/workspace/custom-roles.mdx | 3 +++ references/workspace/roles.mdx | 20 ++++++++++++++++++-- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/references/workspace/custom-roles.mdx b/references/workspace/custom-roles.mdx index 96d11f17..41e7ee35 100644 --- a/references/workspace/custom-roles.mdx +++ b/references/workspace/custom-roles.mdx @@ -44,6 +44,9 @@ Custom roles are created at the organization level but are assigned to users or - **View permissions**: Allow users to see content (dashboards, charts, spaces) - **Create permissions**: Allow users to create new content - **Manage permissions**: Allow users to edit, delete, or administer content + + For a detailed breakdown of commonly confused scopes like **Manage SQL Runner** vs **Manage Custom SQL**, see the [roles and permissions reference](/references/workspace/roles#use-the-sql-runner-vs-create-and-explore-custom-sql-dimensions). + 5. Click **Save** to create the role ![create-new-role.png](/images/references/workspace/create-new-role.png) diff --git a/references/workspace/roles.mdx b/references/workspace/roles.mdx index 0f1f2985..2126848e 100644 --- a/references/workspace/roles.mdx +++ b/references/workspace/roles.mdx @@ -29,8 +29,8 @@ Project Admins can invite users to their project and assign users or [groups](/r | Create and edit scheduled deliveries | | | | | | | Create and edit Syncs | | | | | | | Create and edit charts and dashboards | | | | | | -| Use the SQL runner | | | | | | -| Create and explore custom SQL dimensions | | | | | | +| [Use the SQL runner](#use-the-sql-runner) | | | | | | +| [Create and explore custom SQL dimensions](#create-and-explore-custom-sql-dimensions) | | | | | | | Create virtual views | | | | | | | Manage project access and permissions | | | | | | | Delete project | | | | | | @@ -39,6 +39,22 @@ Project Admins can invite users to their project and assign users or [groups](/r | Rename models, dimensions, and metrics (CLI and UI) | | | | | | +### "Use the SQL Runner" vs "Create and explore custom SQL dimensions" + +These two permissions are independent and control different features. If you're using [custom roles](/references/workspace/custom-roles), you'll see these as separate scopes called **Manage SQL Runner** and **Manage Custom SQL**. + +#### Use the SQL runner + +This permission (the **Manage SQL Runner** scope in custom roles) controls access to the [SQL Runner](/guides/developer/sql-runner), which lets users write and run ad-hoc SQL queries directly against your data warehouse. It also controls the ability to create [virtual views](/guides/developer/virtual-views) and [write back dbt models](/guides/developer/dbt-write-back) from SQL Runner queries. + +#### Create and explore custom SQL dimensions + +This permission (the **Manage Custom SQL** scope in custom roles) controls the ability to create [custom SQL dimensions](/guides/custom-fields) inside the Explore view. Custom SQL dimensions let users add calculated fields to an existing table using raw SQL. This permission does **not** grant access to the SQL Runner. + + + If you want a user to query tables that include custom SQL dimensions created by others, they don't need either of these permissions. Any user with access to the Explore view can **use** existing custom SQL dimensions in their queries — these permissions only control who can **create** them. + + ### Organization Roles Organization Admins can assign roles to organization members, which gives access to all projects in the organization. From 348d9850a8406f9bdbc31b5337f338c02fbc2787 Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Wed, 18 Feb 2026 13:54:13 -0500 Subject: [PATCH 2/3] Remove em dash from permissions tip Co-Authored-By: Claude Opus 4.6 --- references/workspace/roles.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/workspace/roles.mdx b/references/workspace/roles.mdx index 2126848e..81584f14 100644 --- a/references/workspace/roles.mdx +++ b/references/workspace/roles.mdx @@ -52,7 +52,7 @@ This permission (the **Manage SQL Runner** scope in custom roles) controls acces This permission (the **Manage Custom SQL** scope in custom roles) controls the ability to create [custom SQL dimensions](/guides/custom-fields) inside the Explore view. Custom SQL dimensions let users add calculated fields to an existing table using raw SQL. This permission does **not** grant access to the SQL Runner. - If you want a user to query tables that include custom SQL dimensions created by others, they don't need either of these permissions. Any user with access to the Explore view can **use** existing custom SQL dimensions in their queries — these permissions only control who can **create** them. + If you want a user to query tables that include custom SQL dimensions created by others, they don't need either of these permissions. Any user with access to the Explore view can **use** existing custom SQL dimensions in their queries - these permissions only control who can **create** them. ### Organization Roles From 700565391714ceacbfb93716336edb07b91696e4 Mon Sep 17 00:00:00 2001 From: Tori Whaley Date: Wed, 18 Feb 2026 13:57:15 -0500 Subject: [PATCH 3/3] Move SQL scope clarification to custom roles page The explanation of Manage SQL Runner vs Manage Custom SQL scopes belongs on the custom roles page where users are configuring them, not on the general roles permission matrix. Co-Authored-By: Claude Opus 4.6 --- references/workspace/custom-roles.mdx | 17 ++++++++++++++--- references/workspace/roles.mdx | 20 ++------------------ 2 files changed, 16 insertions(+), 21 deletions(-) diff --git a/references/workspace/custom-roles.mdx b/references/workspace/custom-roles.mdx index 41e7ee35..f621a399 100644 --- a/references/workspace/custom-roles.mdx +++ b/references/workspace/custom-roles.mdx @@ -44,9 +44,6 @@ Custom roles are created at the organization level but are assigned to users or - **View permissions**: Allow users to see content (dashboards, charts, spaces) - **Create permissions**: Allow users to create new content - **Manage permissions**: Allow users to edit, delete, or administer content - - For a detailed breakdown of commonly confused scopes like **Manage SQL Runner** vs **Manage Custom SQL**, see the [roles and permissions reference](/references/workspace/roles#use-the-sql-runner-vs-create-and-explore-custom-sql-dimensions). - 5. Click **Save** to create the role ![create-new-role.png](/images/references/workspace/create-new-role.png) @@ -84,6 +81,20 @@ Custom roles are assigned at the project level to provide granular access contro 3. Select the custom role from the dropdown 4. All members of the group will inherit the custom role permissions for this project +## Scope reference + +### Manage SQL Runner vs Manage Custom SQL + +These two scopes are independent and control different features. + +**Manage SQL Runner** controls access to the [SQL Runner](/guides/developer/sql-runner), which lets users write and run ad-hoc SQL queries directly against your data warehouse. It also controls the ability to create [virtual views](/guides/developer/virtual-views) and [write back dbt models](/guides/developer/dbt-write-back) from SQL Runner queries. + +**Manage Custom SQL** controls the ability to create [custom SQL dimensions](/guides/custom-fields) inside the Explore view. Custom SQL dimensions let users add calculated fields to an existing table using raw SQL. This scope does **not** grant access to the SQL Runner. + + + If you want a user to query tables that include custom SQL dimensions created by others, they don't need either of these scopes. Any user with access to the Explore view can **use** existing custom SQL dimensions in their queries - these scopes only control who can **create** them. + + ## Troubleshooting ### Users Can't See Expected Content diff --git a/references/workspace/roles.mdx b/references/workspace/roles.mdx index 81584f14..0f1f2985 100644 --- a/references/workspace/roles.mdx +++ b/references/workspace/roles.mdx @@ -29,8 +29,8 @@ Project Admins can invite users to their project and assign users or [groups](/r | Create and edit scheduled deliveries | | | | | | | Create and edit Syncs | | | | | | | Create and edit charts and dashboards | | | | | | -| [Use the SQL runner](#use-the-sql-runner) | | | | | | -| [Create and explore custom SQL dimensions](#create-and-explore-custom-sql-dimensions) | | | | | | +| Use the SQL runner | | | | | | +| Create and explore custom SQL dimensions | | | | | | | Create virtual views | | | | | | | Manage project access and permissions | | | | | | | Delete project | | | | | | @@ -39,22 +39,6 @@ Project Admins can invite users to their project and assign users or [groups](/r | Rename models, dimensions, and metrics (CLI and UI) | | | | | | -### "Use the SQL Runner" vs "Create and explore custom SQL dimensions" - -These two permissions are independent and control different features. If you're using [custom roles](/references/workspace/custom-roles), you'll see these as separate scopes called **Manage SQL Runner** and **Manage Custom SQL**. - -#### Use the SQL runner - -This permission (the **Manage SQL Runner** scope in custom roles) controls access to the [SQL Runner](/guides/developer/sql-runner), which lets users write and run ad-hoc SQL queries directly against your data warehouse. It also controls the ability to create [virtual views](/guides/developer/virtual-views) and [write back dbt models](/guides/developer/dbt-write-back) from SQL Runner queries. - -#### Create and explore custom SQL dimensions - -This permission (the **Manage Custom SQL** scope in custom roles) controls the ability to create [custom SQL dimensions](/guides/custom-fields) inside the Explore view. Custom SQL dimensions let users add calculated fields to an existing table using raw SQL. This permission does **not** grant access to the SQL Runner. - - - If you want a user to query tables that include custom SQL dimensions created by others, they don't need either of these permissions. Any user with access to the Explore view can **use** existing custom SQL dimensions in their queries - these permissions only control who can **create** them. - - ### Organization Roles Organization Admins can assign roles to organization members, which gives access to all projects in the organization.