Configuring Access Control

This document explains how to configure access control for users and roles in Singdata Lakehouse. Lakehouse uses two independent permission systems: feature permissions control whether a role can open a Studio module and perform operations on its pages, while metadata privileges control which Workspaces, Schemas, Tables, Virtual Clusters, and other objects the role can access. Production roles usually require a combination of both.

Permission type	What it controls	How to configure it
Feature permission	Studio menus, pages, and operations such as create, run, operate, and publish	Configure it on the role details page in the Web UI
Metadata privilege	Viewing, using, querying, writing, modifying, and deleting Lakehouse objects	Use SQL `GRANT`/`REVOKE` or grant data privileges in the Web UI
Role grant	Whether a user receives the feature permissions and metadata privileges assigned to a role	Use the Web UI or SQL `GRANT ROLE`/`REVOKE ROLE`

For example, to let a developer query a table from Studio, grant the Development → Read, Execute feature permissions, USE on a Virtual Cluster, and READ METADATA and SELECT on the target table. Configuring only one permission type is not sufficient for the complete operation.

Instance-Level Management

Assigning Additional Administrator Users for an Instance

In Singdata Lakehouse, the user who creates a service instance is granted the "instance administrator" (instance_admin) role by default. To ensure there is always at least one user who can perform instance-level management tasks (such as creating workspaces and managing instance-level roles), you must retain at least one user when removing users with the instance_admin role; otherwise, an error will be returned. It is recommended to designate at least one additional user as an instance administrator to avoid disruptions caused by user unavailability or other exceptional circumstances.

Granting Instance-Level Roles

Service instance-level roles can only be granted via the Web UI. Only users with the instance_admin role can perform this operation.

In the service instance, navigate to Management -> Security, and switch to the Roles tab.

Click on the instance role you want to grant to enter its detail page, then click Grant to User:

In the dialog, select the users to grant, then click the Grant button to complete the instance role assignment.

Workspace-Level Management

Designating a Workspace Administrator

The user who creates a workspace is granted the "workspace administrator" (workspace_admin) role for that workspace by default. This role has full permissions to manage the workspace. Each workspace must have at least one user granted the workspace administrator role; multiple users can hold this role simultaneously.

Managing Roles and Members in a Workspace

Roles and members in each workspace are independent of other workspaces and must be granted separately. Only users with the workspace_admin role in a given workspace can manage role grants, creation, and deletion, as well as adding and removing members within that workspace.

Managing Workspace Members

For a user to use compute clusters (VClusters) and execute SQL within a workspace, they must first join that workspace. Workspace administrators can add users to a workspace using the following two methods:

Via Web UI

After entering the service instance, click Management -> Workspace in the menu to go to the workspace list. Click on a workspace name to enter its detail page.

On the workspace detail page, click the + Add User button, and select users in the dialog. Only users who exist in the service instance and are not currently members of this workspace will be displayed. Select one or more users and click Add User or Add User and Grant Role to add the selected users to the workspace. After successful addition, you can find the new users in the workspace's Users list.

In the workspace's Users list, click the ... menu next to a user and select Remove User to remove that user from the workspace. The removed user will immediately lose all granted workspace roles and lose the ability to use compute clusters (VClusters) or execute SQL in that workspace.

Note that users removed from a workspace will retain any data permissions directly granted to them, meaning they can exercise those data permissions in other workspaces to query or modify data. Therefore, it is recommended to manage permissions through role grants to reduce the complexity of permission management in such scenarios.

Via SQL

To add a user to a workspace via JDBC, execute the following statement:

CREATE USER <user_name>;

Replace <user_name> with the username to add. Only users who exist in the service instance and are not currently members of this workspace can be added.

To remove a user from a workspace:

DROP USER <user_name>;

Replace <user_name> with the username to remove. This operation does not delete the user identity; it only removes the user from the current workspace.

Using Workspace-Level Roles

Development Within a Workspace

Development within a workspace requires: the ability to execute SQL in the workspace (granted upon joining the workspace); access to compute resources in the workspace; and permissions on the relevant data objects.

Each workspace includes the following preset roles that have one or more of the above permissions by default. You can grant these roles to users to quickly get started with data development.

Workspace Developer (workspace_dev) Role

The workspace_dev role has read/write permissions on all data objects (tables, views, dynamic tables, etc. — see 'Metadata Objects') and usage permissions on all compute clusters within the workspace by default.

After being granted the workspace_dev role, users can directly use the Development feature in the Web UI or connect via JDBC for data development.

Note that the default data object read/write permissions of the workspace_dev role do not allow re-granting to others. To grant read or write permissions on data objects to other roles, use a user with the workspace_admin role.

Workspace Analyst (workspace_analyst) Role

The workspace_analyst role has usage permissions on all compute clusters and read metadata permissions on all data objects (tables, views, dynamic tables, etc.) within the workspace by default. However, it does not have SELECT permissions on data objects, meaning it cannot execute SELECT queries on any tables or views. To perform data query and analysis with the workspace_analyst role, you must grant SELECT permission on the target data objects.

