# clusterTime > Depth-first rabbithole dossier for clusterTime; source-anchored research pack. Parent: [Causal Consistency](https://llms-explorer.com/tree/causal-consistency/) · 3 facets · 19 facts · page: https://llms-explorer.com/tree/clustertime/ ## How it works - [medium] ClusterTime is incremented only when there is a write to a primary node's replication operation log (oplog), and every write or event that changes state is assigned a time when applied to the primary. Sources: https://mongodb.com/blog/post/casual-guarantees-anything-casual, http://muratbuffalo.blogspot.com/2024/04/implementation-of-cluster-wide-logical.html — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [medium] Cluster nodes (mongod, mongos, config server, clients) always track and include the greatest known ClusterTime when sending a message, a process called gossipping the cluster time. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/causal-consistency/causal-consistency.md, http://muratbuffalo.blogspot.com/2024/04/implementation-of-cluster-wide-logical.html — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] When a driver sends a non-SDAM command to a server, it MUST include the highest seen cluster time in a top-level field called $clusterTime, sending the greater of the clusterTime values from MongoClient and ClientSession. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/sessions/driver-sessions.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] A driver detects that it MUST participate in gossipping the cluster time when it sees a $clusterTime in a response received from a server, and if the new clusterTime is greater than the session's current clusterTime, the session's clusterTime MUST be advanced. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/sessions/driver-sessions.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] Cluster time is only used in replica sets and sharded clusters, and when connected to a deployment that does not support cluster times, messages sent to the server should not include $clusterTime. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/causal-consistency/causal-consistency.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] When connected to a deployment that does support cluster times, messages sent to the server should include $clusterTime, and the server reports its view of the current cluster time in the $clusterTime field in responses from the server. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/causal-consistency/causal-consistency.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] A driver MUST NOT use the clusterTime of a ClientSession anywhere else except when executing an operation with this session. Sources: https://raw.githubusercontent.com/mongodb/specifications/master/source/sessions/driver-sessions.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] There is no need to do session_b.advance_cluster_time(session_a.cluster_time) because the MongoClient already gossips the highest $clusterTime seen across all client sessions, but this automatic gossiping is not true for client sessions from different MongoClients. Sources: https://jira.mongodb.org/browse/DRIVERS-2860 — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` ## Problems, failure modes and limitations - [high] The advanceClusterTime method updates the cluster time tracked by the session with parameters for clusterTime and signature, but MUST NOT advance the clusterTime in MongoClient because the supplied clusterTime cannot be verified as valid. Sources: https://www.mongodb.com/docs/manual/reference/method/Session.md, https://raw.githubusercontent.com/mongodb/specifications/master/source/sessions/driver-sessions.md — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - Fact 50 states "Max has been called on to help in three (3) separate instances," which is unrelated to clusterTime and appears to be noise or an error in the source data. Sources: https://jira.mongodb.org/browse/DRIVERS-2860 — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#disagreements` ## Facts and statements - [high] MongoDB implements causal consistency using a hybrid logical clock based on the Lamport logical clock, called clusterTime, to partially order events across replica sets and sharded clusters. Sources: https://mongodb.com/blog/post/casual-guarantees-anything-casual, https://emptysqua.re/blog/how-to-use-mongodb-causal-consistency/, https://dev.to/franckpachot/read-your-writes-on-replicas-postgresql-wait-for-lsn-and-mongodb-causal-consistency-4he2, https://vkontech.com/causal-consistency-guarantees-in-mongodb-lamport-clock-cluster-time-operation-time-and-causally-consistent-sessions/ — source: `~/.global-ai-hub/research/.pipeline/mongodb-2026-10-14/frb/clustertime-81e292d900/rabbithole-synthesis.md#core` - [low] ClusterTime is represented by a