From 0c1386944219254d7c59b618f6b50f583f68ba5f Mon Sep 17 00:00:00 2001 From: lilin90 Date: Wed, 2 Sep 2026 17:17:45 +0800 Subject: [PATCH] lake: add materialized view and update ALTER VIEW 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). --- TOC-tidb-cloud-lake.md | 5 +- tidb-cloud-lake/sql/alter-view.md | 44 ++------- tidb-cloud-lake/sql/ddl-view-overview.md | 3 +- tidb-cloud-lake/sql/materialized-view.md | 110 +++++++++++++++++++++++ 4 files changed, 121 insertions(+), 41 deletions(-) create mode 100644 tidb-cloud-lake/sql/materialized-view.md diff --git a/TOC-tidb-cloud-lake.md b/TOC-tidb-cloud-lake.md index c006dcf612f86..40baf2620d796 100644 --- a/TOC-tidb-cloud-lake.md +++ b/TOC-tidb-cloud-lake.md @@ -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) diff --git a/tidb-cloud-lake/sql/alter-view.md b/tidb-cloud-lake/sql/alter-view.md index 4673c5641cc05..404abe4d113b6 100644 --- a/tidb-cloud-lake/sql/alter-view.md +++ b/tidb-cloud-lake/sql/alter-view.md @@ -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 [ . ]view_name [ (, ...) ] 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. -## 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 ] [ . ] @@ -53,7 +21,7 @@ ALTER VIEW [ IF EXISTS ] [ . ] UNSET TAG [, ...] ``` -### Examples +## Examples ```sql ALTER VIEW default.active_users SET TAG env = 'prod', owner = 'analytics'; diff --git a/tidb-cloud-lake/sql/ddl-view-overview.md b/tidb-cloud-lake/sql/ddl-view-overview.md index 939886ac1dae6..14737860045bd 100644 --- a/tidb-cloud-lake/sql/ddl-view-overview.md +++ b/tidb-cloud-lake/sql/ddl-view-overview.md @@ -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 diff --git a/tidb-cloud-lake/sql/materialized-view.md b/tidb-cloud-lake/sql/materialized-view.md new file mode 100644 index 0000000000000..fd5368ef9727c --- /dev/null +++ b/tidb-cloud-lake/sql/materialized-view.md @@ -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. + +## Create a materialized view + +```sql +CREATE [ OR REPLACE ] MATERIALIZED VIEW [ IF NOT EXISTS ] + [ . ][ . ] + [ ( , ... ) ] + [ CLUSTER BY ( , ... ) ] + [ COMMENT = '' ] + [ = ... ] +AS +``` + +`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 [ . ][ . ] +``` + +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 CLUSTER BY ( , ... ); +ALTER MATERIALIZED VIEW DROP CLUSTER KEY; +ALTER MATERIALIZED VIEW RECLUSTER [ FINAL ] [ LIMIT ]; +ALTER MATERIALIZED VIEW SET OPTIONS (