lake: refine data protection policy guide docs#23314
Conversation
Reworked the Lake data protection documentation for clarity and faster onboarding: simplified the main data protection overview, condensed masking and row access guides into quick-start and example-driven sections, and clarified policy interactions, limits, and privilege requirements. Also added a vector search cross-reference showing how row access policies enforce role-based document visibility in RAG/search workflows.
lilin90
added
translation/no-need
ti-chi-bot
Bot
added
the
size/XXL
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughChangesThe PR restructures four data protection guides with shorter explanations, updated SQL examples, revised policy behavior documentation, and expanded row-access guidance for Vector/RAG and role-based time windows. Data Protection Policy Documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4c8dbf3b-66c2-41d5-9ec8-89eca82943ef
📒 Files selected for processing (4)
tidb-cloud-lake/guides/data-protection-policies.mdtidb-cloud-lake/guides/masking-policy.mdtidb-cloud-lake/guides/row-access-policy.mdtidb-cloud-lake/guides/vector-search-guide.md
| Multi-column policy: | ||
|
|
||
| ```sql | ||
| SET enable_experimental_row_access_policy = 1; | ||
|
|
||
| DROP TABLE IF EXISTS rap_dml_orders; | ||
| DROP TABLE IF EXISTS rap_dml_src; | ||
| DROP ROW ACCESS POLICY IF EXISTS rap_sales_only; | ||
|
|
||
| CREATE ROW ACCESS POLICY rap_sales_only | ||
| AS (dept STRING) | ||
| RETURNS BOOLEAN -> dept = 'sales'; | ||
|
|
||
| CREATE TABLE rap_dml_orders(id INT, dept STRING, amount INT); | ||
| ALTER TABLE rap_dml_orders ADD ROW ACCESS POLICY rap_sales_only ON (dept); | ||
|
|
||
| -- INSERT is not affected: both visible and invisible rows are stored. | ||
| INSERT INTO rap_dml_orders VALUES | ||
| (1, 'sales', 100), | ||
| (2, 'eng', 200), | ||
| (3, 'sales', 300); | ||
|
|
||
| -- SELECT is affected: only policy-visible rows are returned. | ||
| SELECT id, dept, amount FROM rap_dml_orders ORDER BY id; | ||
|
|
||
| id | dept | amount | ||
| ---|-------|------- | ||
| 1 | sales | 100 | ||
| 3 | sales | 300 | ||
|
|
||
| -- Detach only for inspection: the inserted 'eng' row exists. | ||
| ALTER TABLE rap_dml_orders DROP ROW ACCESS POLICY rap_sales_only; | ||
| SELECT id, dept, amount FROM rap_dml_orders ORDER BY id; | ||
|
|
||
| id | dept | amount | ||
| ---|-------|------- | ||
| 1 | sales | 100 | ||
| 2 | eng | 200 | ||
| 3 | sales | 300 | ||
|
|
||
| ALTER TABLE rap_dml_orders ADD ROW ACCESS POLICY rap_sales_only ON (dept); | ||
|
|
||
| -- UPDATE is affected: only visible target rows are updated. | ||
| UPDATE rap_dml_orders SET amount = amount + 10; | ||
|
|
||
| ALTER TABLE rap_dml_orders DROP ROW ACCESS POLICY rap_sales_only; | ||
| SELECT id, dept, amount FROM rap_dml_orders ORDER BY id; | ||
|
|
||
| id | dept | amount | ||
| ---|-------|------- | ||
| 1 | sales | 110 | ||
| 2 | eng | 200 | ||
| 3 | sales | 310 | ||
|
|
||
| ALTER TABLE rap_dml_orders ADD ROW ACCESS POLICY rap_sales_only ON (dept); | ||
|
|
||
| -- DELETE is affected: invisible target rows are not deleted. | ||
| DELETE FROM rap_dml_orders WHERE dept = 'eng'; | ||
|
|
||
| ALTER TABLE rap_dml_orders DROP ROW ACCESS POLICY rap_sales_only; | ||
| SELECT id, dept, amount FROM rap_dml_orders ORDER BY id; | ||
|
|
||
| id | dept | amount | ||
| ---|-------|------- | ||
| 1 | sales | 110 | ||
| 2 | eng | 200 | ||
| 3 | sales | 310 | ||
|
|
||
| ALTER TABLE rap_dml_orders ADD ROW ACCESS POLICY rap_sales_only ON (dept); | ||
|
|
||
| -- DELETE still affects visible target rows. | ||
| DELETE FROM rap_dml_orders WHERE id = 1; | ||
| CREATE ROW ACCESS POLICY rap_region_dept | ||
| AS (region STRING, dept STRING) | ||
| RETURNS BOOLEAN -> | ||
| region = 'APAC' AND dept = 'Engineering'; | ||
|
|
||
| ALTER TABLE rap_dml_orders DROP ROW ACCESS POLICY rap_sales_only; | ||
| SELECT id, dept, amount FROM rap_dml_orders ORDER BY id; | ||
| ALTER TABLE employees | ||
| ADD ROW ACCESS POLICY rap_region_dept ON (office_region, department); | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== .ai/AI-README.md ==\n'
sed -n '1,220p' .ai/AI-README.md
printf '\n== .ai/shared ==\n'
fd -t f . .ai/shared | sort | sed -n '1,200p'
printf '\n== .ai/skills ==\n'
fd -t f . .ai/skills | sort | sed -n '1,200p'
printf '\n== target file outline ==\n'
ast-grep outline tidb-cloud-lake/guides/row-access-policy.md --view expanded || true
printf '\n== target file excerpt ==\n'
sed -n '1,380p' tidb-cloud-lake/guides/row-access-policy.mdRepository: pingcap/docs
Length of output: 234
🏁 Script executed:
sed -n '1,220p' .ai/AI-README.mdRepository: pingcap/docs
Length of output: 210
🌐 Web query:
TiDB row access policy only one row access policy per table multi-column ALTER TABLE ADD ROW ACCESS POLICY ON
💡 Result:
In TiDB, a table can have at most one row access policy attached to it at any given time [1][2]. Consequently, you cannot add multiple row access policies to a single table [1]. If you need to implement complex filtering logic that involves multiple conditions, the recommended approach is to define a single row access policy that incorporates all required conditions using Boolean logic within the policy's predicate expression [3]. When using the ALTER TABLE ADD ROW ACCESS POLICY statement, you can map multiple table columns to the policy's arguments [1]. These columns are bound to the policy arguments by position rather than by name [1][2]. For example: CREATE ROW ACCESS POLICY rap_example AS (arg1 STRING, arg2 STRING) RETURNS BOOLEAN -> arg1 = 'Value1' AND arg2 = 'Value2'; ALTER TABLE my_table ADD ROW ACCESS POLICY rap_example ON (column1, column2); To change or update a policy, you must first drop the existing policy using DROP ROW ACCESS POLICY or DROP ALL ROW ACCESS POLICIES before adding a new one, as CREATE OR REPLACE and ALTER ROW ACCESS POLICY operations are not supported [1][2].
Citations:
- 1: https://docs.pingcap.com/tidbcloudlake/row-access-policy/
- 2: https://docs.pingcap.com/tidbcloudlake/alter-table/
- 3: https://docs.pingcap.com/tidbcloudlake/create-row-access-policy/
Make the multi-column example use its own table.
employees can have only one row access policy, so this example should not attach a second policy to the same table.
Committable suggestion
-Multi-column policy:
+Multi-column policy (use a separate table):
```sql
CREATE ROW ACCESS POLICY rap_region_dept
AS (region STRING, dept STRING)
RETURNS BOOLEAN ->
region = 'APAC' AND dept = 'Engineering';
-ALTER TABLE employees
+CREATE TABLE employee_locations (
+ office_region STRING,
+ department STRING
+);
+
+ALTER TABLE employee_locations
ADD ROW ACCESS POLICY rap_region_dept ON (office_region, department);</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
Multi-column policy (use a separate table):
Source: Path instructions
| GRANT SELECT ON knowledge_docs TO ROLE sales; | ||
| GRANT SELECT ON knowledge_docs TO ROLE finance; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== .ai files ==\n'
git ls-files .ai | sed -n '1,200p'
printf '\n== .ai/AI-README.md ==\n'
sed -n '1,220p' .ai/AI-README.md
printf '\n== .ai/shared (if present) ==\n'
find .ai/shared -maxdepth 1 -type f | sort | sed -n '1,200p'
printf '\n== .ai/skills (if present) ==\n'
find .ai/skills -maxdepth 2 -type f | sort | sed -n '1,200p'
printf '\n== target file outline ==\n'
wc -l tidb-cloud-lake/guides/row-access-policy.md
sed -n '1,240p' tidb-cloud-lake/guides/row-access-policy.mdRepository: pingcap/docs
Length of output: 251
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== file size and relevant range ==\n'
wc -l tidb-cloud-lake/guides/row-access-policy.md
sed -n '1,220p' tidb-cloud-lake/guides/row-access-policy.md
printf '\n== search for admin role references in this guide ==\n'
rg -n "ROLE admin|admin sees|admin" tidb-cloud-lake/guides/row-access-policy.md
printf '\n== search for knowledge_docs grants in repo ==\n'
rg -n "GRANT SELECT ON knowledge_docs TO ROLE" tidb-cloud-lake -g '*.md'Repository: pingcap/docs
Length of output: 7428
Grant admin SELECT on knowledge_docs.
The visibility table says admin sees all rows, but the example only grants SELECT to sales and finance. Add the missing grant so the admin role can query the table too.
Committable replacement
+GRANT SELECT ON knowledge_docs TO ROLE admin;
GRANT SELECT ON knowledge_docs TO ROLE sales;
GRANT SELECT ON knowledge_docs TO ROLE finance;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| GRANT SELECT ON knowledge_docs TO ROLE sales; | |
| GRANT SELECT ON knowledge_docs TO ROLE finance; | |
| GRANT SELECT ON knowledge_docs TO ROLE admin; | |
| GRANT SELECT ON knowledge_docs TO ROLE sales; | |
| GRANT SELECT ON knowledge_docs TO ROLE finance; |
Source: Path instructions
|
@awxxxxxx: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this: Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: lilin90 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
2 participants
What is changed, added or deleted? (Required)
Reworked the Lake data protection documentation for clarity and faster onboarding: simplified the main data protection overview, condensed masking and row access guides into quick-start and example-driven sections, and clarified policy interactions, limits, and privilege requirements.
Also added a vector search cross-reference showing how row access policies enforce role-based document visibility in RAG/search workflows.
Which TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit