At a glance
Database Disk Usage % is the proportion of the data disk that ClickHouse has consumed: used space divided by total space, expressed as a percentage. It is the single most consequential capacity metric on the cluster because ClickHouse does not degrade gracefully when disk fills. When free space runs out, inserts and merges fail outright and the server can stop accepting writes. The card exists to give a DBA the runway to act (drop a partition, add a TTL, expand the volume) long before the disk hits the wall. The > 90% alert is the “act now” line.
Calculation
The headline is computed directly fromsystem.disks:
free_space and total_space per disk in bytes. On a single-disk default install there is one row (default); on a tiered storage setup (hot SSD plus cold object storage) there are multiple disks and the card reports the most pressured data disk, since that is the one that halts writes. The per-table attribution shown when you drill in comes from SELECT table, sum(bytes_on_disk) FROM system.parts WHERE active GROUP BY table, which tells you which table is eating the volume. Note the distinction: bytes_on_disk is the compressed on-disk size (what fills the volume), not the uncompressed logical data size.
Worked example
A telemetry platform stores raw device events in ClickHouse on a 2 TB SSD volume. On 22 Mar 26 a new customer is onboarded and their backfill begins. At 14:00 the disk gauge reads a comfortable 64%; by 17:20 it has climbed to 91% and the> 90% alert fires.
The on-call DBA drills into the per-table attribution:
events_raw will begin failing before that because a merge of a large part needs temporary free space to write the merged output. The DBA has three levers:
- Shed data with a partition drop.
events_rawis partitioned by day. Dropping partitions older than the retention window withALTER TABLE events_raw DROP PARTITION '...'reclaims space instantly (a partition drop is a metadata operation, not a slow delete). This is the fastest relief. - Add a TTL so the problem does not recur:
ALTER TABLE events_raw MODIFY TTL event_date + INTERVAL 30 DAY. This is the durable fix, not the firefight. - Expand the volume. On self-managed, grow the underlying block device and let the filesystem extend. On ClickHouse Cloud, storage auto-scales, so this card behaves differently (see FAQs).
- 90% on ClickHouse is closer to the edge than 90% on a typical app database. Merges need transient free space, so the effective ceiling is below 100%. Treat 90% as “act now”, not “still have 10% to play with”.
- The headline percentage is useless without the per-table attribution. “91% full” does not tell you what to do; “events_raw is 71% of the disk” tells you exactly which partition to drop or which TTL to add.
- A partition drop is instant; a row-level delete is not. Reaching for
DELETE FROMto reclaim space under pressure is the wrong move on ClickHouse; it is a mutation that rewrites parts and can make the space problem worse before it gets better. Drop partitions.
Sibling cards
Reconciling against the source
Confirm the live percentage against the server with:df -h on the data path should agree closely with system.disks. On ClickHouse Cloud, storage is decoupled and elastic: the service Monitoring tab shows stored bytes but there is no fixed “total volume” to divide against in the same way, because storage auto-scales. On Cloud, read this card as a growth-and-cost signal (how much am I storing and how fast is it climbing) rather than a “runway to a halt” signal; the hard write-stop behaviour of a full local disk does not apply.
Why our number may legitimately differ:
Known limitations / FAQs
We are on ClickHouse Cloud. Why is my disk usage not climbing toward a ceiling? ClickHouse Cloud separates compute from storage and auto-scales storage, so there is no fixed local volume to fill. On Cloud, treat this card as a stored-data growth and cost signal, not a runway-to-halt warning. The> 90% write-stop behaviour described here applies to self-managed instances with a fixed data volume.
The disk is at 88% and rising during a backfill. Should I wait or act now?
Act now. Merges need transient free space, so failures begin before 100%. Drop the oldest partitions on the biggest table (instant relief) or pause the backfill. Do not wait for the 90% alert if you can already see the growth rate will cross it within your response time.
Why should I drop partitions instead of running DELETE to free space?
A partition drop is a metadata operation that frees the space immediately. A DELETE (lightweight or mutation) rewrites parts and, for a mutation, temporarily needs more disk to write the new parts, which makes a space crisis worse. Under disk pressure, always drop partitions.
The percentage looks high but my dataset is small. Where did the space go?
Three usual suspects: detached parts (SELECT * FROM system.detached_parts), in-flight merge temporary files during a large merge, and uncleaned tmp directories after a crash. Also check that another process is not sharing the volume. The per-table active parts query will not show detached or temp space.
Does this include the disk used by system tables and logs?
Yes. The headline is whole-volume usage from system.disks, which includes system.query_log, system.part_log, and other internal tables. On a busy cluster these logs can grow large; set a TTL on them (for example system.query_log TTL) if they are a meaningful share of the per-table attribution.
Tiered storage: which disk does the card show?
The most pressured data disk, because that is the one that halts writes when full. If your hot SSD tier is at 94% while the cold object tier is at 30%, the card shows 94% and alerts, because new inserts land on the hot tier first. Configure storage policies and TTL-to-disk moves so hot data ages down to the cold tier before the SSD fills.
Can I set a different alert threshold than 90%?
Yes, in the Alert Rules tab. Clusters with slow, predictable growth and fast volume-expansion tooling may run a higher threshold; clusters with spiky backfills and slow procurement should alert earlier, at 80 to 85%, to buy response time.