Skip to content

Commit d98845a

Browse files
raminqaframinqaf
committed
[FLINK-38355] Inline docs similar to parser definition
1 parent 67170b5 commit d98845a

File tree

2 files changed

+134
-199
lines changed

2 files changed

+134
-199
lines changed

‎docs/content.zh/docs/dev/table/materialized-table/statements.md‎

Lines changed: 67 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,14 @@ under the License.
2727
# 物化表语法
2828

2929
Flink SQL 目前支持以下物化表操作：
30-
- [CREATE MATERIALIZED TABLE](#create-materialized-table)
30+
- [CREATE [OR ALTER] MATERIALIZED TABLE](#create-or-alter-materialized-table)
3131
- [ALTER MATERIALIZED TABLE](#alter-materialized-table)
32-
- [CREATE OR ALTER MATERIALIZED TABLE](#create-or-alter-materialized-table)
3332
- [DROP MATERIALIZED TABLE](#drop-materialized-table)
3433

35-
# CREATE MATERIALIZED TABLE
34+
# CREATE [OR ALTER] MATERIALIZED TABLE
3635

3736
```
38-
CREATE MATERIALIZED TABLE [catalog_name.][db_name.]table_name
37+
CREATE [OR ALTER] MATERIALIZED TABLE [catalog_name.][db_name.]table_name
3938
4039
[ ([ <table_constraint> ]) ]
4140
@@ -210,6 +209,30 @@ CREATE MATERIALIZED TABLE my_materialized_table
210209
AS SELECT * FROM kafka_catalog.db1.kafka_table;
211210
```
212211

212+
## OR ALTER
213+
214+
The `OR ALTER` clause provides create-or-update semantics:
215+
216+
- **If the table does not exist**: Creates a new materialized table with the specified options
217+
- **If the table exists**: Modifies the query definition (behaves like `ALTER MATERIALIZED TABLE AS`)
218+
219+
This is particularly useful in declarative deployment scenarios where you want to define the desired state without checking if the table already exists.
220+
221+
**Behavior when table exists:**
222+
223+
The operation updates the materialized table similarly to [ALTER MATERIALIZED TABLE AS](#as-select_statement-1):
224+
225+
**Full mode:**
226+
1. Updates the schema and query definition
227+
2. The table is refreshed using the new query when the next refresh job is triggered
228+
229+
**Continuous mode:**
230+
1. Pauses the current running refresh job
231+
2. Updates the schema and query definition
232+
3. Starts a new refresh job from the beginning
233+
234+
See [ALTER MATERIALIZED TABLE AS](#as-select_statement-1) for more details.
235+
213236
## 示例
214237

215238
假定 `materialized-table.refresh-mode.freshness-threshold` 为 30 分钟。
@@ -272,6 +295,46 @@ CREATE MATERIALIZED TABLE my_materialized_table_full
272295
p.ds, p.product_id, p.product_name
273296
```
274297

298+
Create or alter a materialized table executed twice:
299+
300+
```sql
301+
-- First execution: creates the table
302+
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
303+
FRESHNESS = INTERVAL '10' SECOND
304+
AS
305+
SELECT
306+
user_id,
307+
COUNT(*) AS event_count,
308+
SUM(amount) AS total_amount
309+
FROM
310+
kafka_catalog.db1.events
311+
WHERE
312+
event_type = 'purchase'
313+
GROUP BY
314+
user_id;
315+
316+
-- Second execution: alters the query definition (adds avg_amount column)
317+
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
318+
FRESHNESS = INTERVAL '10' SECOND
319+
AS
320+
SELECT
321+
user_id,
322+
COUNT(*) AS event_count,
323+
SUM(amount) AS total_amount,
324+
AVG(amount) AS avg_amount -- Add a new nullable column at the end
325+
FROM
326+
kafka_catalog.db1.events
327+
WHERE
328+
event_type = 'purchase'
329+
GROUP BY
330+
user_id;
331+
```
332+
333+
<span class="label label-danger">Note</span>
334+
- When altering an existing table, schema evolution currently only supports adding `nullable` columns to the end of the original table's schema.
335+
- In continuous mode, the new refresh job will not restore from the state of the original refresh job when altering.
336+
- All limitations from both CREATE and ALTER operations apply.
337+
275338
## 限制
276339
- 不支持显式指定列名
277340
- 不支持在 select 查询语句中引用临时表、临时视图或临时函数
@@ -409,102 +472,6 @@ GROUP BY
409472
- Schema 演进当前仅支持在原表 schema 尾部追加`可空列`。
410473
- 在持续模式下，新的流式作业不会从原来的流式作业的状态恢复。这可能会导致短暂的数据重复或丢失。
411474

412-
413-
# CREATE OR ALTER MATERIALIZED TABLE
414-
415-
```
416-
CREATE OR ALTER MATERIALIZED TABLE [catalog_name.][db_name.]table_name
417-
418-
[ ([ <table_constraint> ]) ]
419-
420-
[COMMENT table_comment]
421-
422-
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
423-
424-
[WITH (key1=val1, key2=val2, ...)]
425-
426-
FRESHNESS = INTERVAL '<num>' { SECOND | MINUTE | HOUR | DAY }
427-
428-
[REFRESH_MODE = { CONTINUOUS | FULL }]
429-
430-
AS <select_statement>
431-
432-
<table_constraint>:
433-
[CONSTRAINT constraint_name] PRIMARY KEY (column_name, ...) NOT ENFORCED
434-
```
435-
436-
`CREATE OR ALTER MATERIALIZED TABLE` is a convenient statement that combines create and alter functionality:
437-
438-
- **If the table does not exist**: Creates a new materialized table (behaves like [CREATE MATERIALIZED TABLE](#create-materialized-table))
439-
- **If the table exists**: Modifies the query definition (behaves like [ALTER MATERIALIZED TABLE AS](#as-select_statement-1))
440-
441-
This is particularly useful in declarative deployment scenarios where you want to define the desired state of a materialized table without needing to check if it already exists.
442-
443-
## Syntax Details
444-
445-
The syntax is identical to `CREATE MATERIALIZED TABLE`. See the sections above for detailed explanations of:
446-
- [PRIMARY KEY](#primary-key)
447-
- [PARTITIONED BY](#partitioned-by)
448-
- [WITH Options](#with-options)
449-
- [FRESHNESS](#freshness)
450-
- [REFRESH_MODE](#refresh_mode)
451-
- [AS <select_statement>](#as-select_statement)
452-
453-
## Behavior When Table Exists
454-
455-
When the materialized table already exists, the operation behaves as if you ran `ALTER MATERIALIZED TABLE AS <select_statement>`:
456-
457-
**Full mode:**
458-
1. Update the `schema` and `query definition` of the materialized table.
459-
2. The table is refreshed using the new query definition when the next refresh job is triggered.
460-
461-
**Continuous mode:**
462-
1. Pause the current running refresh job.
463-
2. Update the `schema` and `query definition` of the materialized table.
464-
3. Start a new refresh job to refresh the materialized table from the beginning.
465-
466-
See [ALTER MATERIALIZED TABLE AS](#as-select_statement-1) for more details.
467-
468-
## Examples
469-
470-
471-
```sql
472-
-- First execution: creates the table
473-
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
474-
FRESHNESS = INTERVAL '10' SECOND
475-
AS
476-
SELECT
477-
user_id,
478-
COUNT(*) AS event_count,
479-
SUM(amount) AS total_amount
480-
FROM
481-
kafka_catalog.db1.events
482-
WHERE
483-
event_type = 'purchase'
484-
GROUP BY
485-
user_id;
486-
487-
-- Second execution: alters the query definition (adds avg_amount column)
488-
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
489-
AS
490-
SELECT
491-
user_id,
492-
COUNT(*) AS event_count,
493-
SUM(amount) AS total_amount,
494-
AVG(amount) AS avg_amount -- Add a new nullable column at the end
495-
FROM
496-
kafka_catalog.db1.events
497-
WHERE
498-
event_type = 'purchase'
499-
GROUP BY
500-
user_id;
501-
```
502-
503-
<span class="label label-danger">Note</span>
504-
- When altering an existing table, schema evolution currently only supports adding `nullable` columns to the end of the original table's schema.
505-
- In continuous mode, the new refresh job will not restore from the state of the original refresh job when altering.
506-
- All limitations from both CREATE and ALTER operations apply.
507-
508475
# DROP MATERIALIZED TABLE
509476

510477
```text

‎docs/content/docs/dev/table/materialized-table/statements.md‎

Lines changed: 67 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,14 @@ under the License.
2727
# Materialized Table Statements
2828

2929
Flink SQL supports the following Materialized Table statements for now:
30-
- [CREATE MATERIALIZED TABLE](#create-materialized-table)
30+
- [CREATE [OR ALTER] MATERIALIZED TABLE](#create-or-alter-materialized-table)
3131
- [ALTER MATERIALIZED TABLE](#alter-materialized-table)
32-
- [CREATE OR ALTER MATERIALIZED TABLE](#create-or-alter-materialized-table)
3332
- [DROP MATERIALIZED TABLE](#drop-materialized-table)
3433

35-
# CREATE MATERIALIZED TABLE
34+
# CREATE [OR ALTER] MATERIALIZED TABLE
3635

3736
```
38-
CREATE MATERIALIZED TABLE [catalog_name.][db_name.]table_name
37+
CREATE [OR ALTER] MATERIALIZED TABLE [catalog_name.][db_name.]table_name
3938
4039
[ ([ <table_constraint> ]) ]
4140
@@ -210,6 +209,30 @@ CREATE MATERIALIZED TABLE my_materialized_table
210209
AS SELECT * FROM kafka_catalog.db1.kafka_table;
211210
```
212211

212+
## OR ALTER
213+
214+
The `OR ALTER` clause provides create-or-update semantics:
215+
216+
- **If the table does not exist**: Creates a new materialized table with the specified options
217+
- **If the table exists**: Modifies the query definition (behaves like `ALTER MATERIALIZED TABLE AS`)
218+
219+
This is particularly useful in declarative deployment scenarios where you want to define the desired state without checking if the table already exists.
220+
221+
**Behavior when table exists:**
222+
223+
The operation updates the materialized table similarly to [ALTER MATERIALIZED TABLE AS](#as-select_statement-1):
224+
225+
**Full mode:**
226+
1. Updates the schema and query definition
227+
2. The table is refreshed using the new query when the next refresh job is triggered
228+
229+
**Continuous mode:**
230+
1. Pauses the current running refresh job
231+
2. Updates the schema and query definition
232+
3. Starts a new refresh job from the beginning
233+
234+
See [ALTER MATERIALIZED TABLE AS](#as-select_statement-1) for more details.
235+
213236
## Examples
214237

215238
Assuming `materialized-table.refresh-mode.freshness-threshold` is 30 minutes.
@@ -270,6 +293,46 @@ CREATE MATERIALIZED TABLE my_materialized_table_full
270293
p.ds, p.product_id, p.product_name
271294
```
272295

296+
Create or alter a materialized table executed twice:
297+
298+
```sql
299+
-- First execution: creates the table
300+
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
301+
FRESHNESS = INTERVAL '10' SECOND
302+
AS
303+
SELECT
304+
user_id,
305+
COUNT(*) AS event_count,
306+
SUM(amount) AS total_amount
307+
FROM
308+
kafka_catalog.db1.events
309+
WHERE
310+
event_type = 'purchase'
311+
GROUP BY
312+
user_id;
313+
314+
-- Second execution: alters the query definition (adds avg_amount column)
315+
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
316+
FRESHNESS = INTERVAL '10' SECOND
317+
AS
318+
SELECT
319+
user_id,
320+
COUNT(*) AS event_count,
321+
SUM(amount) AS total_amount,
322+
AVG(amount) AS avg_amount -- Add a new nullable column at the end
323+
FROM
324+
kafka_catalog.db1.events
325+
WHERE
326+
event_type = 'purchase'
327+
GROUP BY
328+
user_id;
329+
```
330+
331+
<span class="label label-danger">Note</span>
332+
- When altering an existing table, schema evolution currently only supports adding `nullable` columns to the end of the original table's schema.
333+
- In continuous mode, the new refresh job will not restore from the state of the original refresh job when altering.
334+
- All limitations from both CREATE and ALTER operations apply.
335+
273336
## Limitations
274337

275338
- Does not support explicitly specifying columns
@@ -409,101 +472,6 @@ ALTER MATERIALIZED TABLE my_materialized_table
409472
- Schema evolution currently only supports adding `nullable` columns to the end of the original table's schema.
410473
- In continuous mode, the new refresh job will not restore from the state of the original refresh job. This may result in temporary data duplication or loss.
411474

412-
# CREATE OR ALTER MATERIALIZED TABLE
413-
414-
```
415-
CREATE OR ALTER MATERIALIZED TABLE [catalog_name.][db_name.]table_name
416-
417-
[ ([ <table_constraint> ]) ]
418-
419-
[COMMENT table_comment]
420-
421-
[PARTITIONED BY (partition_column_name1, partition_column_name2, ...)]
422-
423-
[WITH (key1=val1, key2=val2, ...)]
424-
425-
FRESHNESS = INTERVAL '<num>' { SECOND | MINUTE | HOUR | DAY }
426-
427-
[REFRESH_MODE = { CONTINUOUS | FULL }]
428-
429-
AS <select_statement>
430-
431-
<table_constraint>:
432-
[CONSTRAINT constraint_name] PRIMARY KEY (column_name, ...) NOT ENFORCED
433-
```
434-
435-
`CREATE OR ALTER MATERIALIZED TABLE` is a convenient statement that combines create and alter functionality:
436-
437-
- **If the table does not exist**: Creates a new materialized table (behaves like [CREATE MATERIALIZED TABLE](#create-materialized-table))
438-
- **If the table exists**: Modifies the query definition (behaves like [ALTER MATERIALIZED TABLE AS](#as-select_statement-1))
439-
440-
This is particularly useful in declarative deployment scenarios where you want to define the desired state of a materialized table without needing to check if it already exists.
441-
442-
## Syntax Details
443-
444-
The syntax is identical to `CREATE MATERIALIZED TABLE`. See the sections above for detailed explanations of:
445-
- [PRIMARY KEY](#primary-key)
446-
- [PARTITIONED BY](#partitioned-by)
447-
- [WITH Options](#with-options)
448-
- [FRESHNESS](#freshness)
449-
- [REFRESH_MODE](#refresh_mode)
450-
- [AS <select_statement>](#as-select_statement)
451-
452-
## Behavior When Table Exists
453-
454-
When the materialized table already exists, the operation behaves as if you ran `ALTER MATERIALIZED TABLE AS <select_statement>`:
455-
456-
**Full mode:**
457-
1. Update the `schema` and `query definition` of the materialized table.
458-
2. The table is refreshed using the new query definition when the next refresh job is triggered.
459-
460-
**Continuous mode:**
461-
1. Pause the current running refresh job.
462-
2. Update the `schema` and `query definition` of the materialized table.
463-
3. Start a new refresh job to refresh the materialized table from the beginning.
464-
465-
See [ALTER MATERIALIZED TABLE AS](#as-select_statement-1) for more details.
466-
467-
## Examples
468-
469-
470-
```sql
471-
-- First execution: creates the table
472-
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
473-
FRESHNESS = INTERVAL '10' SECOND
474-
AS
475-
SELECT
476-
user_id,
477-
COUNT(*) AS event_count,
478-
SUM(amount) AS total_amount
479-
FROM
480-
kafka_catalog.db1.events
481-
WHERE
482-
event_type = 'purchase'
483-
GROUP BY
484-
user_id;
485-
486-
-- Second execution: alters the query definition (adds avg_amount column)
487-
CREATE OR ALTER MATERIALIZED TABLE my_materialized_table
488-
AS
489-
SELECT
490-
user_id,
491-
COUNT(*) AS event_count,
492-
SUM(amount) AS total_amount,
493-
AVG(amount) AS avg_amount -- Add a new nullable column at the end
494-
FROM
495-
kafka_catalog.db1.events
496-
WHERE
497-
event_type = 'purchase'
498-
GROUP BY
499-
user_id;
500-
```
501-
502-
<span class="label label-danger">Note</span>
503-
- When altering an existing table, schema evolution currently only supports adding `nullable` columns to the end of the original table's schema.
504-
- In continuous mode, the new refresh job will not restore from the state of the original refresh job when altering.
505-
- All limitations from both CREATE and ALTER operations apply.
506-
507475
# DROP MATERIALIZED TABLE
508476

509477
```text

0 commit comments

Comments
 (0)