Skip to content

Commit f577b4f

Browse files
[docs] Add document about ADD COLUMN AT LAST (#2203)
--------- Co-authored-by: Jark Wu <[email protected]>
1 parent 5ed3b37 commit f577b4f

File tree

2 files changed

+39
-1
lines changed

2 files changed

+39
-1
lines changed

website/docs/engine-flink/ddl.md

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,36 @@ DROP TABLE my_table;
222222
This will entirely remove all the data of the table in the Fluss cluster.
223223

224224
## Alter Table
225+
226+
### Add Columns
227+
228+
Fluss allows you to evolve a table's schema by adding new columns. This is a lightweight, metadata-only operation that offers the following benefits:
229+
230+
- **Zero Data Rewrite**: Adding a column does not require rewriting or migrating existing data files.
231+
- **Instant Execution**: The operation completes in milli-seconds, regardless of the table size.
232+
- **Availability**: The table remains online and fully accessible throughout schema evolution, with no disruption to active clients.
233+
234+
Currently, this feature has the following characteristics:
235+
236+
- **Position**: New columns are always appended to the end of the existing column list.
237+
- **Nullability**: Only nullable columns can be added to an existing table to ensure compatibility with existing data.
238+
- **Type Support**: You can add columns of any data type, including complex types such as `ROW`, `MAP`, and `ARRAY`.
239+
- **Nested Fields**: Currently, adding fields within an existing nested `ROW` is not supported. Such operations are categorized as "updating column types" and will be supported in future versions.
240+
241+
You can add a single column or multiple columns using the `ALTER TABLE statement.
242+
243+
```sql title="Flink SQL"
244+
-- Add a single column at the end of the table
245+
ALTER TABLE my_table ADD user_email STRING COMMENT 'User email address';
246+
247+
-- Add multiple columns at the end of the table
248+
ALTER TABLE MyTable ADD (
249+
user_email STRING COMMENT 'User email address',
250+
order_quantity INT
251+
);
252+
```
253+
254+
225255
### SET properties
226256
The SET statement allows users to configure one or more connector options including the [Storage Options](engine-flink/options.md#storage-options) for a specified table. If a particular option is already configured on the table, it will be overridden with the new value.
227257

@@ -249,7 +279,6 @@ The following example illustrates reset the `table.datalake.enabled` option to i
249279
ALTER TABLE my_table RESET ('table.datalake.enabled');
250280
```
251281

252-
253282
## Add Partition
254283

255284
Fluss supports manually adding partitions to an existing partitioned table through the Fluss Catalog. If the specified partition

website/docs/maintenance/operations/upgrade-notes-0.9.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,15 @@ sidebar_position: 4
77

88
These upgrade notes discuss important aspects, such as configuration, behavior, or dependencies, that changed between Fluss 0.8 and Fluss 0.9. Please read these notes carefully if you are planning to upgrade your Fluss version to 0.9.
99

10+
## Adding Columns
11+
12+
Fluss storage format was designed with schema evolution protocols from day one. Therefore, tables created in v0.8 or earlier can immediately benefit from the `ADD COLUMN` feature after upgrading to v0.9 without dropping and re-creating table.
13+
However, old clients (pre-v0.9) do not recognize the new schema versioning protocol. If an old client attempts to read data from a table that has undergone schema evolution, it may encounter decoding errors or data inaccessibility.
14+
Therefore, it is crucial to ensure that all Fluss servers and all clients interacting with the Fluss cluster are upgraded to v0.9 before performing any schema modifications.
15+
16+
:::warning
17+
Attempting to add columns while older clients (v0.8 or below) are still actively reading from the table will lead to Schema Inconsistency and may crash your streaming pipelines.
18+
:::
1019

1120
## Deprecation / End of Support
1221

0 commit comments

Comments
 (0)