Troubleshooting Guide

OOM (Out of Memory)

Diagnosis: system.query_log WHERE memory_usage is high. system.metrics WHERE metric = 'MemoryTracking'.

Solutions:

• max_memory_usage per query (e.g., 10GB), max_memory_usage_for_user per user
• max_bytes_before_external_group_by / max_bytes_before_external_sort for spill-to-disk
• Reduce JOIN sizes with pre-filtering; use SAMPLE for approximate aggregations

Slow Merges

Diagnosis: system.merges — check elapsed, progress, total_size_bytes_compressed. system.part_log WHERE event_type = 'MergeParts' for throughput. Too many parts: max_parts_count_for_partition in system.asynchronous_metrics.

Solutions:

• Increase background_pool_size (default: 16)
• Check disk I/O via system.asynchronous_metrics (ReadBufferFromFileDescriptorReadBytes)
• Batch larger inserts to reduce frequency; avoid excessive partitioning
• OPTIMIZE TABLE ... FINAL to force merge (expensive, off-peak only)