diff --git a/TOC.md b/TOC.md index d440ed29e3a8d..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) @@ -869,6 +875,7 @@ - [Non-Transactional DML Statements](/non-transactional-dml.md) - [Pipelined DML](/pipelined-dml.md) - [Views](/views.md) + - [Materialized Views](/materialized-views.md) - [Partitioning](/partitioned-table.md) - [Temporary Tables](/temporary-tables.md) - [Cached Tables](/cached-tables.md) @@ -884,6 +891,9 @@ - `mysql` Schema - [Overview](/mysql-schema/mysql-schema.md) - [`tidb_mdl_view`](/mysql-schema/mysql-schema-tidb-mdl-view.md) + - [`tidb_mlog_purge_hist`](/mysql-schema/mysql-schema-tidb-mlog-purge-hist.md) + - [`tidb_mview_refresh_alert`](/mysql-schema/mysql-schema-tidb-mview-refresh-alert.md) + - [`tidb_mview_refresh_hist`](/mysql-schema/mysql-schema-tidb-mview-refresh-hist.md) - [`user`](/mysql-schema/mysql-schema-user.md) - INFORMATION_SCHEMA - [Overview](/information-schema/information-schema.md) diff --git a/materialized-views.md b/materialized-views.md new file mode 100644 index 0000000000000..efa110b2fb5ab --- /dev/null +++ b/materialized-views.md @@ -0,0 +1,93 @@ +--- +title: Materialized Views +summary: Learn what materialized views are in TiDB, when to use them, and where the creation, refresh, limitation, and compatibility details belong. +--- + +# Materialized Views + +TiDB materialized views store the result of a query in a reusable object so you can avoid recomputing the same result repeatedly. This page collects the core concept, usage flow, and limitations for the feature. + +## Usage scenarios + +Materialized views are intended for workloads that repeatedly read the same query result. + +- Reuse expensive analytical query results. +- Reduce repeated computation for read-heavy workloads. +- Provide a stable result set for downstream consumers that do not need to rerun the base query each time. + +## Prerequisites + +- To create a materialized view or materialized view log, set [`tidb_mview_enable`](/system-variables.md#tidb_mview_enable) to `ON`. This variable is `OFF` by default. +- +- + +## How it works + +TiDB materialized views are backed by stored data derived from a query. This page covers how to create, refresh, query, and manage materialized views. + +## Create and manage materialized views + +### Create a materialized view + +For the syntax of this statement, see [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md). + +### Create a materialized view log + +For the syntax of this statement, see [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md). + +### Control materialized view maintenance + +TiDB uses an internal maintenance session to build a materialized view. You can control the resources and storage engines used by this session with the following system variables: + +- [`tidb_mview_maintain_mem_quota`](/system-variables.md#tidb_mview_maintain_mem_quota): Sets the memory quota for the materialized view maintenance session. +- [`tidb_mview_maintain_isolation_read_engines`](/system-variables.md#tidb_mview_maintain_isolation_read_engines): Specifies the storage engines that the maintenance session can use to read data. +- [`tidb_mview_maintain_import_threads`](/system-variables.md#tidb_mview_maintain_import_threads): Sets the thread count for the `IMPORT INTO` operation used by the initial materialized view build. A value of `0` means that TiDB does not set an explicit thread count. +- [`tidb_mview_maintain_import_disk_quota`](/system-variables.md#tidb_mview_maintain_import_disk_quota): Sets the disk quota for the `IMPORT INTO` operation used by the initial materialized view build. An empty value means that TiDB does not set an explicit disk quota. + +When you submit `CREATE MATERIALIZED VIEW`, TiDB records the current values of these variables in the DDL job and uses them for the initial build. + +### Refresh a materialized view + +This section will describe refresh behavior, supported refresh modes, and operational guidance. The `REFRESH` clause syntax is documented in [`CREATE MATERIALIZED VIEW`](/sql-statements/sql-statement-create-materialized-view.md) and [`ALTER MATERIALIZED VIEW`](/sql-statements/sql-statement-alter-materialized-view.md). + +### 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 + +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..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 + 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..60411517820bf --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view-log.md @@ -0,0 +1,63 @@ +--- +title: ALTER MATERIALIZED VIEW LOG | TiDB SQL Statement Reference +summary: Learn how to use ALTER MATERIALIZED VIEW LOG to modify a materialized view log in TiDB. +--- + +# ALTER MATERIALIZED VIEW LOG + +The `ALTER MATERIALIZED VIEW LOG` statement changes the purge configuration or adds columns to a materialized view log. You can specify multiple actions in one statement by separating them with commas. + +## Synopsis + +```ebnf+diagram +AlterMaterializedViewLogStmt ::= + 'ALTER' 'MATERIALIZED' 'VIEW' 'LOG' 'ON' TableName AlterMaterializedViewLogActionList + +AlterMaterializedViewLogActionList ::= + AlterMaterializedViewLogAction ( ',' AlterMaterializedViewLogAction )* + +AlterMaterializedViewLogAction ::= + AlterMLogPurgeClause +| 'ADD' ColumnKeywordOpt '(' ColumnList ')' + +AlterMLogPurgeClause ::= + MLogPurgeClause +| 'PURGE' + +MLogPurgeClause ::= + 'PURGE' 'IMMEDIATE' +| 'PURGE' MLogStartWithOpt 'NEXT' Expression + +MLogStartWithOpt ::= + ( 'START' 'WITH' Expression )? +``` + +The `START WITH` and `NEXT` expressions must return `DATETIME` or `TIMESTAMP` values. + +## Examples + +Change the purge schedule: + +```sql +ALTER MATERIALIZED VIEW LOG ON t PURGE NEXT DATE_ADD(NOW(), INTERVAL 1 HOUR); +``` + +Add columns to a materialized view log: + +```sql +ALTER MATERIALIZED VIEW LOG ON t ADD COLUMN (b, c); +``` + +Specify multiple actions in one statement: + +```sql +ALTER MATERIALIZED VIEW LOG ON t + PURGE, + ADD COLUMN (b, c); +``` + +## See also + +- [Materialized Views](/materialized-views.md) +- [`CREATE MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-create-materialized-view-log.md) +- [`DROP MATERIALIZED VIEW LOG`](/sql-statements/sql-statement-drop-materialized-view-log.md) 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..915a3485a0aea --- /dev/null +++ b/sql-statements/sql-statement-alter-materialized-view.md @@ -0,0 +1,62 @@ +--- +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. + +## 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-create-materialized-view-log.md b/sql-statements/sql-statement-create-materialized-view-log.md new file mode 100644 index 0000000000000..c75da444bcd3a --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view-log.md @@ -0,0 +1,70 @@ +--- +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) +- [`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..646b5df9ecd6e --- /dev/null +++ b/sql-statements/sql-statement-create-materialized-view.md @@ -0,0 +1,78 @@ +--- +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. + +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..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. | diff --git a/system-variable-reference.md b/system-variable-reference.md index 3590ce3e5c8fd..46d460e7ca5cd 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_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 +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_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 bb505a4f3598b..4d5e7e0cc1d51 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_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 @@ -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_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)