@Rocky can you give more info on the state options for an ALTER TABLE? whats the difference between FINISHED and FINISHED_REWRITING and what others can i expect to see?

When you run an asynchronous

ALTER TABLE

operation (such as adding/modifying columns, creating a rollup, or optimizing the table), StarRocks processes the job through several internal states. You can monitor these by running

SHOW ALTER TABLE COLUMN;

,

SHOW ALTER TABLE ROLLUP;

, or

SHOW ALTER TABLE OPTIMIZE;

. The primary difference between FINISHED and FINISHED_REWRITING relates to the stage of data processing versus metadata finalization: 1. FINISHED vs. FINISHED_REWRITING *

FINISHED_REWRITING

: This state indicates that the physical data processing is complete. StarRocks has finished rewriting the data into the new format (e.g., creating "shadow tablets" with the new schema or new bucketing). However, the job is not yet officially "live." It is usually waiting for a final transaction to commit, which swaps the old metadata for the new metadata. _ _Note:* If a job is stuck here, it is often due to lock contention with long-running transactions or a version gap that prevents the FE from publishing the final version. *

FINISHED

: This is the terminal success state. It means the metadata swap is complete, the new schema/structure is now active, and the old data (shadow tablets/old versions) has been scheduled for cleanup. Queries will now use the updated table structure. ────────── 2. Other States You May Encounter As a job progresses, it typically cycles through these states in order: *

PENDING

: The job has been submitted and is waiting in the queue to be scheduled. *

WAITING_TXN

: Before the job can start rewriting data, it must wait for certain preceding transactions (like active data loads) to finish to ensure data consistency. *

RUNNING

: The BE (Backends) are actively performing the work. This is usually the longest phase where data is being read, transformed, and rewritten into new tablet versions. *

CANCELLED

: The job failed or was manually stopped using

CANCEL ALTER TABLE

. You can check the

Msg

column in the

SHOW ALTER

output to see the error reason. Summary Table for Asynchronous Alter Jobs State | Meaning PENDING | Job is created and waiting to start. WAITING_TXN | Waiting for existing load transactions to finish. RUNNING | Actively rewriting data (schema change/rollup creation). FINISHED_REWRITING | Data rewriting is done; waiting to finalize metadata. FINISHED | Operation complete and successfully applied. CANCELLED | Job failed or was aborted by the user. Pro Tip: Operations like RENAME, PARTITION (add/drop), and SWAP are synchronous. They do not go through these states; they either succeed immediately or return an error to your SQL client. References • administration/management/monitoring/metrics.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • sql-reference/information_schema/analyze_status.md • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • sql-reference/information_schema/loads.md • sql-reference/information_schema/routine_load_jobs.md • sql-reference/sql-statements/loading_unloading/routine_load/SHOW_ROUTINE_LOAD.md

can i insert data into the table when its in FINISHED_REWRITING? or need to wait for FINISHED?

Technically, you can continue to insert data while an

ALTER TABLE

job is in the

FINISHED_REWRITING

state, but it is highly recommended to pause or slow down your loads at this stage. Here is the breakdown of why this matters and the specific differences between the states. 1. FINISHED_REWRITING vs. FINISHED *

FINISHED_REWRITING

: This state means the physical work (the heavy lifting) is done. StarRocks has finished rewriting the existing data into the new schema or bucket structure. However, it is now in a "catch-up" phase. It needs to apply any incremental data that was loaded while the

RUNNING

phase was active and then perform a final metadata swap. *

FINISHED

: This is the terminal state. The metadata swap is complete, and the new table version is now live. Queries will now use the new schema, and the background cleanup of old data has begun. 2. Why you should be careful with INSERTS in

FINISHED_REWRITING

The

ALTER

job cannot move from

FINISHED_REWRITING

to

FINISHED

until it has "caught up" with the most recent version of the data. * The Version Gap: Every

INSERT

creates a new version of the data. If you are continuously loading data at a high frequency, the

ALTER

job may struggle to close the gap between the rewritten data and the latest incoming data. * Stuck Jobs: If the load volume is high enough, the job can stay in

FINISHED_REWRITING

indefinitely because it never gets a quiet enough window to publish the final version. In some versions (especially shared-data mode), heavy concurrent writes can even cause version discontinuity errors that require manual intervention. * Lock Contention: The final transition to

FINISHED

requires a metadata lock. High-frequency

INSERT

transactions can compete for these locks, delaying the completion of the schema change. Recommendation: If you see a job sitting in

FINISHED_REWRITING

for a long time, temporarily pause your Routine Loads or

INSERT

jobs. This usually allows the

ALTER

