Skip to content

lake: add materialized view and update ALTER VIEW #23711

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lilin90 wants to merge 1 commit into
base: release-8.5
Choose a base branch
from
Open

lake: add materialized view and update ALTER VIEW #23711

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions TOC-tidb-cloud-lake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,11 +258,12 @@
- [SHOW TABLES](/tidb-cloud-lake/sql/show-tables.md)
- View
- [Overview](/tidb-cloud-lake/sql/ddl-view-overview.md)
- [ALTER VIEW](/tidb-cloud-lake/sql/alter-view.md)
- [CREATE VIEW](/tidb-cloud-lake/sql/create-view.md)
- [DROP VIEW](/tidb-cloud-lake/sql/drop-view.md)
- [ALTER VIEW](/tidb-cloud-lake/sql/alter-view.md)
- [DESC VIEW](/tidb-cloud-lake/sql/desc-view.md)
- [SHOW VIEWS](/tidb-cloud-lake/sql/show-views.md)
- [DROP VIEW](/tidb-cloud-lake/sql/drop-view.md)
- [Materialized View](/tidb-cloud-lake/sql/materialized-view.md)
- User & Role
- [Overview](/tidb-cloud-lake/sql/user-role.md)
- [CREATE USER](/tidb-cloud-lake/sql/create-user.md)
Expand Down
44 changes: 6 additions & 38 deletions tidb-cloud-lake/sql/alter-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,45 +5,13 @@ summary: Alter the existing view by using another QUERY.

# ALTER VIEW

Alter the existing view by using another `QUERY`.
Assigns or removes tags on an existing view. Tags must be created with [CREATE TAG](/tidb-cloud-lake/sql/create-tag.md) first. For full details, see [SET TAG / UNSET TAG](/tidb-cloud-lake/sql/set-tag.md).

## Syntax

```sql
ALTER VIEW [ <database_name>. ]view_name [ (<column>, ...) ] AS SELECT query
```
> **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.

@coderabbitai coderabbitai Bot Sep 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.md

Repository: 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:

🏁 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/&amp;/\&/g; s/&quot;/"/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
done

Repository: 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


## Examples

```sql
CREATE VIEW tmp_view AS SELECT number % 3 AS a, avg(number) FROM numbers(1000) GROUP BY a ORDER BY a;

SELECT * FROM tmp_view;
+------+-------------+
| a | avg(number) |
+------+-------------+
| 0 | 499.5 |
| 1 | 499.0 |
| 2 | 500.0 |
+------+-------------+

ALTER VIEW tmp_view(c1) AS SELECT * from numbers(3);

SELECT * FROM tmp_view;
+------+
| c1 |
+------+
| 0 |
| 1 |
| 2 |
+------+
```

## Tag Operations {#tag-operations}

Assigns or removes tags on a view. Tags must be created with [CREATE TAG](/tidb-cloud-lake/sql/create-tag.md) first. For full details, see [SET TAG / UNSET TAG](/tidb-cloud-lake/sql/set-tag.md).

### Syntax
## Syntax

```sql
ALTER VIEW [ IF EXISTS ] [ <database_name>. ]<view_name>
Expand All @@ -53,7 +21,7 @@ ALTER VIEW [ IF EXISTS ] [ <database_name>. ]<view_name>
UNSET TAG <tag_name> [, <tag_name> ...]
```

### Examples
## Examples

