ClickHouse Performance: Estimated & Actual Row Counts in Execution Plans


Understanding the difference between the estimated and actual number of rows in ClickHouse execution plans is crucial for query optimization and performance tuning.

Overview of Estimated & Actual Row Counts in ClickHouse

Here’s an overview of what these terms mean and how they can be used:

  1. Estimated Number of Rows

    • This is a prediction made by ClickHouse’s query planner about how many rows will likely be involved in each step of the query execution.
    • The estimation is based on statistics about the data, like the number of rows in a table, the distribution of values, and the presence of indexes.
    • It’s important to note that these are just estimates and can be inaccurate, especially if the underlying statistics are not up-to-date or if the data distribution is highly skewed.
  2. Actual Number of Rows

    • This refers to the real number of rows that were processed during the execution of the query.
    • The actual count is determined after the query is executed, reflecting what happened during the data processing.
  3. Discrepancies between Estimated and Actual Rows

    • A significant difference between the estimated and actual number of rows can indicate that the query planner’s assumptions about the data are not accurate.
    • This discrepancy can lead to suboptimal query plans, where the database might choose an inefficient path for executing the query.
  4. Implications for Performance Tuning

    • If you consistently notice a large gap between estimated and actual row counts, it may be a sign that you need to update table statistics. This can be done in ClickHouse using the OPTIMIZE table query with the FINALkeyword.
    • Understanding these differences can help in identifying bottlenecks or inefficiencies in query execution.
  5. Using Execution Plans

    • Analyze execution plans to understand how ClickHouse is processing your queries. Look for steps in the plan where the estimated row count diverges significantly from the actual count.
    • Execution plans can be obtained using the EXPLAIN statement in ClickHouse.
  6. Regular Monitoring and Maintenance

    • Regularly monitor the performance of your queries and the accuracy of row estimations.
    • Keep your ClickHouse instance updated and maintain your data distribution statistics to ensure that estimations remain as accurate as possible.


In summary, the estimated versus actual number of rows in ClickHouse execution plans can provide valuable insights into the effectiveness of the query planning process. By understanding and monitoring these metrics, you can identify potential issues in query performance and take steps to optimize your database configurations and queries.

To read more about SQL Engineering for ClickHouse Performance, do consider reading the following articles

About Shiv Iyer 215 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.