Mutations
Understand background changes to existing table parts and their completion state.
Mutations
A mutation applies a change to data in existing table parts. It runs in the background, so accepting its command and completing its work are separate events.
For example, adding a projection defines a new layout. Materializing that projection creates a mutation that builds the layout for existing parts. New inserts and the backfill of older data have separate lifecycles.
What changes and when
Table metadata can change before all existing parts adopt the new state. A mutation processes those parts over time. A large table can therefore take longer to finish than the command request itself.
Merges and mutations both do background work, but they have different purposes. Merges combine parts. Mutations apply a requested transformation to existing parts, such as materializing a projection or index.
Mutation support does not mean that every row-update or deletion statement is available through the Query API. The API exposes selected table operations and rejects unsupported forms. See ALTER TABLE and ClickHouse compatibility and API scope.
Progress, completion, and failure
system.mutations describes the command, mutation identity, and completion
state. Pending work, completion, and cancellation are distinct outcomes.
A successful command response is not a substitute for the completion state.
A mutation consumes CPU, storage bandwidth, and space while it processes parts. It competes with queries, inserts, and other background work. The time needed depends on the amount of existing data and available resources.
A failed or interrupted operation can leave completed part changes alongside unfinished work. Treating the operation as one atomic rewrite would hide that partial progress.
Cancellation is not rollback
KILL MUTATION stops unfinished mutation work in the selected database.
It does not undo changes to parts that already completed. A completed mutation
cannot be cancelled.
The mutation identifier distinguishes one operation from other work on the same table. Its state helps determine whether work remains, failed, completed, or was cancelled. The Manage mutations guide contains the inspection and cancellation procedure.