task to finish within seconds. ────────── 3. All Possible States When monitoring your job via

SHOW ALTER TABLE COLUMN;

, you will see these states in order: State | What is happening?

PENDING

| The job is in the queue waiting to be scheduled by the FE.

WAITING_TXN

| The job is waiting for pre-existing write transactions to finish so it can establish a consistent starting point.

RUNNING

| The BEs are actively rewriting the data. This is typically the longest phase.

FINISHED_REWRITING

| Data rewrite is complete. The job is waiting for a final metadata transaction to publish the new version.

FINISHED

| Success. The new schema/structure is active.

CANCELLED

| The job failed or was stopped. Check the

Msg

column for the error reason. Summary Wait for

FINISHED

before resuming heavy production workloads. If you are just doing a small test insert, it likely won't hurt, but for large production tables,

FINISHED_REWRITING

is your signal to let the database "breathe" so it can finalize the change. References • sql-reference/sql-statements/table_bucket_part_index/SHOW_ALTER.md • faq/Sql_faq.md • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • faq/operation_maintenance_faq.md • sql-reference/sql-statements/loading_unloading/SHOW_LOAD.md

@Rocky ive noticed that sometimes i get an error like below when i try to insert data into a table where an alter table is in

FINISHED_REWRITING

state

A schema change operation is in progress on the table contacts. Please wait until the current operation completes. To check the status of the operation, see <https://docs.starrocks.io/docs/sql-reference/sql-statements/table_bucket_part_index/SHOW_ALTER>

When you see the error "A schema change operation is in progress" while trying to

INSERT

data into a table in the

FINISHED_REWRITING

state, it is because StarRocks has entered a critical "catch-up" phase where it must align the data versions. Here is why you are seeing this error and what it tells you about the table states. 1. What happens in

FINISHED_REWRITING

? Most

ALTER TABLE

operations (like adding columns or changing data types) are asynchronous. The process follows these stages: *

RUNNING

: The BEs are actively rewriting the data into new "shadow tablets." While this is happening, you can still insert data; StarRocks writes to both the old tablets and the shadow tablets to keep them in sync. *

FINISHED_REWRITING

: The bulk of the historical data rewrite is finished. Now, the FE (Frontend) is trying to close the version gap. It needs to apply any incremental data that arrived while the job was

RUNNING

and perform a final metadata swap to make the new schema live. *

FINISHED

: The metadata swap is complete. The shadow tablets are now the official tablets, and the old ones are discarded. 2. Why is your

INSERT

blocked? Even though StarRocks is designed to allow concurrent writes during most of the schema change, you will hit the "A schema change operation is in progress" error during

INSERT

in a few specific scenarios: * Primary Key Tables: For Primary Key tables, the final consistency check is much stricter. The system may block new write transactions briefly when it reaches the end of the rewriting phase to ensure no data is lost during the swap. * INSERT OVERWRITE: If you are using

INSERT OVERWRITE

, this is treated as a metadata operation (swapping partitions). StarRocks does not allow two metadata-altering operations (the schema change and the partition overwrite) to run concurrently. * Shared-Data (Lake) Mode: In newer StarRocks versions using the shared-data architecture, there is a strict "version continuity" check. If there are too many concurrent inserts, the

ALTER

job cannot get a "quiet" version number to finalize the metadata, and the system may block new inserts to let the

ALTER

job finish. * Version Catch-up Lag: If your table has a very high ingestion rate (e.g., a high-frequency Routine Load), the

ALTER

job can get "stuck" in

FINISHED_REWRITING

because it can never catch up to the latest version. In this state, the FE may temporarily reject new transactions to force a completion. 3. Summary of States to Watch State | Can you INSERT? | What to do?

RUNNING

| Yes | Normal operation; StarRocks handles double-writing to shadow tablets.

FINISHED_REWRITING

| Limited/No | Pause or slow down your loads. This is the most common place for jobs to get stuck if ingestion is too heavy.

FINISHED

| Yes | Success. Resume full-speed production workloads.

CANCELLED

| Yes | The table has reverted to its original schema. Check

Msg

for why it failed. Recommendation If you see the

FINISHED_REWRITING

state and start getting "operation in progress" errors on your

INSERT

statements: 1. Pause your Routine Load or Stream Load for 30–60 seconds. 2. Wait for

SHOW ALTER TABLE COLUMN

to show the state as

FINISHED

. 3. Resume your loads. This "breathing room" allows the FE to finalize the metadata transaction and swap the table versions without competing for locks with your incoming data. References • sql-reference/sql-statements/table_bucket_part_index/SHOW_ALTER.md • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • faq/Sql_faq.md • loading/InsertInto.md References