```sql
ALTER VIEW default.active_users SET TAG env = 'prod', owner = 'analytics';
Expand Down
3 changes: 2 additions & 1 deletion tidb-cloud-lake/sql/ddl-view-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,9 @@ This page provides a comprehensive overview of view operations in {{{ .lake }}},
| Command | Description |
|---------|-------------|
| [CREATE VIEW](/tidb-cloud-lake/sql/create-view.md) | Creates a new view based on a query |
| [ALTER VIEW](/tidb-cloud-lake/sql/alter-view.md) | Modifies an existing view |
| [ALTER VIEW](/tidb-cloud-lake/sql/alter-view.md) | Assigns or removes tags on an existing view |
| [DROP VIEW](/tidb-cloud-lake/sql/drop-view.md) | Removes a view |
| [Materialized View](/tidb-cloud-lake/sql/materialized-view.md) | Creates and maintains a materialized view backed by physical storage |

## View Information

Expand Down
110 changes: 110 additions & 0 deletions tidb-cloud-lake/sql/materialized-view.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
title: Materialized View
summary: A materialized view stores the result of a query physically. TiDB Cloud Lake enables change tracking on the source table when the materialized view is created.
---

# Materialized View

A materialized view stores the result of a query physically. It is defined on one persistent FUSE table in the `default` catalog. {{{ .lake }}} enables change tracking on the source table when the materialized view is created.

Unlike a logical view, a materialized view can be explicitly refreshed to persist the changes from its source table. Reads are consistent even when physical storage lags behind the source table. Before the first refresh, {{{ .lake }}} evaluates the definition against the source. When there are unrefreshed source changes, {{{ .lake }}} uses **read fix**: it unions the persisted materialized-view data with the required incremental source data at read time (and applies the view definition to that increment). The query therefore returns current results rather than stale materialized data.

## Limitations

- 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.

@coderabbitai coderabbitai Bot Sep 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ 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.

Suggested change
- 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


## Create a materialized view

```sql
CREATE [ OR REPLACE ] MATERIALIZED VIEW [ IF NOT EXISTS ]
[ <catalog_name>. ][ <database_name>. ]<view_name>
[ ( <column_name>, ... ) ]
[ CLUSTER BY ( <expr>, ... ) ]
[ COMMENT = '<comment>' ]
[ <fuse_table_option> = <value> ... ]
AS <query>
```

`CLUSTER BY` requires an explicit column list and can reference non-aggregate output columns or `GROUP BY` keys. The optional Fuse table options control the physical storage layout; see [CREATE TABLE](/tidb-cloud-lake/sql/create-table.md) for supported options.

Creation records the definition but does not synchronously populate physical storage. Run `REFRESH MATERIALIZED VIEW` to materialize the initial data.

```sql
CREATE TABLE orders (
order_id INT,
customer_id INT,
amount DECIMAL(10, 2),
paid BOOLEAN
);

CREATE MATERIALIZED VIEW paid_orders_by_customer
(customer_id, total_amount, order_count)
CLUSTER BY (customer_id)
COMMENT = 'Paid-order totals by customer'
AS
SELECT customer_id, sum(amount), count(*)
FROM orders
WHERE paid
GROUP BY customer_id;

REFRESH MATERIALIZED VIEW paid_orders_by_customer;
```

`CREATE OR REPLACE` replaces an existing materialized view. `IF NOT EXISTS` is a no-op if the name already exists.

## Refresh a materialized view

```sql
REFRESH MATERIALIZED VIEW [ <catalog_name>. ][ <database_name>. ]<view_name>
```

The first refresh materializes the source data. Later refreshes process append-only changes incrementally. If the source has `UPDATE`, `DELETE`, or `TRUNCATE` changes, {{{ .lake }}} rebuilds the materialized view from the current source state so that the result remains correct.

## Change physical layout

Use dedicated `ALTER MATERIALIZED VIEW` syntax for supported maintenance operations:

```sql
ALTER MATERIALIZED VIEW <view_name> CLUSTER BY ( <expr>, ... );
ALTER MATERIALIZED VIEW <view_name> DROP CLUSTER KEY;
ALTER MATERIALIZED VIEW <view_name> RECLUSTER [ FINAL ] [ LIMIT <n> ];
ALTER MATERIALIZED VIEW <view_name> SET OPTIONS ( <option> = <value>, ... );
ALTER MATERIALIZED VIEW <view_name> UNSET OPTIONS ( <option>, ... );
ALTER MATERIALIZED VIEW <view_name> COMMENT = '<comment>';
```

For example, set a layout option before a refresh:

```sql
ALTER MATERIALIZED VIEW paid_orders_by_customer SET OPTIONS (row_per_block = 2);
REFRESH MATERIALIZED VIEW paid_orders_by_customer;
```

`RECLUSTER WHERE` is not supported for materialized views. To change the definition, use `CREATE OR REPLACE MATERIALIZED VIEW`; `ALTER VIEW` does not apply.

## View and remove definitions

```sql
SHOW MATERIALIZED VIEWS
[ { FROM | IN } <database_name> ]
[ LIKE '<pattern>' | WHERE <expr> ];

SHOW CREATE MATERIALIZED VIEW
[ <catalog_name>. ][ <database_name>. ]<view_name>;

DROP MATERIALIZED VIEW [ IF EXISTS ]
[ <catalog_name>. ][ <database_name>. ]<view_name>;
```

```sql
SHOW MATERIALIZED VIEWS LIKE 'paid_orders%';
SHOW CREATE MATERIALIZED VIEW paid_orders_by_customer;
DROP MATERIALIZED VIEW IF EXISTS paid_orders_by_customer;
```

## Access control requirements

To query, refresh, alter, show, or drop a materialized view, the user needs `SELECT` on its source table (or ownership that provides the equivalent access). Permissions are checked against the current source table identity, so source-table renames do not change this requirement.