fsk119 commented on code in PR #21647:
URL: https://github.com/apache/flink/pull/21647#discussion_r1094397774
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name SET (key1=val1, key2=val2, ...)
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD
(<column_component>[, <column_component>, ...])
+```
+
+Add table column(s) to the specified position, which includes
+- Append the column to the last position
+- Insert the column to the first position
+- Insert the column after the specified column
+
+Throws `ValidationException` when either of following conditions are met
Review Comment:
Do we need to expose the type of exception? It seems like it is a public API.
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
Review Comment:
Acutally users may also get `TableNotExistException`. How about
```
If the table does not exist, an exception is thrown unless `IF EXISTS` is
specified.
```
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name SET (key1=val1, key2=val2, ...)
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD
(<column_component>[, <column_component>, ...])
+```
+
+Add table column(s) to the specified position, which includes
+- Append the column to the last position
Review Comment:
It's better we can tell users it's the default behaviour.
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
Review Comment:
BTW, why not illustrate `IF EXISTS` parameter like we does in the `ALFTER
FUNCTION` section?
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name SET (key1=val1, key2=val2, ...)
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD
(<column_component>[, <column_component>, ...])
+```
+
+Add table column(s) to the specified position, which includes
+- Append the column to the last position
+- Insert the column to the first position
+- Insert the column after the specified column
+
+Throws `ValidationException` when either of following conditions are met
+- Add a column name which is already defined in the table schema
+- Add a column which refers to a nonexistent column by `AFTER`
+- Add a computed column which is derived from another computed or nonexistent
columns
+- Add a computed column with invalid expression
+
+**Add Table Constraint**
+
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD [CONSTRAINT
constraint_name] PRIMARY KEY(col1[, col2, ...]) NOT ENFORCED
+```
+
+Add primary key to the table. Throws `ValidationException` when either of
following conditions are met
+- The table already defines primary key
+- The specified column does not exist or is not a physical column
+
+<span class="label label-danger">Note</span> Add a column to be primary key
will change the column's nullability to false implicitly.
+
+**Add Table Watermark**
+
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD WATERMARK FOR
rowtime_column_name AS watermark_strategy_expression
+```
+
+Add a watermark to the table. Add primary key to the table. Throws
`ValidationException` when either of following conditions are met
+- The table already defines watermark
+- The specified row-time field does not exist
+- The watermark strategy expression is invalid.
Review Comment:
Do we need to write these details in the doc... I think we can remove this.
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name SET (key1=val1, key2=val2, ...)
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD
(<column_component>[, <column_component>, ...])
+```
+
+Add table column(s) to the specified position, which includes
+- Append the column to the last position
+- Insert the column to the first position
+- Insert the column after the specified column
+
+Throws `ValidationException` when either of following conditions are met
+- Add a column name which is already defined in the table schema
+- Add a column which refers to a nonexistent column by `AFTER`
+- Add a computed column which is derived from another computed or nonexistent
columns
+- Add a computed column with invalid expression
+
+**Add Table Constraint**
+
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD [CONSTRAINT
constraint_name] PRIMARY KEY(col1[, col2, ...]) NOT ENFORCED
Review Comment:
How about giving an example here? We already have the syntax above.
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
Review Comment:
How about using the Level-3 header here? With a level-3 header, we can see
the section in the catalog.
I think we can have the following structure in the doc.
```
1. ALTER TABLE
1.1 ADD
1.2 MODIFY
1.3 DROP
1.4 RENAME COLUMN
1.5 RENAME TABLE
1.6 SET
1.7 RESET
```
I write a piece of the doc about the `ADD` section. WDYT?
```
Use ADD clause to add [columns]({{< ref "docs/dev/table/sql/create"
>}}#columns), [constraints], [watermark] to an existing table.
To add a column at the specified position, user `FIRST` or `AFTER col_name`.
The default is to add the column last.
The following statements add column `user_address` to the `MyTable`.
```text
ALTER TABLE MyTable
ADD `user_address` AFTER `name`
```text
```
##########
docs/content/docs/dev/table/sql/alter.md:
##########
@@ -125,38 +179,310 @@ tables = table_env.list_tables()
{{< tab "SQL CLI" >}}
```sql
Flink SQL> CREATE TABLE Orders (`user` BIGINT, product STRING, amount INT)
WITH (...);
-[INFO] Table has been created.
+[INFO] Execute statement succeed.
+
+Flink SQL> ALTER TABLE Orders ADD `order` INT COMMENT 'order identifier' FIRST;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+------+-----+--------+-----------+------------------+
+| name | type | null | key | extras | watermark | comment |
++---------+--------+------+-----+--------+-----------+------------------+
+| order | INT | TRUE | | | | order identifier |
+| user | BIGINT | TRUE | | | | |
+| product | STRING | TRUE | | | | |
+| amount | INT | TRUE | | | | |
++---------+--------+------+-----+--------+-----------+------------------+
+4 rows in set
+
+Flink SQL> ALTER TABLE Orders ADD (ts TIMESTAMP(3), category STRING AFTER
product, PRIMARY KEY(`order`) NOT ENFORCED, WATERMARK FOR ts AS ts - INTERVAL
'1' HOUR);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| name | type | null | key | extras |
watermark | comment |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| category | STRING | TRUE | | |
| |
+| amount | INT | TRUE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts` -
INTERVAL '1' HOUR | |
++----------+------------------------+-------+------------+--------+--------------------------+------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders MODIFY (amount DOUBLE NOT NULL, category STRING
COMMENT 'category identifier' AFTER `order`, WATERMARK FOR ts AS ts);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark
| comment |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | |
| order identifier |
+| category | STRING | TRUE | | |
| category identifier |
+| user | BIGINT | TRUE | | |
| |
+| product | STRING | TRUE | | |
| |
+| amount | DOUBLE | FALSE | | |
| |
+| ts | TIMESTAMP(3) *ROWTIME* | TRUE | | | `ts`
| |
++----------+------------------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP WATERMARK;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------------+-------+------------+--------+-----------+---------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| category | STRING | TRUE | | | | category
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
+| amount | DOUBLE | FALSE | | | |
|
+| ts | TIMESTAMP(3) | TRUE | | | |
|
++----------+--------------+-------+------------+--------+-----------+---------------------+
+6 rows in set
+
+Flink SQL> ALTER TABLE Orders DROP (amount, ts, category);
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++---------+--------+-------+------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++---------+--------+-------+------------+--------+-----------+------------------+
+| order | INT | FALSE | PRI(order) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++---------+--------+-------+------------+--------+-----------+------------------+
+3 rows in set
+
+Flink SQL> ALTER TABLE Orders RENAME `order` to `order_id`;
+[INFO] Execute statement succeed.
+
+Flink SQL> DESCRIBE Orders;
++----------+--------+-------+---------------+--------+-----------+------------------+
+| name | type | null | key | extras | watermark |
comment |
++----------+--------+-------+---------------+--------+-----------+------------------+
+| order_id | INT | FALSE | PRI(order_id) | | | order
identifier |
+| user | BIGINT | TRUE | | | |
|
+| product | STRING | TRUE | | | |
|
++----------+--------+-------+---------------+--------+-----------+------------------+
+3 rows in set
Flink SQL> SHOW TABLES;
-Orders
++------------+
+| table name |
++------------+
+| Orders |
++------------+
+1 row in set
Flink SQL> ALTER TABLE Orders RENAME TO NewOrders;
-[INFO] Table has been removed.
+[INFO] Execute statement succeed.
Flink SQL> SHOW TABLES;
-NewOrders
++------------+
+| table name |
++------------+
+| NewOrders |
++------------+
+1 row in set
```
{{< /tab >}}
{{< /tabs >}}
+{{< top >}}
+
## ALTER TABLE
-* Rename Table
+The following grammar gives an overview about the available syntax:
+```text
+ALTER TABLE [IF EXISTS] table_name {
+ ADD { <schema_component> | (<schema_component> [, ...]) }
+ | MODIFY { <schema_component> | (<schema_component> [, ...]) }
+ | DROP {column_name | (column_name, column_name, ....) | PRIMARY KEY |
CONSTRAINT constraint_name | WATERMARK}
+ | RENAME old_column_name TO new_column_name
+ | RENAME TO new_table_name
+ | SET (key1=val1, ...)
+ | RESET (key1, ...)
+}
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name RENAME TO new_table_name
+<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
```
-Rename the given table name to another new table name.
+<span class="label label-info">Note</span> If the table does not exist,
`ValidationException` is thrown unless `IF EXISTS` is specified.
-* Set or Alter Table Properties
+**Add Table Column**
-```sql
-ALTER TABLE [catalog_name.][db_name.]table_name SET (key1=val1, key2=val2, ...)
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD
(<column_component>[, <column_component>, ...])
+```
+
+Add table column(s) to the specified position, which includes
+- Append the column to the last position
+- Insert the column to the first position
+- Insert the column after the specified column
+
+Throws `ValidationException` when either of following conditions are met
+- Add a column name which is already defined in the table schema
+- Add a column which refers to a nonexistent column by `AFTER`
+- Add a computed column which is derived from another computed or nonexistent
columns
+- Add a computed column with invalid expression
+
+**Add Table Constraint**
+
+```text
+ALTER TABLE [IF EXISTS] [catalog_name.][db_name.]table_name ADD [CONSTRAINT
constraint_name] PRIMARY KEY(col1[, col2, ...]) NOT ENFORCED
+```
+
+Add primary key to the table. Throws `ValidationException` when either of
following conditions are met
Review Comment:
It's better if we can refer to the create#PRIMARY KEY section. I think we
have the same rules when creating a table with pk.
--
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]
