pingcap · windtalker · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026 · Sep 1, 2026
diff --git a/TOC.md b/TOC.md
@@ -661,6 +661,8 @@
       - [`ADMIN SHOW DDL [JOBS|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md)
       - [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md)
       - [`ALTER INSTANCE`](/sql-statements/sql-statement-alter-instance.md)
+      - [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md)
+      - [`ALTER MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-alter-materialized-view-log.md)
       - [`ALTER PLACEMENT POLICY`](/sql-statements/sql-statement-alter-placement-policy.md)
       - [`ALTER RANGE`](/sql-statements/sql-statement-alter-range.md)
       - [`ALTER RESOURCE GROUP`](/sql-statements/sql-statement-alter-resource-group.md)
@@ -689,6 +691,8 @@
       - [`CREATE BINDING`](/sql-statements/sql-statement-create-binding.md)
       - [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md)
       - [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md)
+      - [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md)
+      - [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md)
       - [`CREATE PLACEMENT POLICY`](/sql-statements/sql-statement-create-placement-policy.md)
       - [`CREATE RESOURCE GROUP`](/sql-statements/sql-statement-create-resource-group.md)
       - [`CREATE ROLE`](/sql-statements/sql-statement-create-role.md)
@@ -705,6 +709,8 @@
       - [`DO`](/sql-statements/sql-statement-do.md)
       - [`DROP BINDING`](/sql-statements/sql-statement-drop-binding.md)
       - [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md)
+      - [`DROP MATERIALIZED VIEW`](/sql-statements/sql-statement-drop-materialized-view.md)
+      - [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md)
       - [`DROP PLACEMENT POLICY`](/sql-statements/sql-statement-drop-placement-policy.md)
       - [`DROP RESOURCE GROUP`](/sql-statements/sql-statement-drop-resource-group.md)
       - [`DROP ROLE`](/sql-statements/sql-statement-drop-role.md)
@@ -869,6 +875,7 @@
       - [Non-Transactional DML Statements](/non-transactional-dml.md)
       - [Pipelined DML](/pipelined-dml.md)
     - [Views](/views.md)
+    - [Materialized Views](/materialized-views.md)
     - [Partitioning](/partitioned-table.md)
     - [Temporary Tables](/temporary-tables.md)
     - [Cached Tables](/cached-tables.md)
