lake: add materialized view and update ALTER VIEW - #23711
Conversation
Introduce a new Materialized View page covering concepts, limitations, create/refresh/alter/show/drop syntax, and access control. Update the View TOC and overview to include materialized views, and clarify that `ALTER VIEW` in TiDB Cloud Lake is for tag management only (with guidance to use `CREATE OR REPLACE VIEW` for definition changes).
lilin90
added
translation/no-need
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
ti-chi-bot
Bot
added
the
size/L
📝 WalkthroughWalkthroughThe documentation adds a materialized-view reference, updates view navigation, clarifies ChangesView documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: 🟡 Moderate · up to The documentation currently misstates ALTER VIEW capabilities and leaves materialized-view refresh and automatic-maintenance behavior contradictory, which could lead users to apply unsupported SQL or misunderstand result freshness. Merge should wait until these behavior descriptions are corrected. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Full details: Description checkExplanation The description includes the required change summary and affected TiDB version. Optional reference links and conditional checklist items are left blank, but the description is otherwise complete and relevant. Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.) ✨ 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: 2
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Team
Run ID: 5c3c0967-ad05-465c-a23a-a7363490f886
📒 Files selected for processing (4)
TOC-tidb-cloud-lake.mdtidb-cloud-lake/sql/alter-view.mdtidb-cloud-lake/sql/ddl-view-overview.mdtidb-cloud-lake/sql/materialized-view.md
Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.
| ``` | ||
| > **Note:** | ||
| > | ||
| > `ALTER VIEW ... AS ...` is not supported. To change a view's query or output columns, use [CREATE OR REPLACE VIEW](/tidb-cloud-lake/sql/create-view.md) instead. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- applicable conventions ---'
find /tmp/coderabbit-repo-knowledge/pingcap-docs-9c73f70c -maxdepth 2 -type f \( -path '*/coding-guidelines/*' -o -path '*/conventions/*' -o -path '*/learnings/*' -o -path '*/architecture/*' \) -print 2>/dev/null | sort
printf '%s\n' '--- repository files ---'
git ls-files 'tidb-cloud-lake/sql/alter-view.md' '*privilege*' '*view*.md' | head -80
printf '%s\n' '--- target document ---'
cat -n tidb-cloud-lake/sql/alter-view.md
printf '%s\n' '--- diff summary and target diff ---'
git diff --stat
git diff -- tidb-cloud-lake/sql/alter-view.mdRepository: pingcap/docs
Length of output: 4868
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- repository review conventions ---'
cat /tmp/coderabbit-repo-knowledge/pingcap-docs-9c73f70c/conventions/repo-wide.md
printf '%s\n' '--- privilege references to ALTER VIEW ---'
rg -n -C 5 'ALTER VIEW|alter an existing view|another query' tidb-cloud-lake/guides/privileges.md tidb-cloud-lake/lake-overview.md tidb-cloud-lake/sql/*.md
printf '%s\n' '--- related view documents ---'
cat -n tidb-cloud-lake/sql/create-view.md | sed -n '1,180p'
cat -n tidb-cloud-lake/sql/ddl-view-overview.md | sed -n '1,160p'Repository: pingcap/docs
Length of output: 12078
🌐 Web query:
TiDB Cloud Lake v8.5 ALTER VIEW AS SELECT support CREATE OR REPLACE VIEW privileges
💡 Result:
In TiDB Cloud Lake v8.5, the support for ALTER VIEW and CREATE OR REPLACE VIEW differs significantly from the standard TiDB (MySQL-compatible) product. For TiDB Cloud Lake v8.5: - ALTER VIEW: Full support is provided for the ALTER VIEW ... AS SELECT ... statement to modify an existing view [1][2]. - CREATE OR REPLACE VIEW: Support for the OR REPLACE syntax is explicitly documented, allowing you to overwrite an existing view with the same name [3]. - Privilege Requirements: To access a view in TiDB Cloud Lake, users only require the SELECT privilege on the view itself; separate permissions on the underlying base tables are not required [3]. In contrast, standard TiDB (e.g., v8.1, v8.5) does not support the ALTER VIEW statement [4][5]. In standard TiDB, you must either drop and recreate the view or use CREATE OR REPLACE VIEW to update it [4][6]. Standard TiDB also requires specific privileges, such as CREATE VIEW (and potentially SUPER depending on the situation), to manage views [7][8]. Always ensure you are consulting the documentation specific to the "TiDB Cloud Lake" product line if you are utilizing that architecture, as its SQL syntax and behavioral characteristics may diverge from the standard TiDB database product [1][2][3].
Citations:
- 1: https://docs.pingcap.com/tidbcloudlake/alter-view/
- 2: https://docs.pingcap.com/tidbcloudlake/ddl-view-overview/
- 3: https://docs.pingcap.com/tidbcloudlake/create-view/
- 4: https://docs.pingcap.com/developer/dev-guide-use-views/
- 5: https://docs.pingcap.com/tidb/stable/sql-statement-create-view/
- 6: https://docs.pingcap.com/tidb/v8.1/sql-statement-create-view/
- 7: https://docs.pingcap.com/tidb/stable/privilege-management/
- 8: https://docs.pingcap.com/tidb/v8.1/privilege-management/
🏁 Script executed:
#!/bin/bash
set -eu
for url in \
'https://docs.pingcap.com/tidbcloudlake/alter-view/' \
'https://docs.pingcap.com/tidbcloudlake/ddl-view-overview/' \
'https://docs.pingcap.com/tidbcloudlake/guides/privileges/'; do
printf '\n--- %s ---\n' "$url"
curl -L --max-time 15 -fsS "$url" |
sed 's/<[^>]*>/ /g; s/&/\&/g; s/"/"/g; s/&`#39`;/'"'"'/g' |
tr -s '[:space:]' ' ' |
grep -o -E '.{0,220}(ALTER VIEW|CREATE OR REPLACE VIEW|another query|view privilege).{0,320}' || true
doneRepository: pingcap/docs
Length of output: 4095
Restore ALTER VIEW ... AS SELECT ... support.
The TiDB Cloud Lake ALTER VIEW contract documents this syntax and examples. Line 12 contradicts that contract and removes supported query alteration from the page. Restore the syntax and examples instead of documenting it as unsupported.
Sources: Path instructions, MCP tools
| - A definition must be a simple `SELECT ... FROM ... [WHERE ...] [GROUP BY ...]` query over exactly one base table. Joins, subqueries, set operations, and non-deterministic functions are not supported. | ||
| - Aggregations are supported only for `sum`, `min`, `max`, `avg`, `count`, and `approx_count_distinct`. `DISTINCT`, `FILTER`, window, and ordered aggregate forms are not supported. | ||
| - The source must be a persistent FUSE base table in the `default` catalog. A materialized view cannot use another view or a different table engine as its source. | ||
| - Materialized views are read-only. Use `REFRESH MATERIALIZED VIEW` to maintain their contents; `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and ordinary `ALTER TABLE` operations are not supported. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Separate automatic maintenance from explicit refresh.
The capability table at tidb-cloud-lake/guides/editions.md:64 advertises automatic maintenance of materialized-view results. tidb-cloud-lake/sql/ddl-view-overview.md:17 also says that materialized views are maintained. This bullet instead says users must use REFRESH MATERIALIZED VIEW to maintain contents. Clarify which changes are automatic and which require explicit refresh. (docs.pingcap.com)
Committable replacement
- Materialized views are read-only. Use `REFRESH MATERIALIZED VIEW` to maintain their contents; `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and ordinary `ALTER TABLE` operations are not supported.
+ Materialized views are read-only. {{{ .lake }}} automatically maintains their results for supported source changes. Use `REFRESH MATERIALIZED VIEW` to materialize the initial data and to rebuild the result when incremental maintenance is invalidated; `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and ordinary `ALTER TABLE` operations on the materialized view are not supported.As per path instructions, this Markdown finding includes a committable replacement because the fix is a safe contiguous change.
📝 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.
| - Materialized views are read-only. Use `REFRESH MATERIALIZED VIEW` to maintain their contents; `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and ordinary `ALTER TABLE` operations are not supported. | |
| Materialized views are read-only. {{{ .lake }}} automatically maintains their results for supported source changes. Use `REFRESH MATERIALIZED VIEW` to materialize the initial data and to rebuild the result when incremental maintenance is invalidated; `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and ordinary `ALTER TABLE` operations on the materialized view are not supported. |
Sources: Path instructions, MCP tools
1 participant
What is changed, added or deleted? (Required)
Introduce a new Materialized View page covering concepts, limitations, create/refresh/alter/show/drop syntax, and access control. Update the View TOC and overview to include materialized views, and clarify that
ALTER VIEWin TiDB Cloud Lake is for tag management only (with guidance to useCREATE OR REPLACE VIEWfor definition changes).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
New Features
Documentation
ALTER VIEW ... AS SELECTis unsupported; useCREATE OR REPLACE VIEWinstead.ALTER VIEWdocumentation to focus on assigning or removing tags.