diff --git a/TOC.md b/TOC.md index d440ed29e3a8d..e44661fc07c60 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) @@ -684,11 +686,15 @@ - [`CALIBRATE RESOURCE`](/sql-statements/sql-statement-calibrate-resource.md) - [`CANCEL DISTRIBUTION JOB`](/sql-statements/sql-statement-cancel-distribution-job.md) - [`CANCEL IMPORT JOB`](/sql-statements/sql-statement-cancel-import-job.md) + - [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md) + - [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md) - [`CANCEL TRAFFIC JOBS`](/sql-statements/sql-statement-cancel-traffic-jobs.md) - [`COMMIT`](/sql-statements/sql-statement-commit.md) - [`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 +711,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) @@ -733,8 +741,10 @@ - [`LOCK STATS`](/sql-statements/sql-statement-lock-stats.md) - [`[LOCK|UNLOCK] TABLES`](/sql-statements/sql-statement-lock-tables-and-unlock-tables.md) - [`PREPARE`](/sql-statements/sql-statement-prepare.md) + - [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-materialized-view-log.md) - [`QUERY WATCH`](/sql-statements/sql-statement-query-watch.md) - [`RECOVER TABLE`](/sql-statements/sql-statement-recover-table.md) + - [`REFRESH MATERIALIZED VIEW`](/sql-statements/sql-statement-refresh-materialized-view.md) - [`REFRESH STATS`](/sql-statements/sql-statement-refresh-stats.md) - [`RENAME USER`](/sql-statements/sql-statement-rename-user.md) - [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md) @@ -869,6 +879,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 +895,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 new file mode 100644 index 0000000000000..4609a625e89f4 --- /dev/null +++ b/materialized-views.md @@ -0,0 +1,134 @@ +--- +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. +- +- + +## 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 + +Use [`REFRESH MATERIALIZED VIEW`](/sql-statements/sql-statement-refresh-materialized-view.md) to refresh a materialized view manually. You can use `FAST` refresh to apply changes from materialized view logs, or `COMPLETE` refresh to recompute the complete result of the materialized view query. + +`COMPLETE` refresh requires one of the following methods. Although `DELTA APPLY` only changes rows that differ, it is a complete refresh method because TiDB recomputes the full materialized view query before applying the differences. + +| Method | How it refreshes the materialized view | Transaction behavior | +| --- | --- | --- | +| `COMPLETE IN PLACE` | Deletes all existing rows from the materialized view and inserts the complete recomputed result. | Runs the delete and insert operations in one transaction. | +| `COMPLETE DELTA APPLY` | Recomputes the complete result, compares it with the current materialized view by its grouping keys, and applies only inserted, deleted, and changed rows. The materialized view must have an explicit `PRIMARY KEY` or `UNIQUE KEY` so that TiDB can uniquely locate existing rows. | Runs the comparison and row changes in one transaction. | +| `COMPLETE OUT OF PLACE` | Creates a shadow table, builds the complete recomputed result in that table, and then switches the materialized view to the replacement table. | Does not run as a single transaction. The existing materialized view remains available while TiDB builds the shadow table. If the build fails before cutover, the existing materialized view is not changed. | + +Use `DRY RUN` to view the planned refresh steps without refreshing the materialized view. Use `WITH PROFILE` to execute the refresh and return step-level runtime information. To cancel a running refresh, use [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md) with the job ID in [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.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). + +### Purge a materialized view log + +To manually purge a materialized view log, use [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-materialized-view-log.md). To cancel a purge job, use [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md). + +#### Purge throttling + +TiDB uses adaptive throttling to spread materialized view log purge work across an available time window. Before deleting rows, TiDB counts the rows eligible for purge and calculates a purge deadline. For a scheduled purge, the deadline does not extend beyond the next scheduled run. For a manually triggered purge, TiDB uses an internal bounded time window, shortened when an earlier next scheduled run exists. + +TiDB uses the following calculation to determine the target delete rate: + +```text +delete time budget = time until deadline * tidb_mlog_purge_rate_budget_ratio +target delete rate = max(pending rows / delete time budget, tidb_mlog_purge_min_rate) +``` + +The target delete rate is measured in rows per second. TiDB deletes rows in batches and waits between batches when deletion has progressed ahead of the target rate. This keeps the average delete rate close to the calculated target. + +For example, assume that 120,000 rows are pending, there are 60 seconds until the deadline, `tidb_mlog_purge_rate_budget_ratio` is `0.5`, and `tidb_mlog_purge_min_rate` is `2000`. TiDB uses 30 seconds as the delete time budget and sets the target delete rate to 4,000 rows per second. If only 20,000 rows are pending under the same settings, the calculated rate is about 667 rows per second, so TiDB uses the 2,000 rows-per-second minimum target instead. + +> **Note:** +> +> Adaptive throttling is best effort. TiDB uses a preliminary TiFlash query to count pending rows and calculate the plan. If TiDB cannot obtain the pending-row statistics, throttling configuration, or purge deadline, it continues with normal unthrottled batched deletion instead of failing the purge. + +You can configure materialized view log purge jobs using the following system variables: + +- [`tidb_mlog_purge_batch_size`](/system-variables.md#tidb_mlog_purge_batch_size): Sets the maximum number of rows deleted in each purge batch. +- [`tidb_mlog_purge_min_rate`](/system-variables.md#tidb_mlog_purge_min_rate): Sets the lower bound of the adaptive purge target delete rate. +- [`tidb_mlog_purge_rate_budget_ratio`](/system-variables.md#tidb_mlog_purge_rate_budget_ratio): Sets the fraction of the available time before the purge deadline that TiDB targets for deletion. +- [`tidb_mlog_purge_delete_tiflash_threads`](/system-variables.md#tidb_mlog_purge_delete_tiflash_threads): Sets the TiFlash thread count used by purge `DELETE` statements. +- [`tidb_mlog_log_slow_purge`](/system-variables.md#tidb_mlog_log_slow_purge): Controls whether TiDB records purge statements in the slow query log. + +### 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 + +- +- + +## Compatibility + +- +- + +## 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 new file mode 100644 index 0000000000000..0399ff2227d40 --- /dev/null +++ b/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md @@ -0,0 +1,53 @@ +--- +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. + +Use the value in the `PURGE_JOB_ID` column with [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md) to cancel a purge job. + +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) +- [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-materialized-view-log.md) +- [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.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..34d5a5f2c2653 --- /dev/null +++ b/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md @@ -0,0 +1,53 @@ +--- +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) +- [`REFRESH MATERIALIZED VIEW`](/sql-statements/sql-statement-refresh-materialized-view.md) +- [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.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 + 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..a408eadf99329 --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view-log.md @@ -0,0 +1,64 @@ +--- +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) +- [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-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..637abf88484d3 --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view.md @@ -0,0 +1,66 @@ +--- +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 +``` + +The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + +> **Important:** +> +> TiDB evaluates `START WITH` and `NEXT` expressions in UTC. TiDB also interprets their resulting values in UTC when calculating the schedule time, regardless of the current session `time_zone` setting. + +## 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 DATE_ADD(NOW(), INTERVAL 1 HOUR); +``` + +Change multiple properties in one statement: + +```sql +ALTER MATERIALIZED VIEW mv + COMMENT = 'updated comment', + REFRESH NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR), + 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-cancel-materialized-view-log-purge-job.md b/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md new file mode 100644 index 0000000000000..6c018773c2794 --- /dev/null +++ b/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md @@ -0,0 +1,29 @@ +--- +title: CANCEL MATERIALIZED VIEW LOG PURGE JOB | TiDB SQL Statement Reference +summary: Learn how to use CANCEL MATERIALIZED VIEW LOG PURGE JOB to cancel a materialized view log purge job in TiDB. +--- + +# CANCEL MATERIALIZED VIEW LOG PURGE JOB + +The `CANCEL MATERIALIZED VIEW LOG PURGE JOB` statement cancels a materialized view log purge job by its ID. + +## Synopsis + +```ebnf+diagram +CancelMaterializedViewJobStmt ::= + 'CANCEL' 'MATERIALIZED' 'VIEW' 'LOG' 'PURGE' 'JOB' Int64Num +``` + +## Examples + +Cancel the materialized view log purge job with ID `1`: + +```sql +CANCEL MATERIALIZED VIEW LOG PURGE JOB 1; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-materialized-view-log.md) +- [`mysql.tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md) diff --git a/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md b/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md new file mode 100644 index 0000000000000..087c525caedeb --- /dev/null +++ b/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md @@ -0,0 +1,35 @@ +--- +title: CANCEL MATERIALIZED VIEW REFRESH JOB | TiDB SQL Statement Reference +summary: Learn how to cancel a running materialized view refresh job in TiDB. +--- + +# CANCEL MATERIALIZED VIEW REFRESH JOB + +The `CANCEL MATERIALIZED VIEW REFRESH JOB` statement requests cancellation of a running materialized view refresh job. + +## Required privileges + +To cancel a refresh job, you need the `OPERATE VIEW` privilege on the materialized view associated with the job. + +## Synopsis + +```ebnf+diagram +CancelMaterializedViewJobStmt ::= + 'CANCEL' 'MATERIALIZED' 'VIEW' 'REFRESH' 'JOB' Int64Num +``` + +The job must be running. To find a refresh job ID, query [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md). + +## Examples + +Cancel the materialized view refresh job with ID `1`: + +```sql +CANCEL MATERIALIZED VIEW REFRESH JOB 1; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`REFRESH MATERIALIZED VIEW`](/sql-statements/sql-statement-refresh-materialized-view.md) +- [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.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..0a8156b967593 --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view-log.md @@ -0,0 +1,71 @@ +--- +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 `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. +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 DATE_ADD(NOW(), INTERVAL 1 HOUR); +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`ALTER MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-alter-materialized-view-log.md) +- [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-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..3f1dd64a64c33 --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view.md @@ -0,0 +1,82 @@ +--- +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 `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + +> **Important:** +> +> TiDB evaluates `START WITH` and `NEXT` expressions in UTC. TiDB also interprets their resulting values in UTC when calculating the schedule time, regardless of the current session `time_zone` setting. + +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 DATE_ADD(NOW(), INTERVAL 1 HOUR) + 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..8f12493a89e99 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,15 +26,21 @@ 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. | +| [`PURGE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-purge-materialized-view-log.md) | Manually purges a materialized view log. | +| [`REFRESH MATERIALIZED VIEW`](/sql-statements/sql-statement-refresh-materialized-view.md) | Manually refreshes a materialized view. | | [`RENAME TABLE`](/sql-statements/sql-statement-rename-table.md) | Renames a table. | | [`SHOW COLUMNS FROM`](/sql-statements/sql-statement-show-columns-from.md) | Shows the columns from a table. | | [`SHOW CREATE DATABASE`](/sql-statements/sql-statement-show-create-database.md) | Shows the CREATE statement for a database. | @@ -95,6 +103,8 @@ TiDB uses SQL statements that aim to follow ISO/IEC SQL standards, with extensio | [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) | Resumes DDL operations. | | [`ADMIN SHOW DDL [JOBS\|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) | Shows DDL jobs or job queries. | | [`ADMIN`](/sql-statements/sql-statement-admin.md) | Performs various administrative tasks. | +| [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md) | Cancels a materialized view refresh job. | +| [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md) | Cancels a materialized view log purge job. | | [`FLUSH TABLES`](/sql-statements/sql-statement-flush-tables.md) | Included for [MySQL compatibility](/mysql-compatibility.md). It has no effective usage in TiDB. | | [`SET `](/sql-statements/sql-statement-set-variable.md) | Modifies a system variable or user variable. | | [`SET [NAMES\|CHARACTER SET]`](/sql-statements/sql-statement-set-names.md) | Set a character set and collation. | @@ -116,6 +126,8 @@ TiDB uses SQL statements that aim to follow ISO/IEC SQL standards, with extensio | [`ADMIN RESUME DDL`](/sql-statements/sql-statement-admin-resume-ddl.md) | Resumes DDL operations. | | [`ADMIN SHOW DDL [JOBS\|JOB QUERIES]`](/sql-statements/sql-statement-admin-show-ddl.md) | Shows DDL jobs or job queries. | | [`ADMIN`](/sql-statements/sql-statement-admin.md) | Performs various administrative tasks. | +| [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md) | Cancels a materialized view refresh job. | +| [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md) | Cancels a materialized view log purge job. | | [`FLUSH TABLES`](/sql-statements/sql-statement-flush-tables.md) | Included for [MySQL compatibility](/mysql-compatibility.md). It has no effective usage in TiDB. | | [`SET `](/sql-statements/sql-statement-set-variable.md) | Modifies a system variable or user variable. | | [`SET [NAMES\|CHARACTER SET]`](/sql-statements/sql-statement-set-names.md) | Set a character set and collation. | diff --git a/sql-statements/sql-statement-purge-materialized-view-log.md b/sql-statements/sql-statement-purge-materialized-view-log.md new file mode 100644 index 0000000000000..ecd72440f4049 --- /dev/null +++ b/sql-statements/sql-statement-purge-materialized-view-log.md @@ -0,0 +1,30 @@ +--- +title: PURGE MATERIALIZED VIEW LOG | TiDB SQL Statement Reference +summary: Learn how to use PURGE MATERIALIZED VIEW LOG to manually purge a materialized view log in TiDB. +--- + +# PURGE MATERIALIZED VIEW LOG + +The `PURGE MATERIALIZED VIEW LOG` statement manually purges the materialized view log on a base table. + +## Synopsis + +```ebnf+diagram +PurgeMaterializedViewLogStmt ::= + 'PURGE' 'MATERIALIZED' 'VIEW' 'LOG' 'ON' TableName +``` + +## Examples + +Purge the materialized view log on `t`: + +```sql +PURGE MATERIALIZED VIEW LOG ON t; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md) +- [`CANCEL MATERIALIZED VIEW LOG PURGE JOB`](/sql-statements/sql-statement-cancel-materialized-view-log-purge-job.md) +- [`mysql.tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md) diff --git a/sql-statements/sql-statement-refresh-materialized-view.md b/sql-statements/sql-statement-refresh-materialized-view.md new file mode 100644 index 0000000000000..bd54590882c93 --- /dev/null +++ b/sql-statements/sql-statement-refresh-materialized-view.md @@ -0,0 +1,118 @@ +--- +title: REFRESH MATERIALIZED VIEW | TiDB SQL Statement Reference +summary: Learn how to manually refresh a materialized view in TiDB with fast or complete refresh methods. +--- + +# REFRESH MATERIALIZED VIEW + +The `REFRESH MATERIALIZED VIEW` statement manually refreshes a materialized view. Use `FAST` to apply changes from materialized view logs, or use `COMPLETE` to recompute the materialized view query. + +## Required privileges + +To refresh a materialized view, you need the `OPERATE VIEW` privilege on the materialized view and the `SELECT` privilege on its base tables. `DRY RUN` and `WITH PROFILE` also require the `SHOW VIEW` privilege on the materialized view. + +## Synopsis + +```ebnf+diagram +RefreshMaterializedViewStmt ::= + 'REFRESH' 'MATERIALIZED' 'VIEW' TableName RefreshWithAsyncModeOpt ( FastRefresh | CompleteRefresh ) RefreshObserveOpt + +RefreshWithAsyncModeOpt ::= + ( 'WITH' 'ASYNC' 'MODE' )? + +FastRefresh ::= + 'FAST' AsOfClauseOpt + +AsOfClauseOpt ::= + ( 'AS' 'OF' 'TIMESTAMP' Expression )? + +CompleteRefresh ::= + 'COMPLETE' ( 'IN' 'PLACE' | 'DELTA' 'APPLY' | 'OUT' 'OF' 'PLACE' ) + +RefreshObserveOpt ::= + ( 'DRY' 'RUN' | 'WITH' 'PROFILE' )? +``` + +The clauses must appear in the order shown in the syntax. `AS OF TIMESTAMP` is supported only with `FAST`. `DRY RUN` and `WITH PROFILE` are mutually exclusive. + +> **Note:** +> +> `WITH ASYNC MODE` is accepted by the parser but is not supported for materialized view refreshes yet. + +## Refresh methods + +### FAST + +`FAST` refresh applies changes recorded in materialized view logs since the last successful refresh. You can use `AS OF TIMESTAMP` to bound the refresh at a specified timestamp. + +### COMPLETE IN PLACE + +`COMPLETE IN PLACE` recomputes the materialized view query by deleting all current rows and inserting the complete result. TiDB performs the delete and insert operations in one transaction. + +### COMPLETE DELTA APPLY + +`COMPLETE DELTA APPLY` recomputes the complete materialized view query. TiDB compares the recomputed result with the current materialized view by its grouping keys and applies only the rows that need to be inserted, deleted, or updated. It is not a fast refresh because it still computes the full query result. + +`COMPLETE DELTA APPLY` requires the materialized view to have an explicit `PRIMARY KEY` or `UNIQUE KEY` so that TiDB can uniquely locate existing rows. The materialized view query must have grouping keys so that TiDB can compare the current and recomputed results. The comparison and the resulting row changes run in one transaction. + +### COMPLETE OUT OF PLACE + +`COMPLETE OUT OF PLACE` creates a shadow table, loads the complete recomputed result into it, and then switches the materialized view to the replacement table. The original materialized view remains available until the cutover. + +This method is non-transactional: building the shadow table and switching to it are not one transaction. If the shadow-table build fails before cutover, TiDB keeps the original materialized view unchanged. + +## Observe a refresh + +Use `DRY RUN` to build and return the planned refresh steps without executing the refresh. Use `WITH PROFILE` to execute the refresh and return the execution time and plan information for each refresh step. + +## Examples + +Refresh a materialized view using materialized view logs: + +```sql +REFRESH MATERIALIZED VIEW mv FAST; +``` + +Refresh a materialized view up to a specified timestamp: + +```sql +REFRESH MATERIALIZED VIEW mv FAST AS OF TIMESTAMP '2026-09-24 12:00:00'; +``` + +Refresh a materialized view by replacing all existing rows: + +```sql +REFRESH MATERIALIZED VIEW mv COMPLETE IN PLACE; +``` + +Refresh a materialized view by applying only the differences from the complete recomputed result: + +```sql +REFRESH MATERIALIZED VIEW mv COMPLETE DELTA APPLY; +``` + +Refresh a materialized view by building a replacement table: + +```sql +REFRESH MATERIALIZED VIEW mv COMPLETE OUT OF PLACE; +``` + +View the plan for a refresh without executing it: + +```sql +REFRESH MATERIALIZED VIEW mv COMPLETE DELTA APPLY DRY RUN; +``` + +Execute a refresh and return profile information: + +```sql +REFRESH MATERIALIZED VIEW mv COMPLETE OUT OF PLACE WITH PROFILE; +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) +- [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md) +- [`CANCEL MATERIALIZED VIEW REFRESH JOB`](/sql-statements/sql-statement-cancel-materialized-view-refresh-job.md) +- [`mysql.tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md) diff --git a/system-variable-reference.md b/system-variable-reference.md index 348bcf3da04a4..53677d5828d40 100644 --- a/system-variable-reference.md +++ b/system-variable-reference.md @@ -2617,6 +2617,48 @@ 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_mlog_log_slow_purge + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mlog_log_slow_purge) + +### tidb_mlog_purge_batch_size + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mlog_purge_batch_size) + +### tidb_mlog_purge_delete_tiflash_threads + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mlog_purge_delete_tiflash_threads) + +### tidb_mlog_purge_min_rate + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mlog_purge_min_rate) + +### tidb_mlog_purge_rate_budget_ratio + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mlog_purge_rate_budget_ratio) + +### tidb_mview_enable + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mview_enable) + ### tidb_max_auto_analyze_time Referenced in: @@ -2864,6 +2906,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_mview_maintain_isolation_read_engines + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mview_maintain_isolation_read_engines) + +### tidb_mview_maintain_mem_quota + +Referenced in: + +- [Materialized Views](/materialized-views.md) +- [System Variables](/system-variables.md#tidb_mview_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 2b5ae3cdd1852..cef588a90895f 100644 --- a/system-variables.md +++ b/system-variables.md @@ -3877,6 +3877,69 @@ 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_mlog_log_slow_purge + +- Scope: 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 TiDB records materialized view log purge statements in the slow query log. + +### tidb_mlog_purge_batch_size + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Integer +- Default value: `10000` +- Range: `[1, 1000000]` +- Unit: Rows +- This variable sets the maximum number of materialized view log rows deleted in each batch of a `PURGE MATERIALIZED VIEW LOG` statement. + +### tidb_mlog_purge_delete_tiflash_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 TiFlash thread count used by the `DELETE` statements of a materialized view log purge. A value of `0` uses the current value of [`tidb_max_tiflash_threads`](/system-variables.md#tidb_max_tiflash_threads-new-in-v610). + +### tidb_mlog_purge_min_rate + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Integer +- Default value: `2000` +- Range: `[1, 2147483647]` +- Unit: Rows per second +- This variable sets the lower bound of the target delete rate for adaptive materialized view log purge throttling. TiDB calculates the target rate from the number of pending rows and the configured delete time budget. If the calculated rate is lower than this value, TiDB uses this value as the target rate instead. +- Increasing this value can cause a purge with a small backlog to delete rows faster and consume more resources. Decreasing this value does not reduce the target rate when the current backlog needs a higher rate to meet the configured delete time budget. For the calculation, see [Purge throttling](/materialized-views.md#purge-throttling). + +### tidb_mlog_purge_rate_budget_ratio + +- Scope: SESSION | GLOBAL +- Persists to cluster: Yes +- Applies to hint [SET_VAR](/optimizer-hints.md#set_varvar_namevar_value): No +- Type: Float +- Default value: `0.5` +- Range: `(0, 1]` +- This variable sets the fraction of the time before the purge deadline that TiDB uses as the initial delete time budget. For example, the default value `0.5` gives a purge half of the available time to delete its pending rows. +- A smaller value shortens the delete time budget, which increases the calculated target delete rate and can increase resource usage. A larger value gives TiDB more time to delete rows, which lowers the calculated target rate. For the calculation, see [Purge throttling](/materialized-views.md#purge-throttling). + +### tidb_mview_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 @@ -4369,6 +4432,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_mview_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_mview_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 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)