Replica
A replica is a copy of a partition held on another node for availability. The replication factor sets how many copies exist, and if a primary is lost, one of its replicas is promoted to take over.
What a replica is
Every partition is owned by one node at a time — its primary — which serves the partition's reads and writes. A replica is an additional copy of that same partition, kept on a different node as a hot standby. Writes land on the primary and stream to the replicas, so a replica stays close to the primary's state and can take over if the primary's node fails.
Copies of the same partition are always placed on different machines, so losing one machine can never take out both a primary and its replica.
The replication factor
The replication factor is the number of copies of each partition that exist — the primary plus its replicas. It is the main dial for availability under node loss, and you set it when you create a store; New-ZrStore requires it explicitly.
- Replication factor 1 — one copy, no replicas. Fast and compact, but a node loss means data loss. Use it only for caches you can rebuild.
- Replication factor 2 — a primary plus one replica. Survives one machine failure; this is the recommended value for production.
- Replication factor 3 — a primary plus two replicas. Survives two simultaneous machine failures.
For production the replication factor must not exceed the number of machines, so each copy can land on a different machine; on a single machine this is relaxed with a warning, which is acceptable for testing but provides no fault tolerance.
In configuration the replication factor's default value is 1 — a single copy with no replicas. New-ZrStore does not assume a default: you pass -ReplicationFactor explicitly when you create the store.
Primary versus replica
The distinction between a primary and a replica is about role, not about being a different kind of thing — both are copies of the same partition on different nodes.
- The primary is the authoritative copy. Writes always go to it, and reads go to it by default.
- A replica is a standby copy. It receives the primary's writes and is ready to be promoted. A store can opt in to replica reads (off by default) so read-heavy workloads can read from replicas, at the cost of possibly slightly staler data.
When the primary considers a write durable depends on the store's replication mode. In Async mode (the default) the primary acknowledges immediately and replicates in the background, so a replica can lag. In Sync mode the primary waits for replica acknowledgement per the write-quorum policy before returning.
Failover: what actually fails over
When a primary's node is lost, one of its replicas is promoted to primary and clients re-route to it after a map refresh. The cluster then rebuilds a fresh replica on a healthy machine to restore the configured replication factor. Until that rebuild completes, the partition is under-replicated.
It is the partition's primary role that fails over — moving from the lost node to a surviving replica — not the partition itself and not the node. The partition keeps its stable code-word name throughout, so you can follow it across the promotion.
With the default Async replication a replica can trail its primary. If the primary fails before the trailing writes replicate, those writes are lost on promotion. Use Sync replication when a failover must not lose recent writes.