Mutation

Mutations insert, update, and delete edges. The process ensures consistency, durability, and write-time optimization.

See Core Concepts for background.

Mutation Flow

flowchart TD
    Request([Mutation Request
with Event, Operation]) --> WAL[Write WAL]
    WAL --> Lock[Acquire Lock]
    Lock --> Read[Read State
from storage]
    Read --> Modify{State exists?}
    Modify -->|Yes| ApplyEvent[Apply Event]
    Modify -->|No| InitialState[Initial State]
    InitialState --> ApplyEvent
    ApplyEvent --> ComputeAdditionalInfo[Compute Index, Count
based on changed States]
    ComputeAdditionalInfo --> Write[Write State with AdditionalInfo
to storage]
    Write --> Release[Release Lock]
    Release --> CDC[Write CDC]
    CDC --> Response([Response])

Mutation Request

A mutation request contains:

• Event: The data change (e.g., new property values, edge creation)
• Operation: Insert, Update, or Delete

Mutation Process

1. Write WAL

Mutation is written to WAL before changes are made. Enables recovery and replay.

In production, Kafka is used as WAL backend.

2. Acquire Lock

Prevents concurrent modifications:

• Unique edges: Lock on (source, target)
• Multi edges: Lock on edge ID

3. Read State

Read current state from storage—properties, timestamps, metadata.

4. Apply Event

Transition state based on operation and client timestamp. See State Transitions for details.

5. Compute Indexes and Counters

Based on changed state:

• Indexes: Delete old, create new
• Counters: Increment or decrement

6. Write to Storage

State, indexes, and counters written atomically.

7. Release Lock

Lock released after write.

8. Write CDC

Mutation recorded in CDC (Kafka in production). Resulting state available for downstream systems.

State Transitions

Edges transition between states based on operations (INSERT, DELETE). Each event carries a client timestamp, and Actionbase uses these timestamps to compute the correct final state—even for out-of-order arrivals and duplicate requests (idempotent).

See State.transit for implementation.

Diagram

flowchart LR
    INITIAL[["INITIAL: No Edge"]]
    ACTIVE(["ACTIVE: Edge Exists"])
    INACTIVE["INACTIVE: Edge Deleted"]

    INITIAL -->|"INSERT / +1"| ACTIVE
    INACTIVE -->|"INSERT / +1"| ACTIVE
    ACTIVE -->|"DELETE / -1"| INACTIVE

Full state transition diagram

Edit on PlantUML

Example: Out-of-Order Events

Alice’s actions: like(t=100) → unlike(t=200) → like(t=300)

Events arrive out of order: like(t=100) → like(t=300) → unlike(t=200)

#	Event Arrives	State	Count Change	Total
1	like (t=100)	INITIAL → ACTIVE	+1	1
2	like (t=300)	ACTIVE → ACTIVE	0	1
3	unlike (t=200)	ACTIVE → ACTIVE	0	1

Final state: ACTIVE, count: 1 — same result regardless of arrival order.

Write-Time Optimization

During mutations, Actionbase pre-computes:

Structure	Purpose	Query Type
EdgeState	Current edge state	GET
EdgeIndex	Sorted entries	SCAN
EdgeCounter	Aggregated counts	COUNT

Reads use simple GET, COUNT, SCAN without query-time computation.

Consistency Guarantees

Mechanism	Guarantee
Locking	Prevents concurrent modifications
Atomic Writes	State and indexes written together
WAL	Durability and recovery
Read-Modify-Write	Mutations based on latest state
State Transitions	Correct final state despite event arrival
Idempotency	Replay produces same result

Next Steps

• Query: Read pre-computed data
• Mutation API: API reference