For granting data permissions to the workspace_analyst role, refer to the GRANT statement documentation.

Using Custom Roles or Users

Custom roles and users can execute SQL for development or data analysis in a workspace after receiving the required privileges. To let a custom role use Web UI features such as Development, Operation Center, Notebook, or publish center, also configure the corresponding feature permissions on the role details page. A user with the workspace_admin role must manage these grants. Use statements like the following to grant metadata privileges:

-- Grant usage and metadata read permissions on all compute clusters in the workspace to a custom role GRANT USE, READ METADATA ON ALL VCLUSTERS TO ROLE <CUSTOM_ROLE_NAME>; -- [Optional] Grant usage and metadata read permissions on a specific compute cluster to a custom role GRANT USE, READ METADATA ON VCLUSTER <VCLUSTER_NAME> TO ROLE <CUSTOM_ROLE_NAME>; -- Grant select and metadata read permissions on all objects in a schema to a custom role GRANT SELECT, READ METADATA ON ALL OBJECTS IN SCHEMA <SCHEMA_NAME> TO ROLE <CUSTOM_ROLE_NAME>; -- Grant select and metadata read permissions on a specific table to a custom role GRANT SELECT, READ METADATA ON TABLE <TABLE_NAME> TO ROLE <CUSTOM_ROLE_NAME>;

To grant permissions to a user, replace TO ROLE <CUSTOM_ROLE_NAME> with TO USER <USER_NAME> in the above statements.

Configuring Feature Permissions

Feature permissions determine whether a role can open a Studio module and perform specific operations within it. They can only be configured in the Web UI and cannot be granted with SQL GRANT or revoked with SQL REVOKE.

Only a workspace administrator (workspace_admin) can manage feature permissions for roles in that workspace:

Open Management → Security → Roles.
Select the target Workspace and open the custom role you want to configure.
On the role details page, open the Permission tab and switch to Feature.
Click Authorization Function, then select the required feature domains and feature objects.
Select the atomic operations to grant and click OK.

The role details page displays the granted READ and WRITE operations by feature object. To change the operations, click Edit for the object. To revoke all permissions on a feature object, click Remove.

⚠️ Note: READ and WRITE group atomic operations; they are not aggregate privileges that automatically include every read or write operation. Expand each group and review the specific operations. For example, the WRITE group for Task Instance maintenance contains Suspend, Make Success, Stop, Make Failed, Start, and Rerun.

Feature permissions are organized as feature domain → feature object → READ/WRITE → atomic operation. See Feature Objects and Privileges for the complete permission reference.

Combining Feature Permissions and Metadata Privileges

The following examples show how common responsibilities combine the two permission systems. The listed feature permissions are suggested minimum starting points; adjust them for the task type and your team's separation of duties.

Responsibility	Suggested feature permissions	Required metadata privileges
Developer	Development: Read, Download, Copy, Create, Update, Execute, Commit; Compute-Job History: Read	`USE` and `READ METADATA` on the target Virtual Cluster, plus the required Schema and data object privileges
Publisher	publish: Read, Commit, Publish; Development: Read	Membership in the target Workspace and read privileges required by the publishing workflow
Workspace operator	Read and required operations on Task maintenance, Task Instance maintenance, Complement Task maintenance, and Task Pipe maintenance; handle Alert Events; read Compute-Job History	Business table read/write privileges are not required by default; grant object privileges separately when data access is needed for troubleshooting
Data quality administrator	Create, Update, Delete, and Execute on Data Quality Rules; Rerun and status operations on Data Validation Result	Metadata and query privileges on validation objects and `USE` on the execution cluster
Notebook analyst	notebook: Read, Create, Update, Delete, Execute	Virtual Cluster `USE`, plus `READ METADATA` and `SELECT` on the target Tables or Views

⚠️ Note: Pausing or deleting a task, terminating or rerunning an instance, manually setting success or failure, modifying a PIPE, changing the workspace compute environment, and publishing a release can affect production workloads. Separate these high-impact operations from routine development permissions and review the grants regularly.

Inspect feature permissions on the role details page. SHOW GRANTS displays SQL metadata privileges and role assignments; it does not display Studio feature permissions.

Committing, Publishing, and Maintaining Scheduled Tasks

Scheduled tasks can be committed and published through Development in the Web UI. The workspace_admin and workspace_dev roles include the corresponding development permissions by default. You can also grant Development → Commit and Development → Publish to a custom workspace role.

The system role for maintaining scheduled tasks in a workspace is workspace_sre (Workspace SRE). Users with this role can manage scheduled tasks in their workspace through Operation Center → Task Maintenance, Operation Center → Alert, and Data → Data Quality.

The workspace_sre role has feature permissions for operating scheduled tasks in its workspace, but it does not have permission to use compute resources or query data objects. If an operator needs to use a Virtual Cluster or query data while troubleshooting, grant the required metadata privileges separately and with the smallest practical scope.

