From 63e0faee2a25a06a13f4711e17db747043897612 Mon Sep 17 00:00:00 2001 From: xufei Date: Mon, 31 Aug 2026 09:40:42 +0800 Subject: [PATCH 1/6] docs: add materialized views framework --- TOC.md | 1 + materialized-views.md | 57 +++++++++++++++++++++++++++++++++++++++++++ views.md | 2 +- 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 materialized-views.md diff --git a/TOC.md b/TOC.md index d440ed29e3a8d..123b8a14f4f92 100644 --- a/TOC.md +++ b/TOC.md @@ -869,6 +869,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) diff --git a/materialized-views.md b/materialized-views.md new file mode 100644 index 0000000000000..21e563e327f13 --- /dev/null +++ b/materialized-views.md @@ -0,0 +1,57 @@ +--- +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 + +- +- + +## How it works + +TiDB materialized views are backed by stored data derived from a query. The final design will define how TiDB creates, refreshes, and invalidates that data. + +## Create and manage materialized views + +### Create a materialized view + +This section will describe the supported creation flow, required clauses, and examples. + +### Refresh a materialized view + +This section will describe refresh behavior, supported refresh modes, and operational guidance. + +### Query a materialized view + +This section will describe how queries resolve to the stored result and any optimizer behavior. + +### Drop a materialized view + +This section will describe cleanup behavior and any related objects. + +## Limitations + +- +- + +## Compatibility + +- +- + +## See also + +- [Views](/views.md) diff --git a/views.md b/views.md index 2229ab7e2f275..a1d8c2f6c0f43 100644 --- a/views.md +++ b/views.md @@ -238,7 +238,6 @@ Query OK, 0 rows affected (0.02 sec) Currently, views in TiDB are subject to the following limitations: -* Materialized views are not supported yet. * Views in TiDB are read-only and do not support write operations such as `UPDATE`, `INSERT`, `DELETE`, and `TRUNCATE`. * For created views, the only supported DDL operation is `DROP [VIEW | TABLE]` @@ -246,3 +245,4 @@ Currently, views in TiDB are subject to the following limitations: - [CREATE VIEW](/sql-statements/sql-statement-create-view.md) - [DROP VIEW](/sql-statements/sql-statement-drop-view.md) +- [Materialized Views](/materialized-views.md) From 22f4127e80760d1f80452be28e2c2c3c853e55b0 Mon Sep 17 00:00:00 2001 From: xufei Date: Mon, 31 Aug 2026 14:04:06 +0800 Subject: [PATCH 2/6] docs: document materialized view system tables --- TOC.md | 3 ++ materialized-views.md | 12 +++++ .../mysql-schema-tidb-mlog-purge-hist.md | 49 ++++++++++++++++++ .../mysql-schema-tidb-mview-refresh-alert.md | 40 +++++++++++++++ .../mysql-schema-tidb-mview-refresh-hist.md | 51 +++++++++++++++++++ mysql-schema/mysql-schema.md | 10 +++- 6 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 mysql-schema/mysql-schema-tidb-mlog-purge-hist.md create mode 100644 mysql-schema/mysql-schema-tidb-mview-refresh-alert.md create mode 100644 mysql-schema/mysql-schema-tidb-mview-refresh-hist.md diff --git a/TOC.md b/TOC.md index 123b8a14f4f92..f5a159ddb7743 100644 --- a/TOC.md +++ b/TOC.md @@ -885,6 +885,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 index 21e563e327f13..2e2532a86f656 100644 --- a/materialized-views.md +++ b/materialized-views.md @@ -42,6 +42,18 @@ This section will describe how queries resolve to the stored result and any opti This section will describe cleanup behavior and any related objects. +## 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 - diff --git a/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md b/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md new file mode 100644 index 0000000000000..c861dcee0eca7 --- /dev/null +++ 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 new file mode 100644 index 0000000000000..8640cdd210e2c --- /dev/null +++ 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 new file mode 100644 index 0000000000000..440783e66b21c --- /dev/null +++ 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 index 3551c1d832346..b5f0d7e750a75 100644 --- 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 - \ No newline at end of file + From 7d0f0cd0f451328708ab95a92f19852d3bb75227 Mon Sep 17 00:00:00 2001 From: xufei Date: Mon, 31 Aug 2026 15:03:32 +0800 Subject: [PATCH 3/6] docs: add materialized view SQL syntax references --- TOC.md | 6 ++ materialized-views.md | 20 ++++- ...l-statement-alter-materialized-view-log.md | 61 +++++++++++++++ .../sql-statement-alter-materialized-view.md | 59 ++++++++++++++ ...-statement-create-materialized-view-log.md | 68 +++++++++++++++++ .../sql-statement-create-materialized-view.md | 76 +++++++++++++++++++ ...ql-statement-drop-materialized-view-log.md | 37 +++++++++ .../sql-statement-drop-materialized-view.md | 35 +++++++++ sql-statements/sql-statement-overview.md | 6 ++ 9 files changed, 364 insertions(+), 4 deletions(-) create mode 100644 sql-statements/sql-statement-alter-materialized-view-log.md create mode 100644 sql-statements/sql-statement-alter-materialized-view.md create mode 100644 sql-statements/sql-statement-create-materialized-view-log.md create mode 100644 sql-statements/sql-statement-create-materialized-view.md create mode 100644 sql-statements/sql-statement-drop-materialized-view-log.md create mode 100644 sql-statements/sql-statement-drop-materialized-view.md diff --git a/TOC.md b/TOC.md index f5a159ddb7743..a15264e3cf78a 100644 --- 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) diff --git a/materialized-views.md b/materialized-views.md index 2e2532a86f656..a66e655958bc5 100644 --- a/materialized-views.md +++ b/materialized-views.md @@ -22,25 +22,37 @@ Materialized views are intended for workloads that repeatedly read the same quer ## How it works -TiDB materialized views are backed by stored data derived from a query. The final design will define how TiDB creates, refreshes, and invalidates that data. +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 -This section will describe the supported creation flow, required clauses, and examples. +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). ### Refresh a materialized view -This section will describe refresh behavior, supported refresh modes, and operational guidance. +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). ### Query a materialized view This section will describe how queries resolve to the stored result and any optimizer behavior. +### 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 -This section will describe cleanup behavior and any related objects. +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 diff --git a/sql-statements/sql-statement-alter-materialized-view-log.md b/sql-statements/sql-statement-alter-materialized-view-log.md new file mode 100644 index 0000000000000..81a15f6f31011 --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view-log.md @@ -0,0 +1,61 @@ +--- +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 )? +``` + +## Examples + +Change the purge schedule: + +```sql +ALTER MATERIALIZED VIEW LOG ON t PURGE NEXT 300; +``` + +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) diff --git a/sql-statements/sql-statement-alter-materialized-view.md b/sql-statements/sql-statement-alter-materialized-view.md new file mode 100644 index 0000000000000..6d31338448015 --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view.md @@ -0,0 +1,59 @@ +--- +title: ALTER MATERIALIZED VIEW | TiDB SQL Statement Reference +summary: Learn how to use ALTER MATERIALIZED VIEW to modify a materialized view in TiDB. +--- + +# ALTER MATERIALIZED VIEW + +The `ALTER MATERIALIZED VIEW` statement modifies the comment, refresh schedule, or attributes of a materialized view. You can specify multiple actions in one statement by separating them with commas. + +## Synopsis + +```ebnf+diagram +AlterMaterializedViewStmt ::= + 'ALTER' 'MATERIALIZED' 'VIEW' TableName AlterMaterializedViewActionList + +AlterMaterializedViewActionList ::= + AlterMaterializedViewAction ( ',' AlterMaterializedViewAction )* + +AlterMaterializedViewAction ::= + 'COMMENT' EqOpt stringLit +| 'REFRESH' MViewStartWithOrNextOpt +| 'ATTRIBUTES' EqOpt stringLit + +MViewStartWithOrNextOpt ::= + MViewStartWithOrNext? + +MViewStartWithOrNext ::= + 'START' 'WITH' Expression 'NEXT' Expression +| 'NEXT' Expression +``` + +## Examples + +Change the comment of a materialized view: + +```sql +ALTER MATERIALIZED VIEW mv COMMENT = 'updated comment'; +``` + +Change the refresh schedule: + +```sql +ALTER MATERIALIZED VIEW mv REFRESH START WITH NOW() NEXT 300; +``` + +Change multiple properties in one statement: + +```sql +ALTER MATERIALIZED VIEW mv + COMMENT = 'updated comment', + REFRESH NEXT 300, + ATTRIBUTES = 'updated attributes'; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) +- [`DROP MATERIALIZED VIEW`](/sql-statements/sql-statement-drop-materialized-view.md) diff --git a/sql-statements/sql-statement-create-materialized-view-log.md b/sql-statements/sql-statement-create-materialized-view-log.md new file mode 100644 index 0000000000000..3efda04da2efb --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view-log.md @@ -0,0 +1,68 @@ +--- +title: CREATE MATERIALIZED VIEW LOG | TiDB SQL Statement Reference +summary: Learn how to use CREATE MATERIALIZED VIEW LOG to define a materialized view log in TiDB. +--- + +# CREATE MATERIALIZED VIEW LOG + +The `CREATE MATERIALIZED VIEW LOG` statement defines a materialized view log on a base table. You can specify table options, purge scheduling, and an accumulation alert threshold. + +## Synopsis + +```ebnf+diagram +CreateMaterializedViewLogStmt ::= + 'CREATE' 'MATERIALIZED' 'VIEW' 'LOG' 'ON' TableName '(' ColumnList ')' MLogCreateOptionListOpt MLogPurgeClauseOpt MLogAccumulationAlertClauseOpt + +MLogCreateOptionListOpt ::= + MLogCreateOptionList? + +MLogCreateOptionList ::= + MLogCreateOption+ + +MLogCreateOption ::= + 'SHARD_ROW_ID_BITS' EqOpt LengthNum +| 'PRE_SPLIT_REGIONS' EqOpt LengthNum + +MLogPurgeClauseOpt ::= + MLogPurgeClause? + +MLogPurgeClause ::= + 'PURGE' 'IMMEDIATE' +| 'PURGE' MLogStartWithOpt 'NEXT' Expression + +MLogStartWithOpt ::= + ( 'START' 'WITH' Expression )? + +MLogAccumulationAlertClauseOpt ::= + ( 'ALERT' 'ROWS' SignedNum )? +``` + +The clauses in `CREATE MATERIALIZED VIEW LOG` must appear in the following order: + +1. The base table name and column list. +2. Table options, if any. +3. The `PURGE` clause, if any. +4. The `ALERT ROWS` clause, if any. + +## Examples + +Create a materialized view log with immediate purging and an accumulation alert: + +```sql +CREATE MATERIALIZED VIEW LOG ON t (a, b) + PURGE IMMEDIATE + ALERT ROWS 10; +``` + +Create a materialized view log with scheduled purging: + +```sql +CREATE MATERIALIZED VIEW LOG ON t (a) + PURGE NEXT 300; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`ALTER MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-alter-materialized-view-log.md) +- [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md) diff --git a/sql-statements/sql-statement-create-materialized-view.md b/sql-statements/sql-statement-create-materialized-view.md new file mode 100644 index 0000000000000..457f8a39debb1 --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view.md @@ -0,0 +1,76 @@ +--- +title: CREATE MATERIALIZED VIEW | TiDB SQL Statement Reference +summary: Learn how to use CREATE MATERIALIZED VIEW to define a materialized view in TiDB. +--- + +# CREATE MATERIALIZED VIEW + +The `CREATE MATERIALIZED VIEW` statement defines a materialized view from a `SELECT` statement. You can specify table options, refresh scheduling, and attributes for the materialized view. + +## Synopsis + +```ebnf+diagram +CreateMaterializedViewStmt ::= + 'CREATE' 'MATERIALIZED' 'VIEW' TableName '(' ColumnList ')' MViewTableOptionListOpt MViewRefreshClauseOpt MViewAttributesOpt 'AS' CreateViewSelectOpt + +MViewTableOptionListOpt ::= + MViewTableOptionList? + +MViewTableOptionList ::= + MViewTableOption+ + +MViewTableOption ::= + 'COMMENT' EqOpt stringLit +| 'SHARD_ROW_ID_BITS' EqOpt LengthNum +| 'PRE_SPLIT_REGIONS' EqOpt LengthNum + +MViewRefreshClauseOpt ::= + MViewRefreshClause? + +MViewRefreshClause ::= + 'REFRESH' 'FAST' MViewStartWithOrNextOpt + +MViewStartWithOrNextOpt ::= + MViewStartWithOrNext? + +MViewStartWithOrNext ::= + 'START' 'WITH' Expression 'NEXT' Expression +| 'NEXT' Expression + +MViewAttributesOpt ::= + ( 'ATTRIBUTES' EqOpt stringLit )? +``` + +The clauses in `CREATE MATERIALIZED VIEW` must appear in the following order: + +1. The materialized view name and column list. +2. Table options, if any. +3. The `REFRESH` clause, if any. +4. The `ATTRIBUTES` clause, if any. +5. The `AS` clause and the `SELECT` statement. + +## Examples + +Create a materialized view with a query: + +```sql +CREATE MATERIALIZED VIEW mv (a) AS SELECT 1; +``` + +Create a materialized view with table options, refresh scheduling, and attributes: + +```sql +CREATE MATERIALIZED VIEW mv (a) + COMMENT = 'example' + SHARD_ROW_ID_BITS = 2 + PRE_SPLIT_REGIONS = 3 + REFRESH FAST NEXT 300 + ATTRIBUTES = 'example' + AS SELECT 1; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md) +- [`DROP MATERIALIZED VIEW`](/sql-statements/sql-statement-drop-materialized-view.md) diff --git a/sql-statements/sql-statement-drop-materialized-view-log.md b/sql-statements/sql-statement-drop-materialized-view-log.md new file mode 100644 index 0000000000000..5037455df47dd --- /dev/null +++ b/sql-statements/sql-statement-drop-materialized-view-log.md @@ -0,0 +1,37 @@ +--- +title: DROP MATERIALIZED VIEW LOG | TiDB SQL Statement Reference +summary: Learn how to use DROP MATERIALIZED VIEW LOG to remove a materialized view log in TiDB. +--- + +# DROP MATERIALIZED VIEW LOG + +The `DROP MATERIALIZED VIEW LOG` statement removes a materialized view log from a base table. + +## Synopsis + +```ebnf+diagram +DropMaterializedViewLogStmt ::= + 'DROP' 'MATERIALIZED' 'VIEW' 'LOG' IfExists 'ON' TableName + +IfExists ::= + ( 'IF' 'EXISTS' )? +``` + +## Examples + +Drop a materialized view log: + +```sql +DROP MATERIALIZED VIEW LOG ON t; +``` + +Drop a materialized view log only when it exists: + +```sql +DROP MATERIALIZED VIEW LOG IF EXISTS ON t; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md) diff --git a/sql-statements/sql-statement-drop-materialized-view.md b/sql-statements/sql-statement-drop-materialized-view.md new file mode 100644 index 0000000000000..f9a1bc16c28ec --- /dev/null +++ b/sql-statements/sql-statement-drop-materialized-view.md @@ -0,0 +1,35 @@ +--- +title: DROP MATERIALIZED VIEW | TiDB SQL Statement Reference +summary: Learn how to use DROP MATERIALIZED VIEW to remove a materialized view in TiDB. +--- + +# DROP MATERIALIZED VIEW + +The `DROP MATERIALIZED VIEW` statement removes a materialized view. + +## Synopsis + +```ebnf+diagram +DropMaterializedViewStmt ::= + 'DROP' 'MATERIALIZED' 'VIEW' TableName +| 'DROP' 'MATERIALIZED' 'VIEW' 'IF' 'EXISTS' TableName +``` + +## Examples + +Drop a materialized view: + +```sql +DROP MATERIALIZED VIEW mv; +``` + +Drop a materialized view only when it exists: + +```sql +DROP MATERIALIZED VIEW IF EXISTS mv; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) diff --git a/sql-statements/sql-statement-overview.md b/sql-statements/sql-statement-overview.md index e60dc29d34660..7c8662cca62b4 100644 --- a/sql-statements/sql-statement-overview.md +++ b/sql-statements/sql-statement-overview.md @@ -12,6 +12,8 @@ TiDB uses SQL statements that aim to follow ISO/IEC SQL standards, with extensio | SQL Statement | Description | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | [`ALTER DATABASE`](/sql-statements/sql-statement-alter-database.md) | Modifies a database. | +| [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md) | Modifies a materialized view. | +| [`ALTER MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-alter-materialized-view-log.md) | Modifies a materialized view log. | | [`ALTER SEQUENCE`](/sql-statements/sql-statement-alter-sequence.md) | Modifies a sequence. | | [`ALTER TABLE ... ADD COLUMN`](/sql-statements/sql-statement-add-column.md) | Adds a column to an existing table. | | [`ALTER TABLE ... ADD INDEX`](/sql-statements/sql-statement-add-index.md) | Adds an index to an existing table. | @@ -24,12 +26,16 @@ TiDB uses SQL statements that aim to follow ISO/IEC SQL standards, with extensio | [`ALTER TABLE`](/sql-statements/sql-statement-alter-table.md) | Changes a table definition. | | [`CREATE DATABASE`](/sql-statements/sql-statement-create-database.md) | Creates a new database. | | [`CREATE INDEX`](/sql-statements/sql-statement-create-index.md) | Creates a new index on a table. | +| [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) | Creates a materialized view. | +| [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md) | Creates a materialized view log. | | [`CREATE SEQUENCE`](/sql-statements/sql-statement-create-sequence.md) | Creates a new sequence object. | | [`CREATE TABLE LIKE`](/sql-statements/sql-statement-create-table-like.md) | Copies the definition of an existing table, without copying any data. | | [`CREATE TABLE`](/sql-statements/sql-statement-create-table.md) | Creates a new table. | | [`CREATE VIEW`](/sql-statements/sql-statement-create-view.md) | Creates a new view. | | [`DROP DATABASE`](/sql-statements/sql-statement-drop-database.md) | Drops an existing database. | | [`DROP INDEX`](/sql-statements/sql-statement-drop-index.md) | Drops an index from a table. | +| [`DROP MATERIALIZED VIEW`](/sql-statements/sql-statement-drop-materialized-view.md) | Drops a materialized view. | +| [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md) | Drops a materialized view log. | | [`DROP SEQUENCE`](/sql-statements/sql-statement-drop-sequence.md) | Drops a sequence object. | | [`DROP TABLE`](/sql-statements/sql-statement-drop-table.md) | Drops an existing table. | | [`DROP VIEW`](/sql-statements/sql-statement-drop-view.md) | Drops an existing view. | From 1aa9929fa3a166568b8098445e32a8939e6b7039 Mon Sep 17 00:00:00 2001 From: xufei Date: Tue, 1 Sep 2026 10:51:18 +0800 Subject: [PATCH 4/6] docs: fix materialized view schedule examples --- .../sql-statement-alter-materialized-view-log.md | 4 +++- sql-statements/sql-statement-alter-materialized-view.md | 7 +++++-- .../sql-statement-create-materialized-view-log.md | 4 +++- sql-statements/sql-statement-create-materialized-view.md | 4 +++- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/sql-statements/sql-statement-alter-materialized-view-log.md b/sql-statements/sql-statement-alter-materialized-view-log.md index 81a15f6f31011..60411517820bf 100644 --- a/sql-statements/sql-statement-alter-materialized-view-log.md +++ b/sql-statements/sql-statement-alter-materialized-view-log.md @@ -32,12 +32,14 @@ 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 300; +ALTER MATERIALIZED VIEW LOG ON t PURGE NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR); ``` Add columns to a materialized view log: diff --git a/sql-statements/sql-statement-alter-materialized-view.md b/sql-statements/sql-statement-alter-materialized-view.md index 6d31338448015..915a3485a0aea 100644 --- a/sql-statements/sql-statement-alter-materialized-view.md +++ b/sql-statements/sql-statement-alter-materialized-view.md @@ -29,6 +29,8 @@ MViewStartWithOrNext ::= | 'NEXT' Expression ``` +The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + ## Examples Change the comment of a materialized view: @@ -40,7 +42,8 @@ ALTER MATERIALIZED VIEW mv COMMENT = 'updated comment'; Change the refresh schedule: ```sql -ALTER MATERIALIZED VIEW mv REFRESH START WITH NOW() NEXT 300; +ALTER MATERIALIZED VIEW mv + REFRESH START WITH NOW() NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR); ``` Change multiple properties in one statement: @@ -48,7 +51,7 @@ Change multiple properties in one statement: ```sql ALTER MATERIALIZED VIEW mv COMMENT = 'updated comment', - REFRESH NEXT 300, + REFRESH NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR), ATTRIBUTES = 'updated attributes'; ``` diff --git a/sql-statements/sql-statement-create-materialized-view-log.md b/sql-statements/sql-statement-create-materialized-view-log.md index 3efda04da2efb..c75da444bcd3a 100644 --- a/sql-statements/sql-statement-create-materialized-view-log.md +++ b/sql-statements/sql-statement-create-materialized-view-log.md @@ -37,6 +37,8 @@ MLogAccumulationAlertClauseOpt ::= ( 'ALERT' 'ROWS' SignedNum )? ``` +The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + The clauses in `CREATE MATERIALIZED VIEW LOG` must appear in the following order: 1. The base table name and column list. @@ -58,7 +60,7 @@ Create a materialized view log with scheduled purging: ```sql CREATE MATERIALIZED VIEW LOG ON t (a) - PURGE NEXT 300; + PURGE NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR); ``` ## See also diff --git a/sql-statements/sql-statement-create-materialized-view.md b/sql-statements/sql-statement-create-materialized-view.md index 457f8a39debb1..646b5df9ecd6e 100644 --- a/sql-statements/sql-statement-create-materialized-view.md +++ b/sql-statements/sql-statement-create-materialized-view.md @@ -41,6 +41,8 @@ MViewAttributesOpt ::= ( 'ATTRIBUTES' EqOpt stringLit )? ``` +The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + The clauses in `CREATE MATERIALIZED VIEW` must appear in the following order: 1. The materialized view name and column list. @@ -64,7 +66,7 @@ CREATE MATERIALIZED VIEW mv (a) COMMENT = 'example' SHARD_ROW_ID_BITS = 2 PRE_SPLIT_REGIONS = 3 - REFRESH FAST NEXT 300 + REFRESH FAST NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR) ATTRIBUTES = 'example' AS SELECT 1; ``` From 80a2d33c8d35ac67e80149878724334b6f9a0233 Mon Sep 17 00:00:00 2001 From: xufei Date: Wed, 2 Sep 2026 11:53:29 +0800 Subject: [PATCH 5/6] docs: document materialized view system variables --- materialized-views.md | 14 +++++++++- system-variable-reference.md | 35 +++++++++++++++++++++++++ system-variables.md | 50 ++++++++++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 1 deletion(-) diff --git a/materialized-views.md b/materialized-views.md index a66e655958bc5..6307be6a7a2bd 100644 --- a/materialized-views.md +++ b/materialized-views.md @@ -17,7 +17,8 @@ Materialized views are intended for workloads that repeatedly read the same quer ## Prerequisites -- +- To create a materialized view or materialized view log, set [`tidb_materialized_view_enable`](/system-variables.md#tidb_materialized_view_enable) to `ON`. This variable is `OFF` by default. +- - ## How it works @@ -34,6 +35,17 @@ For the syntax of this statement, see [`CREATE MATERIALIZED VIEW`](/sql-statemen 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_mv_maintain_mem_quota`](/system-variables.md#tidb_mv_maintain_mem_quota): Sets the memory quota for the materialized view maintenance session. +- [`tidb_mv_maintain_isolation_read_engines`](/system-variables.md#tidb_mv_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). diff --git a/system-variable-reference.md b/system-variable-reference.md index 3590ce3e5c8fd..f662c007bee8e 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -2617,6 +2617,13 @@ Referenced in: - [System Variables](/system-variables.md#tidb_low_resolution_tso_update_interval-new-in-v800) - [TiDB 8.0.0 Release Notes](/releases/release-8.0.0.md) +### tidb_materialized_view_enable + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_materialized_view_enable) + ### tidb_max_auto_analyze_time Referenced in: @@ -2864,6 +2871,34 @@ Referenced in: - [TiDB 5.0.3 Release Notes](/releases/release-5.0.3.md) - [TiDB 4.0.14 Release Notes](/releases/release-4.0.14.md) +### tidb_mv_maintain_isolation_read_engines + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mv_maintain_isolation_read_engines) + +### tidb_mv_maintain_mem_quota + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mv_maintain_mem_quota) + +### tidb_mview_maintain_import_disk_quota + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mview_maintain_import_disk_quota) + +### tidb_mview_maintain_import_threads + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mview_maintain_import_threads) + ### tidb_non_prepared_plan_cache_size Referenced in: diff --git a/system-variables.md b/system-variables.md index bb505a4f3598b..948f22b38dcfe 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3870,6 +3870,15 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - This variable is used to set the update interval of the cached timestamp used in the low-precision TSO feature, in milliseconds. - This variable is only available when [`tidb_low_resolution_tso`](#tidb_low_resolution_tso) is enabled. +### tidb_materialized_view_enable + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Boolean +- Default value: `OFF` +- This variable controls whether to allow [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) and [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md) statements. + ### tidb_max_auto_analyze_time New in v6.1.0 - Scope: GLOBAL @@ -4362,6 +4371,47 @@ As shown in this diagram, when [`tidb_enable_paging`](#tidb_enable_paging-new-in > * [Connector/J](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`) > * PHP [mysqli](https://www.php.net/manual/en/mysqli.quickstart.multiple-statement.php) (`mysqli_multi_query`) +### tidb_mv_maintain_isolation_read_engines + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: String +- Default value: The value of [`isolation-read.engines`](/tidb-configuration-file.md#isolation-read) in the TiDB configuration. +- Possible values: Any combination of `tikv`, `tiflash`, and `tidb`. +- This variable specifies the storage engines that internal materialized view maintenance sessions can use to read data. + +### tidb_mv_maintain_mem_quota + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Integer +- Default value: `2147483648` (2 GiB) +- Range: `[-1, 9223372036854775807]` +- Unit: Bytes +- This variable sets the memory quota for internal materialized view maintenance sessions. When the value is greater than `0` but less than `128`, TiDB changes the value to `128` and returns a warning. + +### tidb_mview_maintain_import_disk_quota + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: String +- Default value: `""` +- This variable sets the disk quota passed to the `IMPORT INTO` operation used by the initial materialized view build. Set this variable to a positive size with a unit, such as `100GiB`. When the value is empty, TiDB does not pass an explicit disk quota to `IMPORT INTO`. + +### tidb_mview_maintain_import_threads + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Integer +- Default value: `0` +- Range: `[0, 256]` +- Unit: Threads +- This variable sets the thread count passed to the `IMPORT INTO` operation used by the initial materialized view build. A value of `0` means that TiDB does not pass an explicit thread count to `IMPORT INTO`. + ### tidb_nontransactional_ignore_error New in v6.1.0 - Scope: SESSION | GLOBAL From c3d873953935d31f06cfcf7b9111cc36bfb9161f Mon Sep 17 00:00:00 2001 From: xufei Date: Thu, 3 Sep 2026 11:24:36 +0800 Subject: [PATCH 6/6] docs: rename materialized view system variables --- materialized-views.md | 6 +++--- system-variable-reference.md | 12 ++++++------ system-variables.md | 6 +++--- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/materialized-views.md b/materialized-views.md index 6307be6a7a2bd..efa110b2fb5ab 100644 --- a/materialized-views.md +++ b/materialized-views.md @@ -17,7 +17,7 @@ Materialized views are intended for workloads that repeatedly read the same quer ## Prerequisites -- To create a materialized view or materialized view log, set [`tidb_materialized_view_enable`](/system-variables.md#tidb_materialized_view_enable) to `ON`. This variable is `OFF` by default. +- 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. - - @@ -39,8 +39,8 @@ For the syntax of this statement, see [`CREATE MATERIALIZED VIEW LOG`](/sql-stat 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_mv_maintain_mem_quota`](/system-variables.md#tidb_mv_maintain_mem_quota): Sets the memory quota for the materialized view maintenance session. -- [`tidb_mv_maintain_isolation_read_engines`](/system-variables.md#tidb_mv_maintain_isolation_read_engines): Specifies the storage engines that the maintenance session can use to read data. +- [`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. diff --git a/system-variable-reference.md b/system-variable-reference.md index f662c007bee8e..46d460e7ca5cd 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -2617,12 +2617,12 @@ Referenced in: - [System Variables](/system-variables.md#tidb_low_resolution_tso_update_interval-new-in-v800) - [TiDB 8.0.0 Release Notes](/releases/release-8.0.0.md) -### tidb_materialized_view_enable +### tidb_mview_enable Referenced in: - [Materialized Views](/materialized-views.md) -- [System Variables](/system-variables.md#tidb_materialized_view_enable) +- [System Variables](/system-variables.md#tidb_mview_enable) ### tidb_max_auto_analyze_time @@ -2871,19 +2871,19 @@ Referenced in: - [TiDB 5.0.3 Release Notes](/releases/release-5.0.3.md) - [TiDB 4.0.14 Release Notes](/releases/release-4.0.14.md) -### tidb_mv_maintain_isolation_read_engines +### tidb_mview_maintain_isolation_read_engines Referenced in: - [Materialized Views](/materialized-views.md) -- [System Variables](/system-variables.md#tidb_mv_maintain_isolation_read_engines) +- [System Variables](/system-variables.md#tidb_mview_maintain_isolation_read_engines) -### tidb_mv_maintain_mem_quota +### tidb_mview_maintain_mem_quota Referenced in: - [Materialized Views](/materialized-views.md) -- [System Variables](/system-variables.md#tidb_mv_maintain_mem_quota) +- [System Variables](/system-variables.md#tidb_mview_maintain_mem_quota) ### tidb_mview_maintain_import_disk_quota diff --git a/system-variables.md b/system-variables.md index 948f22b38dcfe..4d5e7e0cc1d51 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3870,7 +3870,7 @@ For a system upgraded to v5.0 from an earlier version, if you have not modified - This variable is used to set the update interval of the cached timestamp used in the low-precision TSO feature, in milliseconds. - This variable is only available when [`tidb_low_resolution_tso`](#tidb_low_resolution_tso) is enabled. -### tidb_materialized_view_enable +### tidb_mview_enable - Scope: SESSION | GLOBAL - Persists to cluster: Yes @@ -4371,7 +4371,7 @@ As shown in this diagram, when [`tidb_enable_paging`](#tidb_enable_paging-new-in > * [Connector/J](https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html) (`allowMultiQueries`) > * PHP [mysqli](https://www.php.net/manual/en/mysqli.quickstart.multiple-statement.php) (`mysqli_multi_query`) -### tidb_mv_maintain_isolation_read_engines +### tidb_mview_maintain_isolation_read_engines - Scope: SESSION | GLOBAL - Persists to cluster: Yes @@ -4381,7 +4381,7 @@ As shown in this diagram, when [`tidb_enable_paging`](#tidb_enable_paging-new-in - Possible values: Any combination of `tikv`, `tiflash`, and `tidb`. - This variable specifies the storage engines that internal materialized view maintenance sessions can use to read data. -### tidb_mv_maintain_mem_quota +### tidb_mview_maintain_mem_quota - Scope: SESSION | GLOBAL - Persists to cluster: Yes