@Rocky are reads fully available during an ALTER TABLE?

Yes, reads are fully available and non-blocking during an

ALTER TABLE

operation in StarRocks. While the system is processing a schema change or rollup, it uses a "Shadow Tablet" mechanism to ensure that your existing queries are not interrupted. Here is how it works under the hood: 1. How Reads Remain Available When you trigger an asynchronous

ALTER

(like

ADD COLUMN

), StarRocks does not modify the existing data files. Instead: * Shadow Tablets: It creates a new set of "shadow" tablets that will eventually hold the new schema. * Base Tablets: Your queries continue to read from the original "base" tablets. Since the base tablets are never locked for reading, your BI tools and applications will see no downtime. 2. Which Schema Do Reads See? The schema seen by your queries depends on the job state: * PENDING / RUNNING / FINISHED_REWRITING: Queries will continue to see and use the old schema. Even if you added a column, you cannot

SELECT

that column yet; it doesn't "exist" for the query engine until the job is finalized. * FINISHED: Once the state reaches

FINISHED

, the FE (Frontend) performs an atomic metadata swap. From this point forward, all new queries will see the new schema. 3. Is There Any Blocking at All? The only "blocking" that occurs is during the final metadata swap (the transition from

FINISHED_REWRITING

to

FINISHED

). This is a pure metadata operation in the FE and usually takes only a few milliseconds. * Read impact: Negligible. A query hitting the table at the exact millisecond of the swap might experience a tiny sub-second pause, but it will not fail. * Write impact: As discussed previously, writes are more sensitive during the

FINISHED_REWRITING

phase because the system needs to "catch up" on data versions before it can safely swap. Summary Table for Read Availability State | Read Availability | Which Schema?

RUNNING

| Fully Available | Old Schema

FINISHED_REWRITING

| Fully Available | Old Schema

FINISHED

| Fully Available | New Schema In short: You can safely perform schema changes on large production tables without worrying about blocking your end-user queries. The system is designed to favor read availability at all times. References • faq/Sql_faq.md • using_starrocks/caching/query_cache.md • faq/operation_maintenance_faq.md • best_practices/query_tuning/schema_tuning.md • knowledge/admin_and_operation/shared_data_compaction.md

@Rocky what are best practices for schema evolution? my tables have regular writes which i dont want to fail, but over time we will need the ability to update our schemas. it seems like ALTER TABLE will be a pain to manage (all writes will need to be paused). is there some alternative thats recommended? this is in shared-data mode

For schema evolution in shared-data mode (StarRocks v3.0+), the best practices have evolved significantly to minimize or even eliminate write failures. Here are the recommended strategies depending on your version and the type of change you are making. 1. The "Golden Standard": Fast Schema Evolution v2 (v4.1+) If you are on StarRocks v4.1 or higher, schema evolution for cloud-native tables is a "solved" problem. * Feature:

cloud_native_fast_schema_evolution_v2

(enabled by default for new tables). * How it works: It makes schema changes synchronous and near-instant. Instead of rewriting tablets or even metadata on S3, it only updates the metadata in the Frontend (FE). * Impact on Writes: There is no "catch-up" phase or

FINISHED_REWRITING

state. The

ALTER

statement returns success in milliseconds, and your next write immediately uses the new schema. 2. For v3.3.x to v4.0.x: Fast Schema Evolution If you aren't on v4.1 yet, StarRocks still offers Fast Schema Evolution (LSC) for adding or dropping columns. * Shared-data support: Enabled by default since v3.3.0. * How it works: It is still asynchronous, but it avoids rewriting the actual data files. It updates tablet metadata on S3. * Best Practice: To avoid the

INSERT

errors you saw during the catch-up phase: * Monitor the Job: Use

SHOW ALTER TABLE COLUMN

. * Graceful Ingestion: If you have high-frequency writes (e.g., Routine Load), the system might struggle to finalize the metadata swap. If it stays in

FINISHED_REWRITING

for more than a minute, pause your loads for 10 seconds. This gives the FE a "quiet window" to commit the final version without version conflict. 3. For "Heavy" Changes: The Blue-Green (Swap) Strategy If you need to change something structural that requires a full data rewrite (like changing the

DISTRIBUTED BY

key, the

ORDER BY

key, or a column data type that requires conversion), a standard

ALTER TABLE

will be slow and may block writes during the final swap. Alternative: Create-Insert-Swap 1. Create a new table (

new_table

) with the desired schema. 2. Sync the historical data:

INSERT INTO new_table SELECT * FROM old_table;

. 3. Catch up on recent data: Run incremental inserts or point your data loader to both tables briefly. 4. Atomic Swap: Use the

