Mastering Performance Tuning in ClickHouse: Tips for Inspecting Statistics Objects

Inspecting statistics objects in ClickHouse is a pivotal activity for database administrators and data engineers aiming to optimize performance and troubleshoot issues. ClickHouse, renowned for its speed and efficiency in processing large volumes of data, offers a variety of tools and system tables that provide insights into the database’s inner workings. Here are several tips and tricks for leveraging these resources effectively:

1. Utilize System Tables

ClickHouse’s system tables store a treasure trove of metadata and runtime statistics that can be invaluable for performance tuning:

  • system.query_log: This table records details about executed queries, including execution times, read rows, memory usage, and whether the query resulted in an error. Analyzing this log can help identify slow-running queries and potential optimizations.
SELECT query, elapsed, read_rows, exception FROM system.query_log WHERE type = 'QueryFinish' ORDER BY elapsed DESC LIMIT 10;

  • system.metrics, system.asynchronous_metrics, and These tables provide real-time metrics on the server’s health and performance, such as the number of active queries, memory usage, and the number of processed rows and bytes. Tracking these metrics can help diagnose performance bottlenecks.
SELECT * FROM system.metrics WHERE metric LIKE '%Memory%';

2. Monitor and Analyze Merge Operations

Merges are a critical part of ClickHouse’s background activity, especially for tables using the MergeTree family of engines. Excessive or inefficient merge operations can lead to performance issues:

  • system.merges: Offers insights into ongoing merge operations, including which tables are being merged, the number of rows and bytes processed, and the duration of merge operations.
SELECT database, table, elapsed, progress FROM system.merges;

Observing this table can help identify if merges are consuming too many resources or taking too long to complete.

3. Inspect Parts and Partitions

Understanding how data is distributed across parts and partitions can help in optimizing data storage and access patterns:

  • Contains information about the data parts in MergeTree tables, including their size, number of rows, and disk space used. Large numbers of small parts can indicate suboptimal insert patterns, while large parts might suggest potential issues with partitioning strategies.
SELECT table, partition, name, rows, data_compressed_bytes FROM WHERE active ORDER BY data_compressed_bytes DESC LIMIT 10;

4. Evaluate Index Usage

Indexes play a crucial role in optimizing query performance by reducing the amount of data scanned:

  • system.query_log can also be used to analyze how indexes are leveraged in queries. Look for queries with high read rates but low efficiency, indicating potential areas where index optimization could be beneficial.

5. Use the EXPLAIN Statement

For specific queries that are performing poorly, use the EXPLAIN statement to understand how ClickHouse plans to execute the query. This can reveal whether indexes are being used effectively and if any unnecessary full-table scans are occurring.

EXPLAIN SYNTAX SELECT * FROM my_table WHERE column = 'value';

6. Profile Queries for Detailed Insights

  • system.query_thread_log: Contains detailed execution statistics for each thread involved in query execution, offering a deeper dive into query performance at the thread level.
SELECT query_id, query_duration_ms, read_rows, read_bytes FROM system.query_thread_log ORDER BY query_duration_ms DESC LIMIT 10;

7. Regular Housekeeping

Regular maintenance tasks like optimizing table structures, cleaning up old data, and revisiting indexing strategies based on the insights gathered from system tables can significantly improve overall performance.


Effectively inspecting statistics objects in ClickHouse is both an art and a science, requiring a deep understanding of the system’s behavior under various workloads. By leveraging the system tables and employing strategic query analysis, administrators can significantly enhance the performance and stability of ClickHouse deployments, ensuring that the database remains responsive and efficient, even as data volumes and query complexities grow.

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.