Counters in Clusters

• This section describes Counter behaviors in a Cluster.

• How Counters are modified and replicated.
• How Counters are allowed to be modified concurrently without conflict.
• In which rare cases do Counter modifications "race" against each other.

Counter-Value Modification

Value Modification Flow

Each node manages its own portion of a Counter's total value, independently from other nodes.

In the following 3-nodes-cluster example:
- The total value of the "ProductLikes" Counter is 80.
- Each node independently manages a portion of this total.

Counter Name Node Tag Counter Value on this node
ProductLikes A 42
ProductLikes B 28
ProductLikes C 10

When a client modifies a Counter's value, only the portion of the Counter's value on the node this client writes to is modified. The Counter's values on the other nodes do not change.

In the following example:
- A client has used node B to increment ProductLikes by 5.
- Only node B's portion of the value is incremented.

Counter Name Node Tag Counter Value per node
ProductLikes A 42
ProductLikes B 33
ProductLikes C 10

Value Replication Flow

After modifying the Counter's value locally, a node replicates the new value to all other nodes.
This way each node is always kept updated with the values set for each Counter by all nodes.

In the following example:
- The `ProductLikes` Counter is incremented by 2 on node C.
- Node C sends the new node-C value (12) to nodes A and B.
- All nodes are updated with the same three values.

Counter Name Node Tag Counter Value per node
ProductLikes A 42
ProductLikes B 33
ProductLikes C 12

Note that only the Counter's value is replicated.
The document itself hasn't been modified and needs no replication.

When a client requests a Counter's value, it gets a single accumulated sum.

In the following example, a request for ProductLikes's value will yield 85.

Counter Name Node Tag Counter Value per node
ProductLikes A 42
ProductLikes B 33
ProductLikes C 10
Total Value: 42+33+10 = 85

Counter Name modification

Replication due to a Counter Name modification:

• As described in the Overview section, creating or deleting a Counter triggers a document change.
• As a result, the whole document, including the new Counter value, is replicated to all nodes in the database group.
Existing Counters aren't replicated, since they already exist on the other nodes and their values haven't changed.

Concurrent Modification

The same Counter can be concurrently modified by multiple clients.

As described in the Counters in a multi-node cluster section, each node manages its own portion of a Counter's value.
As a result:

• Clients can modify the same Counter concurrently.
• Nodes do not need to coordinate Counter modification with each other.
• Concurrent value modification cannot cause conflicts.
• Find more about Counters and conflicts in the Overview section.

Concurrent `Delete` and `Increment`

A sequence of Counter actions is cumulative, as long as it doesn't Delete the Counter.
When Delete is executed, the order of execution does matter.

• When Increment and Delete are called concurrently, their order of execution is unknown and the outcome becomes uncertain.
We can identify this behavior in two different scenarios:
• In a single-server system
• In a multi-node cluster

In a Single-Server System

Different clients may simultaneously request to Delete and Increment the same Counter.

• The result depends upon the server's order of execution.
• If Delete is executed last, the Counter will be permanently deleted.
• If Delete is executed before Increment, the Counter will be deleted but then re-created with the value of the Increment action as its initial value.

In a Multi-Node Cluster

Different nodes may concurrently Delete and Increment the same Counter.

• The outcome depends upon the order of replication.
• If the node that deleted the counter replicates the change last, the Counter will be permanently deleted.
• If the node that incremented the counter replicates the change last, the Counter will be deleted but then re-created with the value of the Increment action as its initial value.