REPLACE

command:

sql
    ALTER TABLE old_table REPLACE WITH TABLE new_table;

This is an atomic metadata operation. It swaps the names of the tables instantly. Existing queries and writes against

old_table

will switch to the new structure with zero downtime. 4. General Best Practices * Prefer ADD over MODIFY: Adding a column is almost always a metadata-only "Linked Schema Change." Modifying a column type often triggers a "Direct Schema Change" (full rewrite). * Use Views for Abstraction: If you find yourself changing schemas often, point your application to a

VIEW

instead of the base table. You can then use the "Swap Strategy" above and just update the view definition to point to the new table when ready. * Check `RENAME COLUMN`: Since v3.3.2, you can rename columns without a table rewrite. This is a metadata-only change.

sql
    ALTER TABLE my_table RENAME COLUMN old_name TO new_name;

Summary Recommendation If your priority is zero write failure, upgrade to v4.1 to get Fast Schema Evolution v2. If that's not possible, use the

ALTER TABLE ... REPLACE WITH TABLE

strategy for major changes, as it provides the most control over when the "switch" happens without the risk of an asynchronous job getting stuck in a catch-up loop. References • best_practices/query_tuning/schema_tuning.md • faq/operation_maintenance_faq.md

@Rocky when will the

cloud_native_fast_schema_evolution_v2

feature be released? is there a date?

The feature

cloud_native_fast_schema_evolution_v2

is part of StarRocks version 4.1. As of April 2026, this feature is currently available. The Release Candidate (v4.1.0-RC) was released on February 28, 2026, making it the current standard for high-performance schema evolution in shared-data (cloud-native) clusters. Why this solves your problem: This feature fundamentally changes how

ALTER TABLE

works for cloud-native tables. Instead of an asynchronous process that rewrites tablet metadata or data files, it becomes a synchronous, metadata-only operation in the Frontend (FE). * Latency: Schema changes take seconds, regardless of how many tablets or partitions you have. * Write Availability: Because it is synchronous and near-instant, there is no

FINISHED_REWRITING

state to get stuck in. When the

ALTER

statement returns, the new schema is live, and your writes can continue immediately without version conflict errors. * Materialized Views: This version also extends fast schema evolution support to Materialized Views. How to use it in v4.1: * New Tables: It is enabled by default for all new cloud-native tables created in a v4.1 cluster. * Existing Tables: For tables created in older versions (e.g., v3.x or v4.0), you must manually enable it after upgrading to v4.1:

sql
    ALTER TABLE <table_name> SET ("cloud_native_fast_schema_evolution_v2" = "true");

* Verification: You can check the status of your schema changes using:

sql
    SHOW ALTER TABLE COLUMN;

In v4.1 with this feature enabled, jobs will typically show as

FINISHED

almost immediately. Recommendation If your workload requires frequent schema updates alongside heavy, non-stop writes, upgrading to v4.1 is the best path forward. It eliminates the "catch-up" phase that caused the "operation in progress" errors you encountered in previous versions. References • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md • release_notes/release-3.3.md • administration/management/FE_configuration.md • best_practices/query_tuning/schema_tuning.md • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • loading/InsertInto.md References • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md • release_notes/release-3.5.md • administration/management/FE_configuration.md • release_notes/release-3.1.md • release_notes/release-3.2.md • release_notes/release-2.5.md

@Rocky when will 4.1 be officially released (not just candidate)?

StarRocks version 4.1.0-RC (Release Candidate) was officially released on February 28, 2026. As of April 2026, the version is in its Release Candidate phase. In the StarRocks lifecycle, a "General Availability" (GA) release typically follows the RC by roughly 4 to 8 weeks, depending on the feedback and stability of the candidate version. Expected GA Timeline Based on the current date (April 10, 2026) and the February 28 RC date: * Target: You can expect the official GA release in late April or early May 2026. * Current Stable Branch: The v4.0.x branch is the current stable production series (with v4.0.8 released on March 25, 2026). Why v4.1 Matters for Your Use Case The

cloud_native_fast_schema_evolution_v2

feature you are looking for is the headline feature of v4.1. Because it is already in the RC version, the code for this feature is functionally complete and is currently undergoing final production-hardening. Recommendation: If you have a non-production or staging environment, you can download the 4.1.0-RC today to test how the new fast schema evolution handles your specific write patterns. For mission-critical production clusters, it is generally best to wait for the GA announcement, which should be imminent. References • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • release_notes/release-3.3.md • best_practices/query_tuning/schema_tuning.md • administration/management/FE_configuration.md • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md • release_notes/release-3.5.md