ClickHouse Troubleshooting: Why is ClickHouse Index Underutilized?


If a ClickHouse index is not being utilized for existing data, leading to full table scans even after creating the index, several factors could be at play. Understanding these can help in troubleshooting and ensuring that indexes are used effectively. Here are some possible causes.

Runbook to Troubleshoot Underutilized ClickHouse Indexes

1. Improper Index Type or Configuration

  • Mismatched Index Type: The type of index created might not be suitable for the queries being executed. For instance, using a min-max index when a bloom filter would be more appropriate.
  • Incorrect Columns in Index: The index might not include the right columns or the columns used in the query’s filter conditions.

2. Index Granularity Issues

  • Granularity Too High: If the granularity of the index is set too high, it might not be efficient in filtering out data blocks, leading to more rows being scanned.

3. Query Not Optimized for Index Usage

  • Complex Query Conditions: Sometimes, the way a query is written or the complexity of its conditions can prevent the effective use of indexes.
  • Use of Non-Deterministic Functions: Queries with non-deterministic functions or complex calculations in the WHERE clause might not leverage indexes effectively.

4. Data Distribution and Skew

  • Uniform Data Distribution: If the data is uniformly distributed, skip indexes might not be as effective in reducing the dataset to be scanned.
  • Data Skew: Extreme skew in data distribution can sometimes lead to ineffective index utilization.

5. Index Creation on Large Datasets

  • Delayed Index Building: In some cases, especially with very large datasets, the index might take time to be fully built and become effective.

6. System and Configuration Constraints

  • Resource Limitations: Limited system resources (CPU, memory, I/O bandwidth) can affect the efficiency of index building and utilization.
  • Configuration Settings: Certain ClickHouse settings might influence index usage, such as settings related to memory allocation for query execution.

7. Version and Feature Support

  • ClickHouse Version: Older versions of ClickHouse might have limitations or bugs affecting index usage. Ensure that you are using a recent version with the latest fixes and improvements.

8. Incorrect Expectations or Misinterpretation

  • Misinterpretation of Query Plan: Sometimes, it might seem like an index is not being used when, in fact, it is. Use EXPLAIN to understand the query plan better.

Troubleshooting Tips


When a ClickHouse index is not being utilized as expected, it’s important to review the index configuration, query design, data characteristics, and system settings. Often, a combination of refining the index, optimizing the query, and ensuring adequate resources can resolve issues related to index utilization.

To read more on troubleshooting ClickHouse Indexes:

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