This is an automated email from the ASF dual-hosted git repository.
jark pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fluss.git
The following commit(s) were added to refs/heads/main by this push:
new f577b4f44 [docs] Add document about ADD COLUMN AT LAST (#2203)
f577b4f44 is described below
commit f577b4f44a530032fd411aa298138b208d6a63d6
Author: Hongshun Wang <[email protected]>
AuthorDate: Fri Dec 26 21:42:28 2025 +0800
[docs] Add document about ADD COLUMN AT LAST (#2203)
---------
Co-authored-by: Jark Wu <[email protected]>
---
website/docs/engine-flink/ddl.md | 31 +++++++++++++++++++++-
.../maintenance/operations/upgrade-notes-0.9.md | 9 +++++++
2 files changed, 39 insertions(+), 1 deletion(-)
diff --git a/website/docs/engine-flink/ddl.md b/website/docs/engine-flink/ddl.md
index cc5bfcd97..324c75305 100644
--- a/website/docs/engine-flink/ddl.md
+++ b/website/docs/engine-flink/ddl.md
@@ -222,6 +222,36 @@ DROP TABLE my_table;
This will entirely remove all the data of the table in the Fluss cluster.
## Alter Table
+
+### Add Columns
+
+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:
+
+- **Zero Data Rewrite**: Adding a column does not require rewriting or
migrating existing data files.
+- **Instant Execution**: The operation completes in milli-seconds, regardless
of the table size.
+- **Availability**: The table remains online and fully accessible throughout
schema evolution, with no disruption to active clients.
+
+Currently, this feature has the following characteristics:
+
+- **Position**: New columns are always appended to the end of the existing
column list.
+- **Nullability**: Only nullable columns can be added to an existing table to
ensure compatibility with existing data.
+- **Type Support**: You can add columns of any data type, including complex
types such as `ROW`, `MAP`, and `ARRAY`.
+- **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.
+
+You can add a single column or multiple columns using the `ALTER TABLE
statement.
+
+```sql title="Flink SQL"
+-- Add a single column at the end of the table
+ALTER TABLE my_table ADD user_email STRING COMMENT 'User email address';
+
+-- Add multiple columns at the end of the table
+ALTER TABLE MyTable ADD (
+ user_email STRING COMMENT 'User email address',
+ order_quantity INT
+);
+```
+
+
### SET properties
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.
@@ -249,7 +279,6 @@ The following example illustrates reset the
`table.datalake.enabled` option to i
ALTER TABLE my_table RESET ('table.datalake.enabled');
```
-
## Add Partition
Fluss supports manually adding partitions to an existing partitioned table
through the Fluss Catalog. If the specified partition
diff --git a/website/docs/maintenance/operations/upgrade-notes-0.9.md
b/website/docs/maintenance/operations/upgrade-notes-0.9.md
index c9c7ab66f..863a04820 100644
--- a/website/docs/maintenance/operations/upgrade-notes-0.9.md
+++ b/website/docs/maintenance/operations/upgrade-notes-0.9.md
@@ -7,6 +7,15 @@ sidebar_position: 4
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.
+## Adding Columns
+
+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.
+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.
+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.
+
+:::warning
+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.
+:::
## Deprecation / End of Support
