raminqaf commented on code in PR #28287: URL: https://github.com/apache/flink/pull/28287#discussion_r3356069763
########## docs/content/docs/sql/materialized-table/statements.md: ########## @@ -260,6 +261,56 @@ The operation updates the materialized table similarly to [ALTER MATERIALIZED TA See [ALTER MATERIALIZED TABLE AS](#as-select_statement-1) for more details. +## Converting a Table to a Materialized Table + +`CREATE OR ALTER MATERIALIZED TABLE` can convert an existing regular table into a materialized table in place. The catalog object keeps its identity and underlying storage; only the table kind and the materialized-table metadata (query definition, freshness, refresh mode, and refresh status) change. After the conversion, a refresh job is launched just as it is for a newly created materialized table. + +This lets you adopt a materialized table on top of a table that already exists, without dropping and recreating it. + +**Enabling conversion** + +Conversion is disabled by default. To enable it, set the following option in the cluster configuration file `config.yaml`: + +```yaml +table.materialized-table.conversion-from-table.enabled: true +``` + +This is a cluster-wide setting: it must be set in the cluster configuration, and a session-level `SET` statement has no effect. When the option is disabled, `CREATE OR ALTER MATERIALIZED TABLE` against a regular table is rejected. + +**Watermark and primary key inheritance** + +When the conversion statement does not declare a `WATERMARK` or a `PRIMARY KEY`, the corresponding definition is inherited from the source table: + +- Omitting the watermark carries over the source table's watermark; declaring one replaces it. +- Omitting the primary key carries over the source table's primary key; declaring one replaces it. + +Inheritance is applied independently for each, regardless of whether a column list is provided. To drop an inherited watermark or primary key after conversion, run a follow-up `ALTER MATERIALIZED TABLE`. A source table that defines more than one watermark cannot be converted; declare an explicit watermark in the conversion statement instead. + +**Example** + +```sql +-- An existing regular table that you now want to maintain as a materialized table +CREATE TABLE user_spending ( + user_id BIGINT, + total_amount BIGINT +) WITH ( + 'connector' = '...' +); + +-- Convert it in place; from now on it is refreshed by the query +CREATE OR ALTER MATERIALIZED TABLE user_spending + AS SELECT + user_id, + SUM(amount) AS total_amount + FROM orders + GROUP BY user_id; +``` + +<span class="label label-danger">Note</span> +- The conversion is one-way and cannot be undone. To revert, drop the materialized table and recreate the original table. Review Comment: Extracted and added an example with ALTER MT SUSPEND -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
