ClickHouse Replication: Understanding High Watermark Mechanism for Horizontal Scaling

Understanding the High Watermark Mechanism in ClickHouse for Data Replication

Table of Contents


In ClickHouse, the term “high watermark” refers to a mechanism used to track the progress of data replication in a distributed environment. It helps ensure data consistency and integrity across multiple replicas of a ClickHouse database.

When data is replicated in ClickHouse, it is sent from the leader replica (also known as the “leader” or “master” replica) to the follower replicas (also known as “replicas” or “slaves”). The high watermark is a position marker that indicates the maximum replicated position up to which all the data has been successfully replicated to the follower replicas.

Here’s how the high watermark works in ClickHouse:

  1. Replication Log:
    • ClickHouse maintains a replication log on the leader replica, which contains a sequence of events representing data changes.
    • Each event in the replication log is associated with a position value, which is a unique identifier indicating the position of the event in the log.
  2. Replication Process:
    • When data changes occur on the leader replica, ClickHouse appends the corresponding events to the replication log and sends them to the follower replicas.
    • Follower replicas receive the replication events and apply them to their local database copies to synchronize the data.
  3. High Watermark:
    • The high watermark is a position value that represents the maximum replicated position across all the replicas.
    • It indicates the point up to which all the data changes have been successfully replicated to the follower replicas.
    • The high watermark is periodically updated as new events are replicated and applied on the follower replicas.
  4. Data Consistency:
    • The high watermark is used to ensure data consistency and integrity across the replicas.
    • Before committing new transactions or making data changes on the leader replica, ClickHouse checks whether the high watermark on the follower replicas has caught up with the leader’s position.
    • This ensures that all replicas have successfully applied the previous data changes before proceeding with new changes, preventing data inconsistencies.

The high watermark mechanism in ClickHouse helps maintain data consistency in distributed environments by ensuring that all replicas have received and applied the same set of data changes up to a specific position. It serves as a synchronization point and allows ClickHouse to guarantee data integrity across replicas.

Note that the high watermark is specific to ClickHouse’s replication mechanism and should not be confused with high watermarks used in other contexts, such as in database storage or memory management.


ClickHouse’s high watermark mechanism plays a crucial role in maintaining data consistency and integrity across distributed replicas, ensuring synchronization and preventing data inconsistencies during replication processes. Its periodic updates and synchronization checks facilitate reliable replication and support robust data management in distributed environments.

To read more about replication in ClickHouse, do read the following articles:

ChistaDATA: Your Trusted ClickHouse Consultative Support and Managed Services Provider. Unlock the Power of Real-Time Analytics with ChistaDATA Cloud – the World’s Most Advanced ClickHouse DBaaS Infrastructure. Contact us at or (844)395-5717 for tailored solutions and optimal performance.

About Shiv Iyer 227 Articles
Open Source Database Systems Engineer with a deep understanding of Optimizer Internals, Performance Engineering, Scalability and Data SRE. Shiv currently is the Founder, Investor, Board Member and CEO of multiple Database Systems Infrastructure Operations companies in the Transaction Processing Computing and ColumnStores ecosystem. He is also a frequent speaker in open source software conferences globally.