This is an automated email from the ASF dual-hosted git repository.
snuyanzin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/master by this push:
new 34246de9a26 [FLINK-38861][docs] Update documentation to cover new
`CREATE`/`ALTER` operations for `MATERIALIZED TABLE`s
34246de9a26 is described below
commit 34246de9a26776e06cd55482ac9336ff429b6efb
Author: Sergey Nuyanzin <[email protected]>
AuthorDate: Tue Mar 31 12:41:32 2026 +0200
[FLINK-38861][docs] Update documentation to cover new `CREATE`/`ALTER`
operations for `MATERIALIZED TABLE`s
---
.../docs/sql/materialized-table/statements.md | 126 +++++++++++++++++++-
docs/content.zh/docs/sql/reference/ddl/alter.md | 4 +
docs/content.zh/docs/sql/reference/ddl/create.md | 8 +-
docs/content.zh/docs/sql/reference/ddl/drop.md | 4 +
.../docs/sql/materialized-table/statements.md | 128 ++++++++++++++++++++-
docs/content/docs/sql/reference/ddl/alter.md | 4 +
docs/content/docs/sql/reference/ddl/create.md | 4 +
docs/content/docs/sql/reference/ddl/drop.md | 4 +
8 files changed, 270 insertions(+), 12 deletions(-)
diff --git a/docs/content.zh/docs/sql/materialized-table/statements.md
b/docs/content.zh/docs/sql/materialized-table/statements.md
index eb829d9e694..d411a1d5ffe 100644
--- a/docs/content.zh/docs/sql/materialized-table/statements.md
+++ b/docs/content.zh/docs/sql/materialized-table/statements.md
@@ -33,7 +33,7 @@ Flink SQL 目前支持以下物化表操作：
# CREATE [OR ALTER] MATERIALIZED TABLE
-```
+```text
CREATE [OR ALTER] MATERIALIZED TABLE [catalog_name.][db_name.]table_name
[(
@@ -44,6 +44,8 @@ CREATE [OR ALTER] MATERIALIZED TABLE
[catalog_name.][db_name.]table_name
[COMMENT table_comment]
+[ <distribution> ]
+
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
[WITH (key1=val1, key2=val2, ...)]
@@ -71,6 +73,12 @@ AS <select_statement>
<watermark_definition>:
WATERMARK FOR rowtime_column_name AS watermark_strategy_expression
+
+<distribution>:
+{
+ DISTRIBUTED BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
+ | DISTRIBUTED INTO n BUCKETS
+}
```
## PRIMARY KEY
@@ -383,15 +391,123 @@ CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
# ALTER MATERIALIZED TABLE
-```
+```text
ALTER MATERIALIZED TABLE [catalog_name.][db_name.]table_name
- SUSPEND | RESUME [WITH (key1=val1, key2=val2, ...)] |
- REFRESH [PARTITION partition_spec] |
- AS <select_statement>
+ ADD { <schema_component> | (<schema_component> [, ...]) | <distribution> }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) |
<distribution> }
+ | DROP {column_name | (column_name, column_name, ...) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK | DISTRIBUTION }
+ | SUSPEND | RESUME [WITH (key1=val1, key2=val2, ...)]
+ | REFRESH [PARTITION partition_spec] |
+ | AS <select_statement>
+<schema_component>:
+ { <column_component> | <constraint_component> | <watermark_component> }
+
+<column_component>:
+ column_name <column_definition> [FIRST | AFTER column_name]
+
+<constraint_component>:
+ [CONSTRAINT constraint_name] PRIMARY KEY (column_name, ...) NOT ENFORCED
+
+<watermark_component>:
+ WATERMARK FOR rowtime_column_name AS watermark_strategy_expression
+
+<column_definition>:
+ { <physical_column_definition> | <metadata_column_definition> |
<computed_column_definition> } [COMMENT column_comment]
+
+<physical_column_definition>:
+ column_type
+
+<metadata_column_definition>:
+ column_type METADATA [ FROM metadata_key ] [ VIRTUAL ]
+
+<computed_column_definition>:
+ AS computed_column_expression
+
+<distribution>:
+{
+ DISTRIBUTED BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
+ | DISTRIBUTED INTO n BUCKETS
+}
```
`ALTER MATERIALIZED TABLE`
用于管理物化表。用户可以使用此命令暂停和恢复物化表的刷新管道，并手动触发数据刷新，以及修改物化表的查询定义。
+## ADD
+Use `ADD` clause to add [columns]({{< ref "docs/sql/reference/ddl/create"
>}}#columns) (only non persisted like computed and metadata virtual),
[constraints]({{< ref "docs/sql/reference/ddl/create" >}}#primary-key), a
[watermark]({{< ref "docs/sql/reference/ddl/create" >}}#watermark), and a
[distribution]({{< ref "docs/sql/reference/ddl/create" >}}#distributed) to an
existing materialized table.
+
+To add a column at the specified position, use `FIRST` or `AFTER col_name`. By
default, the column is appended at last.
+
+The following examples illustrate the usage of the `ADD` statements.
+
+```sql
+-- add a new column
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD category_id STRING METADATA
VIRTUAL;
+
+-- add columns, constraint, and watermark
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD (
+ log_ts STRING METADATA VIRTUAL FIRST,
+ ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
+ PRIMARY KEY (id) NOT ENFORCED,
+ WATERMARK FOR ts AS ts - INTERVAL '3' SECOND
+);
+
+-- add new distribution using a hash on uid into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY HASH(uid)
INTO 4 BUCKETS;
+
+-- add new distribution on uid into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY (uid) INTO 4
BUCKETS;
+
+-- add new distribution on uid.
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY (uid);
+
+-- add new distribution into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION INTO 4 BUCKETS;
+```
+<span class="label label-danger">Note</span> Add a column to be primary key
will change the column's nullability to false implicitly.
+
+## MODIFY
+Use `MODIFY` clause to change column's comment, position, type (only non
persisted like computed and metadata virtual also see [columns]({{< ref
"docs/sql/reference/ddl/create" >}}#columns)), change primary key columns and
watermark strategy to an existing table.
+
+To modify an existent column to a new position, use `FIRST` or `AFTER
col_name`. By default, the position remains unchanged.
+
+The following examples illustrate the usage of the `MODIFY` statements.
+
+```sql
+-- modify a column type, comment and position
+ALTER MATERIALIZED TABLE MyMaterializedTable MODIFY measurement double
METADATA COMMENT 'unit is bytes per second' AFTER `id`;
+
+-- modify definition of column log_ts and ts, primary key, watermark. They
must exist in table schema
+ALTER MATERIALIZED TABLE MyMaterializedTable MODIFY (
+ log_ts STRING METADATA COMMENT 'log timestamp string' AFTER `id`, --
reorder columns
+ ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
+ PRIMARY KEY (id) NOT ENFORCED,
+ WATERMARK FOR ts AS ts -- modify watermark strategy
+);
+```
+
+<span class="label label-danger">Note</span> Modify a column to be primary key
will change the column's nullability to false implicitly.
+
+## DROP
+Use the `DROP` clause to drop columns (only non persisted like computed and
metadata virtual also see [columns]({{< ref "docs/sql/reference/ddl/create"
>}}#columns)), primary key, partitions, and watermark strategy to an existing
table.
+
+The following examples illustrate the usage of the `DROP` statements.
+
+```sql
+-- drop a column
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP measurement;
+
+-- drop columns
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP (col1, col2, col3);
+
+-- drop primary key
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP PRIMARY KEY;
+
+-- drop a watermark
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP WATERMARK;
+
+-- drop distribution
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP DISTRIBUTION;
+```
## SUSPEND
diff --git a/docs/content.zh/docs/sql/reference/ddl/alter.md
b/docs/content.zh/docs/sql/reference/ddl/alter.md
index b5a1a9e42f6..1f089e28241 100644
--- a/docs/content.zh/docs/sql/reference/ddl/alter.md
+++ b/docs/content.zh/docs/sql/reference/ddl/alter.md
@@ -36,6 +36,7 @@ ALTER 语句用于修改一个已经在 [Catalog]({{< ref "docs/sql/catalogs" >}
Flink SQL 目前支持以下 ALTER 语句：
- ALTER TABLE
+- ALTER MATERIALIZED TABLE
- ALTER VIEW
- ALTER DATABASE
- ALTER FUNCTION
@@ -510,6 +511,9 @@ ALTER TABLE DataGenSource RESET ('rows-per-second');
{{< top >}}
+## ALTER MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#alter-materialized-table).
+
## ALTER VIEW
```sql
diff --git a/docs/content.zh/docs/sql/reference/ddl/create.md
b/docs/content.zh/docs/sql/reference/ddl/create.md
index cffd9d689a6..6a9fcaafe76 100644
--- a/docs/content.zh/docs/sql/reference/ddl/create.md
+++ b/docs/content.zh/docs/sql/reference/ddl/create.md
@@ -37,6 +37,7 @@ CREATE 语句用于向当前或指定的 [Catalog]({{< ref "docs/sql/catalogs" >
- CREATE TABLE
- [CREATE OR] REPLACE TABLE
+- CREATE [OR ALTER ]MATERIALIZED TABLE
- CREATE CATALOG
- CREATE DATABASE
- CREATE VIEW
@@ -196,8 +197,8 @@ CREATE TABLE [IF NOT EXISTS]
[catalog_name.][db_name.]table_name
<distribution>:
{
- DISTRIBUTION BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
- | DISTRIBUTION INTO n BUCKETS
+ DISTRIBUTED BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
+ | DISTRIBUTED INTO n BUCKETS
}
```
@@ -808,6 +809,9 @@ INSERT INTO my_rtas_table (id, price, quantity, order_time)
{{< top >}}
+## CREATE [OR ALTER ]MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#create-materialized-table).
+
## CREATE CATALOG
```sql
diff --git a/docs/content.zh/docs/sql/reference/ddl/drop.md
b/docs/content.zh/docs/sql/reference/ddl/drop.md
index 25ad94dac72..2cf8af8fbfe 100644
--- a/docs/content.zh/docs/sql/reference/ddl/drop.md
+++ b/docs/content.zh/docs/sql/reference/ddl/drop.md
@@ -35,6 +35,7 @@ Flink SQL 目前支持以下 DROP 语句：
- DROP CATALOG
- DROP TABLE
+- DROP MATERIALIZED TABLE
- DROP DATABASE
- DROP VIEW
- DROP FUNCTION
@@ -173,6 +174,9 @@ DROP TABLE [IF EXISTS] [catalog_name.][db_name.]table_name
表不存在时不会进行任何操作。
+## DROP MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#drop-materialized-table).
+
## DROP DATABASE
```sql
diff --git a/docs/content/docs/sql/materialized-table/statements.md
b/docs/content/docs/sql/materialized-table/statements.md
index a8f0403a6d6..acfece212e9 100644
--- a/docs/content/docs/sql/materialized-table/statements.md
+++ b/docs/content/docs/sql/materialized-table/statements.md
@@ -33,7 +33,7 @@ Flink SQL supports the following Materialized Table
statements for now:
# CREATE [OR ALTER] MATERIALIZED TABLE
-```
+```text
CREATE [OR ALTER] MATERIALIZED TABLE [catalog_name.][db_name.]table_name
[(
@@ -44,6 +44,8 @@ CREATE [OR ALTER] MATERIALIZED TABLE
[catalog_name.][db_name.]table_name
[COMMENT table_comment]
+[ <distribution> ]
+
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
[WITH (key1=val1, key2=val2, ...)]
@@ -71,6 +73,12 @@ AS <select_statement>
<watermark_definition>:
WATERMARK FOR rowtime_column_name AS watermark_strategy_expression
+
+<distribution>:
+{
+ DISTRIBUTED BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
+ | DISTRIBUTED INTO n BUCKETS
+}
```
## PRIMARY KEY
@@ -382,15 +390,125 @@ CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
# ALTER MATERIALIZED TABLE
-```
+```text
ALTER MATERIALIZED TABLE [catalog_name.][db_name.]table_name
- SUSPEND | RESUME [WITH (key1=val1, key2=val2, ...)] |
- REFRESH [PARTITION partition_spec] |
- AS <select_statement>
+ ADD { <schema_component> | (<schema_component> [, ...]) | <distribution> }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) |
<distribution> }
+ | DROP {column_name | (column_name, column_name, ...) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK | DISTRIBUTION }
+ | SUSPEND | RESUME [WITH (key1=val1, key2=val2, ...)]
+ | REFRESH [PARTITION partition_spec] |
+ | AS <select_statement>
+<schema_component>:
+ { <column_component> | <constraint_component> | <watermark_component> }
+
+<column_component>:
+ column_name <column_definition> [FIRST | AFTER column_name]
+
+<constraint_component>:
+ [CONSTRAINT constraint_name] PRIMARY KEY (column_name, ...) NOT ENFORCED
+
+<watermark_component>:
+ WATERMARK FOR rowtime_column_name AS watermark_strategy_expression
+
+<column_definition>:
+ { <physical_column_definition> | <metadata_column_definition> |
<computed_column_definition> } [COMMENT column_comment]
+
+<physical_column_definition>:
+ column_type
+
+<metadata_column_definition>:
+ column_type METADATA [ FROM metadata_key ] [ VIRTUAL ]
+
+<computed_column_definition>:
+ AS computed_column_expression
+
+<distribution>:
+{
+ DISTRIBUTED BY [ { HASH | RANGE } ] (bucket_column_name1,
bucket_column_name2, ...) [INTO n BUCKETS]
+ | DISTRIBUTED INTO n BUCKETS
+}
+
```
`ALTER MATERIALIZED TABLE` is used to manage materialized tables. This command
allows users to suspend and resume refresh pipeline of materialized tables and
manually trigger data refreshes, and modify the query definition of
materialized tables.
+## ADD
+Use `ADD` clause to add [columns]({{< ref "docs/sql/reference/ddl/create"
>}}#columns) (only non persisted like computed and metadata virtual),
[constraints]({{< ref "docs/sql/reference/ddl/create" >}}#primary-key), a
[watermark]({{< ref "docs/sql/reference/ddl/create" >}}#watermark), and a
[distribution]({{< ref "docs/sql/reference/ddl/create" >}}#distributed) to an
existing materialized table.
+
+To add a column at the specified position, use `FIRST` or `AFTER col_name`. By
default, the column is appended at last.
+
+The following examples illustrate the usage of the `ADD` statements.
+
+```sql
+-- add a new column
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD category_id STRING METADATA
VIRTUAL;
+
+-- add columns, constraint, and watermark
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD (
+ log_ts STRING METADATA VIRTUAL FIRST,
+ ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
+ PRIMARY KEY (id) NOT ENFORCED,
+ WATERMARK FOR ts AS ts - INTERVAL '3' SECOND
+);
+
+-- add new distribution using a hash on uid into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY HASH(uid)
INTO 4 BUCKETS;
+
+-- add new distribution on uid into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY (uid) INTO 4
BUCKETS;
+
+-- add new distribution on uid.
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION BY (uid);
+
+-- add new distribution into 4 buckets
+ALTER MATERIALIZED TABLE MyMaterializedTable ADD DISTRIBUTION INTO 4 BUCKETS;
+```
+<span class="label label-danger">Note</span> Add a column to be primary key
will change the column's nullability to false implicitly.
+
+## MODIFY
+Use `MODIFY` clause to change column's comment, position, type (only non
persisted like computed and metadata virtual also see [columns]({{< ref
"docs/sql/reference/ddl/create" >}}#columns)), change primary key columns and
watermark strategy to an existing table.
+
+To modify an existent column to a new position, use `FIRST` or `AFTER
col_name`. By default, the position remains unchanged.
+
+The following examples illustrate the usage of the `MODIFY` statements.
+
+```sql
+-- modify a column type, comment and position
+ALTER MATERIALIZED TABLE MyMaterializedTable MODIFY measurement double
METADATA COMMENT 'unit is bytes per second' AFTER `id`;
+
+-- modify definition of column log_ts and ts, primary key, watermark. They
must exist in table schema
+ALTER MATERIALIZED TABLE MyMaterializedTable MODIFY (
+ log_ts STRING METADATA COMMENT 'log timestamp string' AFTER `id`, --
reorder columns
+ ts AS TO_TIMESTAMP(log_ts) AFTER log_ts,
+ PRIMARY KEY (id) NOT ENFORCED,
+ WATERMARK FOR ts AS ts -- modify watermark strategy
+);
+```
+
+<span class="label label-danger">Note</span> Modify a column to be primary key
will change the column's nullability to false implicitly.
+
+## DROP
+Use the `DROP` clause to drop columns (only non persisted like computed and
metadata virtual, also see [columns]({{< ref "docs/sql/reference/ddl/create"
>}}#columns)), primary key, partitions, and watermark strategy to an existing
table.
+
+The following examples illustrate the usage of the `DROP` statements.
+
+```sql
+-- drop a column
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP measurement;
+
+-- drop columns
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP (col1, col2, col3);
+
+-- drop primary key
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP PRIMARY KEY;
+
+-- drop a watermark
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP WATERMARK;
+
+-- drop distribution
+ALTER MATERIALIZED TABLE MyMaterializedTable DROP DISTRIBUTION;
+```
+
## SUSPEND
```
diff --git a/docs/content/docs/sql/reference/ddl/alter.md
b/docs/content/docs/sql/reference/ddl/alter.md
index 030573d7344..3671b422181 100644
--- a/docs/content/docs/sql/reference/ddl/alter.md
+++ b/docs/content/docs/sql/reference/ddl/alter.md
@@ -34,6 +34,7 @@ ALTER statements are used to modify the definition of a
table, view or function
Flink SQL supports the following ALTER statements for now:
- ALTER TABLE
+- ALTER MATERIALIZED TABLE
- ALTER VIEW
- ALTER DATABASE
- ALTER FUNCTION
@@ -508,6 +509,9 @@ ALTER TABLE DataGenSource RESET ('rows-per-second');
{{< top >}}
+## ALTER MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#alter-materialized-table).
+
## ALTER VIEW
```sql
diff --git a/docs/content/docs/sql/reference/ddl/create.md
b/docs/content/docs/sql/reference/ddl/create.md
index b72fa7a2dea..8140c9e9cc7 100644
--- a/docs/content/docs/sql/reference/ddl/create.md
+++ b/docs/content/docs/sql/reference/ddl/create.md
@@ -33,6 +33,7 @@ Flink SQL supports the following CREATE statements for now:
- CREATE TABLE
- [CREATE OR] REPLACE TABLE
+- CREATE [OR ALTER ]MATERIALIZED TABLE
- CREATE CATALOG
- CREATE DATABASE
- CREATE VIEW
@@ -792,6 +793,9 @@ If you want to enable atomicity for RTAS, then you should
make sure:
{{< top >}}
+## CREATE [OR ALTER ]MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#create-materialized-table).
+
## CREATE CATALOG
```sql
diff --git a/docs/content/docs/sql/reference/ddl/drop.md
b/docs/content/docs/sql/reference/ddl/drop.md
index a57f8593adf..d9464c2660e 100644
--- a/docs/content/docs/sql/reference/ddl/drop.md
+++ b/docs/content/docs/sql/reference/ddl/drop.md
@@ -33,6 +33,7 @@ Flink SQL supports the following DROP statements for now:
- DROP CATALOG
- DROP TABLE
+- DROP MATERIALIZED TABLE
- DROP DATABASE
- DROP VIEW
- DROP FUNCTION
@@ -169,6 +170,9 @@ Drop temporary table that has catalog and database
namespaces.
If the table does not exist, nothing happens.
+## DROP MATERIALIZED TABLE
+See a dedicated page for [Materialized tables]({{< ref
"docs/sql/materialized-table/statements" >}}#drop-materialized-table).
+
## DROP DATABASE
```sql