For unified management of scheduled tasks across all workspaces in an instance, you can grant the instance-level role instance_sre (Instance SRE). This role's permissions are the union of all workspace_sre role permissions within the service instance.

Creating Custom Roles

To practice the principle of least privilege, it is recommended to create custom roles aligned with your organization's business functions and assign them permissions for specific objects and operations. This allows you to precisely control user access to specific data or objects.

General process for creating and using custom roles:

Create a custom workspace role in the Web UI or with CREATE ROLE.
Configure the role's feature permissions in the Web UI.
Grant the required metadata privileges with GRANT or through the Web UI.
Grant the role to users with GRANT ROLE or through the Web UI.

The Web UI supports creating custom workspace roles and configuring their feature permissions and data privileges. It does not currently support custom instance-level roles. Default permissions on system preset roles are managed by Lakehouse and cannot be modified like permissions on a custom role.

⚠️ Note: In Singdata Lakehouse, roles cannot be granted to other roles; that is, role hierarchy is not supported. All roles are granted directly to users, eliminating the complexity of determining a user's effective permissions through hierarchical role inheritance.

Granting or Revoking Roles from Users

You can grant or revoke roles from users via the Web UI or SQL. Only users with the instance_admin or workspace_admin role can grant or revoke roles. The instance_admin role can grant instance-level roles to all users in the instance; the workspace_admin role can grant workspace-level roles to members within the workspace.

Via Web UI

On the Management -> Security -> Roles page, you can view instance-level and workspace-level roles in the current instance.

The instance_admin role can view all instance-level roles and all workspace-level roles, and manage grants for all instance-level roles.

The workspace_admin role can view all roles within their workspace and manage grants for those roles. If a user holds the workspace_admin role in multiple workspaces, they can manage role grants across all those workspaces.

To grant a role, click the role name to enter its detail page, where you can view all users currently granted the role. Click + Grant to User, select users in the dialog, and click Grant to assign the role to users.

To revoke a role, click the ... menu next to a user and select Remove User to remove the user's association with that role.

In the Management -> Workspace list, enter a workspace detail page, and on the Roles tab you can also view the role list within the workspace and grant or revoke roles using the same process.

Via SQL

Only workspace-level users support SQL-based authorization. Execute the following statement in a workspace to grant a workspace role to a user:

Grant ROLE <ROLE_NAME> TO USER <USER_NAME>;

Execute the following to revoke a role from a user:

REVOKE ROLE <ROLE_NAME> FROM USER <USER_NAME>;

Example: Creating a Custom Role and Granting Permissions

You can create a custom workspace role in the Web UI or with SQL. The following example uses SQL to create a role and grant metadata privileges. If the role also needs to use Studio features, configure its feature permissions in the Web UI as described in Configuring Feature Permissions.

Suppose you want to create a workspace-level role r1 to manage a specific table t1 in schema s1. You need to grant r1:

Usage permission (USAGE) on a compute cluster (e.g., named v1).
[Optional] READ METADATA permission on the compute cluster (e.g., v1) so it appears on the compute cluster page or in SHOW VCLUSTERS results.
ALL permission on table s1.t1 to perform operations such as SELECT, INSERT, UPDATE, ALTER.

Create the Custom Role

CREATE ROLE r1;

Grant Permissions to the Role

-- Grant usage permission on compute cluster (e.g., v1) to role r1 GRANT use ON VCLUSTER v1 TO ROLE r1; -- [Optional] Grant read metadata permission on compute cluster (e.g., v1) to role r1 GRANT read metadata ON VCLUSTER v1 TO ROLE r1; -- Grant all permissions on table s1.t1 to role r1 GRANT all ON table s1.t1 to ROLE r1;

Grant the Role to a User

GRANT ROLE r1 TO USER u1;

Example: Creating a Read-Only Role

If you need a role that can only query (read-only access) all tables in a schema, follow the same process as creating a custom role. The difference is that you grant only SELECT and READ METADATA permissions, without any write, modify, or delete permissions. Use ALL TABLES IN SCHEMA s1 to cover all current and future table objects in s1, simplifying the grant expression.

For example, to grant SELECT and READ METADATA permissions on all tables in schema s1 to the read_only role:

GRANT SELECT, READ METADATA ON ALL TABLES IN SCHEMA s1 TO ROLE read_only;

Note that if the read_only role does not have usage permission on a compute cluster, it cannot use compute resources to query tables. You must also grant the role usage permission on at least one compute cluster (VCluster).

For example, granting the read_only role usage permission on a compute cluster named demo_vcluster:

GRANT USE ON VCLUSTER demo_vcluster TO ROLE read_only;

Viewing Granted Permissions

Use the SHOW GRANTS command to view the current permission state of an object or role. For example:

-- View granted permissions on schema d1.s1 SHOW GRANTS ON SCHEMA d1.s1; -- View permissions granted to role r1 SHOW GRANTS TO ROLE r1; -- View permissions and roles granted to user smith SHOW GRANTS TO USER smith;

SHOW GRANTS displays role assignments and metadata privileges. View feature permissions under Management → Security → Roles → Permission → Feature.