@@ -884,6 +891,9 @@
       - `mysql` Schema
         - [Overview](/mysql-schema/mysql-schema.md)
         - [`tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md)
+        - [`tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md)
+        - [`tidb_mview_refresh_alert`](/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md)
+        - [`tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md)
         - [`user`](/mysql-schema/mysql-schema-user.md)
       - INFORMATION_SCHEMA
         - [Overview](/information-schema/information-schema.md)

diff --git a/materialized-views.md b/materialized-views.md
@@ -0,0 +1,93 @@
+---
+title: Materialized Views
+summary: Learn what materialized views are in TiDB, when to use them, and where the creation, refresh, limitation, and compatibility details belong.
+---
+
+# Materialized Views
+
+TiDB materialized views store the result of a query in a reusable object so you can avoid recomputing the same result repeatedly. This page collects the core concept, usage flow, and limitations for the feature.
+
+## Usage scenarios
+
+Materialized views are intended for workloads that repeatedly read the same query result.
+
+- Reuse expensive analytical query results.
+- Reduce repeated computation for read-heavy workloads.
+- Provide a stable result set for downstream consumers that do not need to rerun the base query each time.
+
+## Prerequisites
+
+- To create a materialized view or materialized view log, set [`tidb_mview_enable`](/system-variables.md#tidb_mview_enable) to `ON`. This variable is `OFF` by default.
+- <!-- TODO: confirm the minimum TiDB version. -->
+- <!-- TODO: confirm whether the feature depends on specific storage engines or cluster settings. -->
+
+## How it works
+
+TiDB materialized views are backed by stored data derived from a query. This page covers how to create, refresh, query, and manage materialized views.
+
+## Create and manage materialized views
+
+### Create a materialized view
+
+For the syntax of this statement, see [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md).
+
+### Create a materialized view log
+
+For the syntax of this statement, see [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md).
+
+### Control materialized view maintenance
+
+TiDB uses an internal maintenance session to build a materialized view. You can control the resources and storage engines used by this session with the following system variables:
+
+- [`tidb_mview_maintain_mem_quota`](/system-variables.md#tidb_mview_maintain_mem_quota): Sets the memory quota for the materialized view maintenance session.
+- [`tidb_mview_maintain_isolation_read_engines`](/system-variables.md#tidb_mview_maintain_isolation_read_engines): Specifies the storage engines that the maintenance session can use to read data.
+- [`tidb_mview_maintain_import_threads`](/system-variables.md#tidb_mview_maintain_import_threads): Sets the thread count for the `IMPORT INTO` operation used by the initial materialized view build. A value of `0` means that TiDB does not set an explicit thread count.
+- [`tidb_mview_maintain_import_disk_quota`](/system-variables.md#tidb_mview_maintain_import_disk_quota): Sets the disk quota for the `IMPORT INTO` operation used by the initial materialized view build. An empty value means that TiDB does not set an explicit disk quota.
+
+When you submit `CREATE MATERIALIZED VIEW`, TiDB records the current values of these variables in the DDL job and uses them for the initial build.
+
+### Refresh a materialized view
+
+This section will describe refresh behavior, supported refresh modes, and operational guidance. The `REFRESH` clause syntax is documented in [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) and [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md). <!-- TODO: fill in from the spec. -->
+
+### Query a materialized view
+
+This section will describe how queries resolve to the stored result and any optimizer behavior. <!-- TODO: fill in from the spec. -->
+
+### Alter a materialized view
+
+For the syntax of this statement, see [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md).
+
+### Alter a materialized view log
+
+For the syntax of this statement, see [`ALTER MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-alter-materialized-view-log.md).
+
+### Drop a materialized view
+
+For the syntax of these statements, see [`DROP MATERIALIZED VIEW`](/sql-statements/sql-statement-drop-materialized-view.md) and [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md).
+
+## System tables
+
+TiDB stores materialized view maintenance metadata in the `mysql` schema. The following tables are created for materialized view and materialized view log maintenance:
+
+- `mysql.tidb_mview_refresh_info`: Stores the current refresh scheduling information for each materialized view. This table is used internally by the automatic refresh scheduler.
+- `mysql.tidb_mlog_purge_info`: Stores the current purge scheduling information for each materialized view log. This table is used internally by the automatic purge scheduler.
+- [`mysql.tidb_mview_refresh_alert`](/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md): Stores the current refresh alert level for each materialized view.
+- [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md): Stores materialized view refresh history for user queries.
+- [`mysql.tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md): Stores materialized view log purge history for user queries.
+
+The `_info` tables are internal maintenance metadata tables. Do not modify TiDB system tables directly.
+
+## Limitations
+
+- <!-- TODO: list unsupported DDL, DML, replication, or optimizer cases from the spec. -->
+- <!-- TODO: add size, freshness, or compatibility limits if they exist. -->
+
+## Compatibility
+
+- <!-- TODO: describe MySQL compatibility gaps or version-specific behavior. -->
+- <!-- TODO: describe behavior differences across TiDB versions or storage layouts. -->
+
+## See also
+
+- [Views](/views.md)
diff --git a/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md b/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md
@@ -0,0 +1,49 @@
+---
+title: mysql.tidb_mlog_purge_hist
+summary: Learn about the materialized view log purge history table in the `mysql` schema.
+---
+
+# `mysql.tidb_mlog_purge_hist`
+
+The `mysql.tidb_mlog_purge_hist` table stores the purge history of materialized view logs. You can query this table to review purge jobs, their duration and status, the number of purged rows, and failure information.
+
+To view the structure of the table, use the following SQL statement:
+
+```sql
+DESC mysql.tidb_mlog_purge_hist;
+```
+
+## Fields
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `PURGE_JOB_ID` | `BIGINT UNSIGNED` | The identifier of the purge job. |
+| `MLOG_ID` | `BIGINT` | The identifier of the materialized view log. |
+| `BASE_TABLE_SCHEMA` | `VARCHAR(64)` | The schema name of the base table for the materialized view log. |
+| `BASE_TABLE_NAME` | `VARCHAR(64)` | The name of the base table for the materialized view log. |
+| `PURGE_METHOD` | `VARCHAR(32)` | The method used to purge the materialized view log. |
+| `PURGE_START_TIME` | `DATETIME(6)` | The time when the purge job started. |
+| `PURGE_END_TIME` | `DATETIME(6)` | The time when the purge job ended. |
+| `PURGE_DURATION_SEC` | `DECIMAL(18,6)` | The purge duration in seconds. |
+| `PURGE_ROWS` | `BIGINT` | The number of rows purged by the job. |
+| `PURGE_STATUS` | `VARCHAR(16)` | The status of the purge job. |
+| `PURGE_CUTOFF_TSO` | `BIGINT UNSIGNED` | The cutoff timestamp used by the purge job. |
+| `PURGE_FAILED_REASON` | `TEXT` | The reason why the purge job failed. |
+| `CANCEL_REQUEST_TIME` | `DATETIME(6)` | The time when a cancellation was requested for the purge job. |
+| `CANCEL_REQUESTED_BY` | `VARCHAR(512)` | The user or session that requested cancellation. |
+| `LAST_HEARTBEAT_TIME` | `DATETIME(6)` | The time of the latest heartbeat from the purge job. |
+
+## Examples
+
+To query the most recent materialized view log purge jobs, run the following statement:
+
+```sql
+SELECT *
+FROM mysql.tidb_mlog_purge_hist
+ORDER BY PURGE_START_TIME DESC;
+```
+
+## See also
+
+- [Materialized Views](/materialized-views.md)
+- [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md)
diff --git a/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md b/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md
@@ -0,0 +1,40 @@
+---
+title: mysql.tidb_mview_refresh_alert
+summary: Learn about the materialized view refresh alert table in the `mysql` schema.
+---
+
+# `mysql.tidb_mview_refresh_alert`
+
+The `mysql.tidb_mview_refresh_alert` table stores the current refresh alert information for each materialized view. You can query this table to check the alert level and the latest refresh status of materialized views.
+
+To view the structure of the table, use the following SQL statement:
+
+```sql
+DESC mysql.tidb_mview_refresh_alert;
+```
+
+## Fields
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `MVIEW_ID` | `BIGINT` | The identifier of the materialized view. |
+| `MVIEW_SCHEMA` | `VARCHAR(64)` | The schema name of the materialized view. |
+| `MVIEW_NAME` | `VARCHAR(64)` | The name of the materialized view. |
+| `ALERT_LEVEL` | `VARCHAR(16)` | The current alert level of the materialized view. |
+| `REFRESH_FAILED` | `VARCHAR(3)` | Indicates whether the materialized view refresh failed. |
+| `LAST_SUCCESS_SNAPSHOT_TIME` | `DATETIME(6)` | The time of the latest successful snapshot. |
+| `UPDATE_TIME` | `DATETIME(6)` | The time when the alert information was updated. |
+
+## Examples
+
+To query the refresh alert information for materialized views, run the following statement:
+
+```sql
+SELECT *
+FROM mysql.tidb_mview_refresh_alert;
+```
+
+## See also
+
+- [Materialized Views](/materialized-views.md)
+- [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md)
diff --git a/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md b/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md
@@ -0,0 +1,51 @@
+---
+title: mysql.tidb_mview_refresh_hist
+summary: Learn about the materialized view refresh history table in the `mysql` schema.
+---
+
+# `mysql.tidb_mview_refresh_hist`
+
+The `mysql.tidb_mview_refresh_hist` table stores the refresh history of materialized views. You can query this table to review refresh jobs, their duration and status, the number of refreshed rows, and failure information.
+
+To view the structure of the table, use the following SQL statement:
+
+```sql
+DESC mysql.tidb_mview_refresh_hist;
+```
+
+## Fields
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `REFRESH_JOB_ID` | `BIGINT UNSIGNED` | The identifier of the refresh job. |
+| `MVIEW_ID` | `BIGINT` | The identifier of the materialized view. |
+| `MVIEW_SCHEMA` | `VARCHAR(64)` | The schema name of the materialized view. |
+| `MVIEW_NAME` | `VARCHAR(64)` | The name of the materialized view. |
+| `REFRESH_METHOD` | `VARCHAR(32)` | The method used to refresh the materialized view. |
+| `REFRESH_START_TIME` | `DATETIME(6)` | The time when the refresh job started. |
+| `REFRESH_END_TIME` | `DATETIME(6)` | The time when the refresh job ended. |
+| `REFRESH_DURATION_SEC` | `DECIMAL(18,6)` | The refresh duration in seconds. |
+| `REFRESH_SCHEDULE_DURATION_SEC` | `DECIMAL(18,6)` | The time in seconds that the refresh job spent waiting for or being processed by the refresh scheduler. |
+| `REFRESH_STATUS` | `VARCHAR(16)` | The status of the refresh job. |
+| `REFRESH_ROWS` | `BIGINT` | The number of rows refreshed by the job. |
+| `REFRESH_READ_TSO` | `BIGINT UNSIGNED` | The read timestamp used by the refresh job. |
+| `REFRESH_COMMIT_TSO` | `BIGINT UNSIGNED` | The commit timestamp of the refresh job. |
+| `REFRESH_FAILED_REASON` | `TEXT` | The reason why the refresh job failed. |
+| `CANCEL_REQUEST_TIME` | `DATETIME(6)` | The time when a cancellation was requested for the refresh job. |
+| `CANCEL_REQUESTED_BY` | `VARCHAR(512)` | The user or session that requested cancellation. |
+| `LAST_HEARTBEAT_TIME` | `DATETIME(6)` | The time of the latest heartbeat from the refresh job. |
+
+## Examples
+
+To query the most recent materialized view refresh jobs, run the following statement:
+
+```sql
+SELECT *
+FROM mysql.tidb_mview_refresh_hist
+ORDER BY REFRESH_START_TIME DESC;
+```
+
+## See also
+
+- [Materialized Views](/materialized-views.md)
+- [`mysql.tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md)
diff --git a/mysql-schema/mysql-schema.md b/mysql-schema/mysql-schema.md
@@ -96,6 +96,14 @@ Currently, the `help_topic` is NULL.
 * [`tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md): a view of metadata locks. You can use it to view the information about the currently blocked DDL statements. See also [Metadata Lock](/metadata-lock.md).
 * `tidb_mdl_info`: used internally by TiDB to synchronize metadata locks across nodes.
 
+## System tables related to materialized views
+
+* `tidb_mview_refresh_info`: the current refresh scheduling information for each materialized view. This table is used internally by the automatic refresh scheduler.
+* `tidb_mlog_purge_info`: the current purge scheduling information for each materialized view log. This table is used internally by the automatic purge scheduler.
+* [`tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md): the refresh history of materialized views.
+* [`tidb_mview_refresh_alert`](/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md): the current refresh alert level for each materialized view.
+* [`tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md): the purge history of materialized view logs.
+
 ## System tables related to DDL statements
 
 * `tidb_ddl_history`: the history records of DDL statements
@@ -140,4 +148,4 @@ Currently, the `help_topic` is NULL.
 
 - `GLOBAL_VARIABLES`: global system variable table
 
-</CustomContent>
+</CustomContent>
diff --git a/sql-statements/sql-statement-alter-materialized-view-log.md b/sql-statements/sql-statement-alter-materialized-view-log.md
@@ -0,0 +1,63 @@
+---
+title: ALTER MATERIALIZED VIEW LOG | TiDB SQL Statement Reference
+summary: Learn how to use ALTER MATERIALIZED VIEW LOG to modify a materialized view log in TiDB.
+---
+
+# ALTER MATERIALIZED VIEW LOG
+
+The `ALTER MATERIALIZED VIEW LOG` statement changes the purge configuration or adds columns to a materialized view log. You can specify multiple actions in one statement by separating them with commas.
+
+## Synopsis
+
+```ebnf+diagram
+AlterMaterializedViewLogStmt ::=
+    'ALTER' 'MATERIALIZED' 'VIEW' 'LOG' 'ON' TableName AlterMaterializedViewLogActionList
+
+AlterMaterializedViewLogActionList ::=
+    AlterMaterializedViewLogAction ( ',' AlterMaterializedViewLogAction )*
+
+AlterMaterializedViewLogAction ::=
+    AlterMLogPurgeClause
+|   'ADD' ColumnKeywordOpt '(' ColumnList ')'
+
+AlterMLogPurgeClause ::=
+    MLogPurgeClause
+|   'PURGE'
+
+MLogPurgeClause ::=
+    'PURGE' 'IMMEDIATE'
+|   'PURGE' MLogStartWithOpt 'NEXT' Expression
+
+MLogStartWithOpt ::=
+    ( 'START' 'WITH' Expression )?
+```
+
+The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values.
+
+## Examples
+
+Change the purge schedule:
+
+```sql
+ALTER MATERIALIZED VIEW LOG ON t PURGE NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR);
+```
+
+Add columns to a materialized view log:
+
+```sql
+ALTER MATERIALIZED VIEW LOG ON t ADD COLUMN (b, c);
+```
+
+Specify multiple actions in one statement:
+
+```sql
+ALTER MATERIALIZED VIEW LOG ON t
+    PURGE,
+    ADD COLUMN (b, c);
+```
+
+## See also
+
+- [Materialized Views](/materialized-views.md)
+- [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md)
+- [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md)