# Mutations (/docs/concepts/mutations)



Mutations [#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 [#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](/docs/reference/sql/statements/alter-table) and
[ClickHouse compatibility and API scope](/docs/reference/clickhouse-compatibility).

Progress, completion, and failure [#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 [#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](/docs/guides/operate/mutations)
contains the inspection and cancellation procedure.

Related [#related]

* [Storage and compute](/docs/concepts/storage-and-compute)
* [Projections](/docs/concepts/projections)
* [Sorting keys](/docs/concepts/sorting-keys)
* [KILL MUTATION statements](/docs/reference/sql/statements/kill-mutation)