Overview
Row Filter allows you to configure row filtering rules for a single table on the table details page, declare WHERE filter expressions by authorized principals (users or user groups), and limit the range of rows visible to different principals in the same table. After configuration, query requests for controlled tables automatically have the corresponding filter conditions appended in all authentication scenarios such as SQL, Notebook, and dashboards, and only rows that meet the conditions are returned.
Typical scenario: In a fact table containing nationwide orders, you may want operations personnel in South China to see only orders where region = 'south', operations personnel in North China to see only orders where region = 'north', and the operations director to see all rows. This can be achieved by adding row filter expressions for different user groups.
Prerequisites
Before you start this operation, make sure the following prerequisites are met:
You have activated the DataBuddy service and completed workspace initialization.
The current account has the Grant permission on the target table, which means the account has access to the "+ Grant" button. For details about permission semantics, see Members and Permission Management. The authorized principals for row filtering have been determined (users or user groups), and the user groups have been created in the workspace.
Use Limits
Limit | Description |
Applicable Scope | Row-level permission rules are configured per table and apply to that table. |
Authorized principal type | Supports users and user groups; when the same principal appears at both the user level and the user group level, the permission scope is the union of both. |
Expression format | A row filtering expression is a standard SQL WHERE clause fragment, for example, year > 2010 AND country != 'US'. |
Expression length | The maximum length of a single row filtering expression is 2,000 characters. |
Number of rules. | There is no hard limit on the number of row-level permission rules that can be configured for a single table. |
Validation item | Expressions support one-click validation, including basic checks such as whether fields exist, logic, and syntax; if validation fails, corrections are required before saving. |
Schema change behavior | After a field referenced by a row filtering expression is renamed or deleted from the table Schema, the related row-level permission rules automatically become invalid; you must edit the expression again to restore row-level permission control. |
User group member change | After user group members are added or removed, queries that are already in progress do not switch their visible row set in real time; the change takes effect for subsequently issued queries. |
Permission inheritance | The visibility of the Row permissions Tab inherits the visibility of the Permissions Tab on the table details page; the clickability of the + Grant > Row permissions button inherits the permissions of the + Grant button itself. |
Scope of supporting capabilities | Advanced security capabilities such as column-level permissions, ABAC policies, and dynamic views are not yet publicly available in the current version and will be gradually rolled out in subsequent versions. |
Operation Steps
Step 1: Go to the Data Table Details Page
2. Switch to the target region and Workspace at the top.
3. Select Data Catalog in the left sidebar.
4. Find the target table in Catalog → Schema and go to its details page.
Step 2: Go to the Row Permission Management Panel
1. Click the "Grant" button, and two options will appear in the drop-down list: Table Permissions and Row Permissions.
2. Click Row Permissions to go to the row permission configuration panel for the table.
Step 3: Add a Row Permission Rule
1. On the row permission management panel, choose + Grant > Row Permissions to go to the row-level permission configuration page.
2. Select the authorized principals by switching between Users and User Groups. Fuzzy search, multiple selection, and select all are supported.
3. Enter the row filter expression: fill in a WHERE clause fragment, for example, year > 2010 AND country != 'US'.
4. First select the compute resources, and then click Validate to check whether the expression is valid, including whether the fields exist and whether the logic and syntax are correct. If validation fails, make corrections as prompted before saving.
5. After validation passes, click OK to save.
Tip
When rules are added for multiple principals on the same table, the configuration panel saves one record for each user and user group. Subsequent edits and removals are performed on individual records separately.
Step 4: Edit or Remove a Row Permission Rule
1. Locate the target record in the row permission list.
2. Click Edit to modify the row filter expression. After modification, validate it again and save.
3. After clicking Remove, confirm the deletion in the dialog box. The rule takes effect immediately after confirmation.
Parameter Description
Parameter | Description | Required | Default Value | Value Range |
Authorized object | Select the principal to which the row rule applies. You can switch between users and user groups, and fuzzy search, multi-select, and select all are supported. | Yes | - | Existing Users / User Groups in the Current Workspace |
Row filtering expression | A standard SQL WHERE clause fragment. Referenced fields must be actual fields in the table. Maximum length: 2000 characters. | Yes | - | For example, region = 'south', year > 2010 AND country != 'US' |
Verification Result
After the operation is completed, you can confirm in the following ways:
1. In the Row Permissions panel list on the table details page, you can see the rule you just saved. The authorized principal, principal type, and expression are all displayed correctly.
2. Use the account of the corresponding principal to execute SELECT * FROM <table_name> in Studio. The returned row set contains only rows that meet the expression condition.
3. If you switch to a principal that has no row permissions configured but has table query permissions, all rows can still be queried. This mechanism ensures that access is restricted only for principals with explicitly configured rules.
FAQs
Q: If a user belongs to a user group and is also granted row permissions individually, which rows can the user see?
A: Take the union of all rules. For example, if the user group rule is region = 'south' and the user rule is vip = true, the rows ultimately visible to this user are all records where region = 'south' or vip = true.
Q: What syntax is supported in row filter expressions?
A: Use a standard SQL WHERE clause fragment. You can use common syntax such as comparison operators (= != > < >= <=), logical operators (AND OR NOT), IN lists, BETWEEN, and LIKE. The supported functions and operators depend on the actual capabilities of the underlying engine. We recommend that you use the Validate feature during editing to verify whether the expression is valid.
Q: Does deleting a row permission rule take effect immediately?
A: The removal takes effect immediately for subsequent queries. Queries that are already in progress will not be forcibly interrupted.
Q: Which query entries does row-level permission apply to?
A: After the row filter is configured, the controlled table controls row visibility based on the row filter expression logic. This applies to all SQL query scenarios that require authentication, including Studio SQL, Notebook, dashboards, and SQL tasks in workflows.
References
Column-level permission control