ClickHouse Troubleshooting: Avoiding Excessive Disk Swaps

ClickHouse Swapping


Disk swapping is a technique used by operating systems to manage memory usage when the amount of available physical memory is limited. When the operating system runs out of available physical memory, it uses a portion of the hard disk to temporarily store data that would normally be held in memory.

When a program needs to access data that is currently swapped out to disk, the operating system moves that data back into memory and swaps out other data to make room. This process is known as paging. The time required to swap data in and out of memory can significantly impact system performance, particularly if the disk is slow or heavily utilized.

Disk swapping is typically used as a last resort when there is not enough physical memory available to satisfy the demands of running programs. In modern systems, disk swapping is less common due to the availability of larger amounts of physical memory and the use of techniques such as memory compression to improve memory utilization. However, in some cases, such as when running large memory-intensive applications, disk swapping may still be necessary to ensure that the system can continue to function.

When ClickHouse swaps on disk?

ClickHouse uses memory-mapped files to store data in memory, and it is designed to handle large data sets that may not fit entirely in memory. When the amount of data that needs to be processed exceeds the available memory, ClickHouse may start swapping data to disk.

ClickHouse swaps data to disk when the following conditions are met:

  1. Memory pressure: When the amount of data that needs to be processed exceeds the available memory, ClickHouse will start swapping data to disk to make room for new data.
  2. Memory-mapped file limitations: ClickHouse uses memory-mapped files to store data in memory. Memory-mapped files have certain limitations, such as a maximum size and a maximum number of files that can be mapped at once. When these limitations are reached, ClickHouse will start swapping data to disk.
  3. Query complexity: Some complex queries may require more memory than is available, causing ClickHouse to swap data to disk.

ClickHouse is optimized for handling large data sets and can perform well even when swapping to disk. However, swapping can have an impact on performance, particularly if the disk is slow or if there is a large amount of data being swapped. To avoid excessive swapping, it is important to properly size the ClickHouse cluster and monitor memory usage to ensure that there is enough available memory to handle the workload. Additionally, it may be necessary to adjust configuration settings to optimize performance in specific use cases.

How to configure ClickHouse to avoid swapping?

To configure ClickHouse to avoid swapping, you can follow these steps:

  1. Allocate enough RAM: ClickHouse is optimized for in-memory processing, so it is essential to allocate enough RAM to the system. The amount of RAM required will depend on the size of the data being processed and the complexity of the queries being executed. It is recommended to allocate at least 2-4 times the amount of RAM required to store the data in memory.
  2. Adjust the max memory usage settings: ClickHouse provides several parameters that can be used to adjust the maximum memory usage. These include max_memory_usage, max_memory_usage_for_all_queries, and max_query_size. These parameters can be set to limit the amount of memory that a query can use and prevent memory usage from exceeding the available memory.
  3. Use memory quotas: ClickHouse allows for fine-grained control of memory usage through memory quota settings. These settings can be used to limit the amount of memory that a user or group of users can use, and to ensure that there is enough memory available for critical operations.
  4. Use appropriate data types: ClickHouse supports a wide range of data types, and choosing the appropriate data types for the data being processed can help reduce memory usage and improve performance.
  5. Use compression: ClickHouse supports several compression algorithms that can be used to reduce the amount of memory required to store data. For example, the gzip or lz4 compression algorithms can be used to compress data before it is written to disk.
  6. Monitor resource usage: It is important to regularly monitor resource usage to ensure that there is enough available memory and disk space to handle the workload. You can use ClickHouse’s built-in monitoring tools or third-party monitoring tools to monitor resource usage and identify bottlenecks.

By following these steps, you can configure ClickHouse to avoid swapping and ensure optimal performance for your workload.

Monitoring ClickHouse Swapping 

To monitor swapping in ClickHouse, you can run the following SQL script:

FROM system.processes
WHERE swap_memory_usage > 0
ORDER BY swap_memory_usage DESC

This script will return a list of all currently running queries in ClickHouse that are using swap memory. The output will include the query ID, user, current memory usage, memory limit, swap memory usage, and swap memory limit.


If you run this script periodically, you can monitor the swapping behavior of ClickHouse and identify queries that are causing excessive swapping. You can then analyze these queries and optimize them to reduce their memory usage and improve performance.

To read more about troubleshooting in ClickHouse, do consider reading the following articles

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.