Struct Mutation 

pub struct Mutation {
    pub table: TableId,
    pub partition_key: PartitionKey,
    pub clustering_key: Option<ClusteringKey>,
    pub operations: Vec<CellOperation>,
    pub timestamp_micros: i64,
    pub ttl_seconds: Option<u32>,
    pub partition_tombstone: Option<PartitionTombstone>,
    pub range_tombstones: Vec<RangeTombstone>,
    pub local_deletion_time: Option<i32>,
    pub row_tombstone: Option<(i64, i32)>,
    pub cell_write_timestamps: Option<HashMap<String, i64>>,
}

A mutation represents a write operation (INSERT, UPDATE, DELETE)

This is the fundamental unit of write operations in CQLite, corresponding to a single CQL INSERT/UPDATE/DELETE statement. Each mutation targets a specific row (identified by partition key + optional clustering key) and contains one or more cell operations.

Tombstone Support (M5.2)

Mutations can represent various deletion types:

• Cell tombstone: CellOperation::Delete for single column
• Row tombstone: CellOperation::DeleteRow for entire row
• Range tombstone: range_tombstones field for clustering key ranges
• Partition tombstone: partition_tombstone field for entire partition

Fields

table: TableId

Target table

partition_key: PartitionKey

Partition key values

clustering_key: Option<ClusteringKey>

Clustering key values (None for tables without clustering keys)

operations: Vec<CellOperation>

Cell-level operations (writes or deletes)

timestamp_micros: i64

Timestamp in microseconds since Unix epoch

ttl_seconds: Option<u32>

Time-to-live in seconds applied to all cells in this mutation (None = no expiration).

This is set by USING TTL in CQL statements and applies uniformly to all Write operations. For per-column TTL, use CellOperation::WriteWithTtl in the operations list instead.

partition_tombstone: Option<PartitionTombstone>

Partition tombstone (deletes entire partition)

range_tombstones: Vec<RangeTombstone>

Range tombstones (delete clustering key ranges within partition)

local_deletion_time: Option<i32>

Explicit local deletion time (seconds since Unix epoch) for the row and cell tombstones (DeleteRow, Delete) produced by this mutation.

None (the default) preserves historical behavior: the writer derives the local deletion time from timestamp_micros (timestamp_micros / 1_000_000). When Some(ldt), the writer emits exactly ldt as the localDeletionTime of every row/cell tombstone in this mutation, and feeds it into the Statistics.db min/max localDeletionTime aggregates.

Partition and range tombstones carry their own local_deletion_time inside PartitionTombstone / RangeTombstone and are unaffected by this field. (Issue #764)

row_tombstone: Option<(i64, i32)>

Row-level deletion that COEXISTS with the live cells produced by this mutation’s operations (issue #932).

Some((deletion_time_micros, local_deletion_time_secs)) carries a row tombstone whose deletion_time is DECOUPLED from timestamp_micros — it is older than the row’s surviving cells (whose own writetimes drive timestamp_micros). The writer emits a HAS_DELETION row carrying BOTH the deletion AND the surviving cells, so older cells of OTHER columns in SSTables not part of a partial compaction stay shadowed (they cannot resurrect). This is distinct from a CellOperation::DeleteRow, whose deletion time IS the mutation timestamp; row_tombstone is used only on the compaction merge→mutation path where the two diverge.

None (the default) preserves historical behavior: a row deletion, when present, rides as CellOperation::DeleteRow at timestamp_micros.

cell_write_timestamps: Option<HashMap<String, i64>>

Per-column write timestamps (microseconds) for the simple-cell Write/WriteWithTtl operations of this mutation (issue #1018).

CellOperation::Write/WriteWithTtl carry no per-cell timestamp — every such cell historically inherits the row’s single timestamp_micros. On the compaction merge→mutation path a reconciled row can hold sibling cells at DIFFERENT writetimes (e.g. live name@100 alongside a score cell tombstone@300). Promoting every live cell to the row’s MAX writetime would rewrite name’s writetime to 300, losing fidelity. This side-channel maps a regular column name → that cell’s OWN write timestamp so the writer emits it verbatim (clearing USE_ROW_TIMESTAMP when it differs from the row marker).

None / absent column (the default) preserves historical behavior: the cell inherits timestamp_micros. Populated only by merge_entry_to_mutation; the WAL / CQL-INSERT paths leave it unset (their cells genuinely share one writetime). #[serde(default)] keeps backward compatibility with mutations serialized before this field existed.

Implementations

impl Mutation

pub fn new( table: TableId, partition_key: PartitionKey, clustering_key: Option<ClusteringKey>, operations: Vec<CellOperation>, timestamp_micros: i64, ttl_seconds: Option<u32>, ) -> Self

Create a new mutation

pub fn cell_write_timestamp(&self, column: &str) -> i64

Per-cell write timestamp (microseconds) for column, falling back to the mutation’s row timestamp_micros when no per-cell override was supplied (issue #1018). Used by the writer to decide whether a simple cell keeps USE_ROW_TIMESTAMP or carries its own explicit delta.

pub fn with_row_tombstone(self, deletion_time: i64, ldt: i32) -> Self

Attach a row-level deletion that coexists with this mutation’s live cells (issue #932).

deletion_time is in microseconds (markedForDeleteAt); ldt is the localDeletionTime in GC-clock seconds. The writer emits a HAS_DELETION row carrying both the deletion and the surviving cells, decoupling the deletion time from timestamp_micros (the row’s liveness writetime).

pub fn with_local_deletion_time(self, local_deletion_time: i32) -> Self

Set an explicit local deletion time (seconds since Unix epoch) for the row/cell tombstones produced by this mutation (Issue #764).

When unset, the writer derives the local deletion time from timestamp_micros exactly as it did historically.

pub fn effective_local_deletion_time(&self) -> i32

Local deletion time (seconds since Unix epoch) to stamp on the row/cell tombstones of this mutation, falling back to the timestamp-derived value when no explicit value was supplied (Issue #764).

pub fn decorated_key(&self, schema: &TableSchema) -> Result<DecoratedKey>

Get the decorated key for this mutation (token + raw bytes)

Trait Implementations

impl Clone for Mutation

fn clone(&self) -> Mutation

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Mutation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Mutation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Mutation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.