A part is a sealed bundle of rows created from one incoming batch. ClickHouse sorts the batch, writes everything needed to read it later, and then treats that bundle as finished.

Picture a print shop

You hand the shop 1,000 index cards. The shop sorts those cards by (service, time), prints several organized mini-books, adds a tiny table of contents, and shrink-wraps the result. That shrink-wrapped package is one part.

When another 1,000 cards arrive, the shop does not cut open the first package and insert each new card into its perfect position. It makes a second sorted package. Later, a background worker may open several packages, combine their cards in order, and produce one larger replacement package.

These are four nested levels. The names are confusing because everyday English makes “partition” and “part” sound identical. In ClickHouse they are not.

Put numbers on it

Suppose July has received 30 insert batches and no merges have happened yet. The July partition can contain 30 parts. If each part has 819,200 rows and uses 8,192-row granules, each part has roughly 100 granules. Every granule contains individual rows.

A date filter may discard every drawer except July. ClickHouse must then inspect the folders inside July and use each folder’s index to choose page groups.

Because the map can become almost as troublesome as the territory. An entry for every row gives precise lookups, but billions of entries consume memory and create more work to store and maintain.

The phone-book version

Imagine a 1,000-page phone book. One strategy is a separate index entry for every name. That index is enormous. Another is a tab every eight pages saying “names beginning around MARTIN start here.” You jump close to MARTIN, then scan a few pages.

ClickHouse chooses the second shape because analytical queries usually want many rows anyway. With one billion rows and a simple 8,192-row granularity, the rough order of magnitude is about 122,071 key samples instead of one billion row pointers. The exact number varies by parts and adaptive granularity, but the size difference is the point.

No. It means reading the granule’s row range for the columns the query needs. Column pruning and granule pruning are separate savings that stack together.

A concrete query

Your table has 50 columns. The query needs service, status, and latency. The sparse index decides that granule 14 might match. ClickHouse reads the granule-14 ranges for those three columns—not all 50 columns—but it normally reads all candidate rows inside those three ranges.

If the granule contains 8,192 rows and only 40 truly match, the remaining rows are filtered after the selected column data is read. That is still far cheaper than reading every granule or every column in the part.

They cooperate at one boundary, but they have different jobs: the index stores a clue, the mark stores a location, and the granule is the data neighborhood reached through that location.

Use a cookbook

The cookbook is ordered alphabetically by recipe name. A tiny card says “Pasta begins around page 240.” That card is like the sparse primary-index sample: it gives you a key value near a boundary. The ribbon physically tucked into page 240 is like a mark: it tells you where to open. The recipes on pages 240–247 are like the granule: the chunk you actually pull into view.

Ignore the file jargon for one minute. Make three moves and predict the highlighted boxes before looking.

1. Choose auth and stop at minute 07. Exactly one 8-row granule should light up. The cutoff lands on its final row, so eight rows are read and all eight match.
2. Move the cutoff to minute 11. The second auth granule must light up because it contains minutes 08–15. ClickHouse reads 16 auth rows total; minutes 12–15 are extra passengers and fail the exact filter.
3. Switch auth to search. The number of granules stays the same, but different boxes light up. The first sorting-key field groups each service into its own contiguous neighborhood.

The one question to answer

Why can ClickHouse not read only minutes 08–11 from that second toy granule? Because the sparse boundary gets it to the 08–15 neighborhood. The row-level predicate, not the sparse index, separates 08–11 from 12–15.

Because every part is its own little sorted world. ClickHouse cannot inspect one master index and be done; it must ask each surviving part what it might contain.

Imagine searching 400 short books

All 400 books are alphabetized internally, and each has a good table of contents. Finding “zebra” in any one book is easy. But to find every zebra across the collection, you still pick up each relevant book, inspect its table of contents, possibly open it, and later combine the answers.

One larger anthology may contain the same pages, yet it has fewer covers, fewer tables of contents, fewer open/close operations, and longer contiguous passages to read. That is the intuition behind merging parts.

Treat the formula as a counting lens, not a promise of exact milliseconds.

Suppose a date filter leaves 12 parts. Inside each part, the sparse index admits 4 granules. The query needs 3 columns.

Compression blocks, caching, coalesced reads, parallelism, and file format affect the real I/O, so ClickHouse may not issue 144 literal disk requests. The multiplication still tells you where optimization can remove work.

1. Reject more parts with partition or part-level metadata.
2. Reject more granules with a sorting key aligned to predicates.
3. Request fewer columns by avoiding SELECT * when it is unnecessary.

An insert arrives as a batch. ClickHouse sorts that batch and seals it into a part. Inside the part, rows are divided into granules. At each granule boundary, the primary index saves a sample key and every column keeps location information for that boundary.

Later, a query asks for a few columns and includes a filter. ClickHouse first rejects irrelevant partitions and parts when it can. Inside every surviving part, it compares the filter with sparse key samples. Those samples identify candidate granules. Marks translate the chosen boundaries into locations within the requested column streams. ClickHouse reads those whole granule ranges, then applies the exact filter to discard the extra rows that rode along.

If there are many parts, this decision process repeats many times. If granules are large, more neighbor rows may ride along. If the query asks for many columns, more vertical data streams must be read.