After a SQL deployment is running, its query is immutable. To change the query logic, stop the deployment, update the SQL, and restart — with or without preserving state depending on whether the change is state-compatible.
Choose an approach
Choose an approach based on whether your SQL change is state-compatible:
|
Approach |
When to use |
|
Stop, update, and restart with state |
The SQL change is state-compatible (see the State compatibility reference section below) |
|
Stop, update, and restart without state |
The SQL change is state-incompatible, or state loss is acceptable |
Prerequisites
Before you begin, make sure you have:
A deployment in the Running state
Permissions to stop and start the deployment
(Required for stateful restarts) A savepoint or checkpoint available for the deployment
Restart with state
Use this approach when your SQL change is state-compatible. The job resumes from a savepoint and does not reprocess historical data.
On the Deployments page, find the target deployment and click Stop.
-
In the dialog, select Save current state as a savepoint and confirm.
WarningFlink restores operator state from the savepoint, but cannot roll back writes already emitted to external systems. If the job ran after the savepoint was taken, the restarted job may re-emit the same records. Whether this is safe depends on your sink:
Idempotent sinks (for example, upserts to a key-value store): duplicate writes are typically harmless.
Append-only sinks (for example, a Kafka topic or a database table without a primary key): duplicate records are written and cannot be undone.
After the deployment reaches the Stopped state, click Edit and update the SQL.
Click Start, select Resume from savepoint, and choose the savepoint created in step 2.
Confirm that the deployment reaches the Running state.
Restart without state
Use this approach when the SQL change is state-incompatible, or when reprocessing from the beginning is acceptable.
On the Deployments page, find the target deployment and click Stop.
Wait until the deployment reaches the Stopped state.
Click Edit and update the SQL.
Click Start, then select Reset state to start from the beginning, or configure a source offset to start from a specific position in the upstream data stream.
Confirm that the deployment reaches the Running state.
State compatibility reference
State compatibility determines whether the new query can resume from the previous job's savepoint. The following table summarizes which changes are compatible with a stateful restart.
|
Change type |
State-compatible? |
Notes |
|
Modifying stateless operator logic (for example, updating a |
Yes |
Stateless operators carry no state, so the change does not affect savepoint compatibility. |
|
Adding a stateless operator |
Yes |
The new operator initializes with no state, which is valid. |
|
Removing a stateless operator |
Yes |
No state is lost. |
|
Adding a stateful operator (for example, a new aggregation or join) |
Partial |
The new operator starts with its default initial state. Existing operator states are preserved. |
|
Removing a stateful operator |
No — state lost |
The removed operator's state is discarded. If another operator does not absorb it, the state is permanently lost. |
|
Changing the data type of an operator's state |
No |
Flink cannot deserialize existing state into a different type. Reset state and reprocess. |
|
Changing the key of a keyed aggregation |
No |
The state is organized by the old key. A different key produces a different state partition structure. |
|
Replacing a source or sink connector |
Depends |
If the new connector is schema-compatible, the downstream operators may be preserved. Verify with a test deployment before proceeding. |
Assign explicit operator UIDs to all stateful operators in your SQL deployments. Flink derives default operator IDs from the operator's position in the job graph — if you modify the query, positions may shift and default IDs may change, making savepoint-based restarts impossible. With explicit UIDs, Flink can reliably match savepoint state to the correct operators even after query changes.
What's next
Overview of SQL deployments
Manage savepoints
Monitor deployment status