dethlex — digital garden

Kafka partition assignment: Range, RoundRobin, and why joins care

Wed, 22 Apr 2026 00:00:00 GMT

🧪 Sample seed note. Placeholder content demonstrating the garden structure — replace with your own text.

A consumer group is a little scheduler: topics on one side, consumers on the other, and an assignor deciding who reads what. Most people meet assignors the day load lands unevenly on their pods. The more interesting encounter is the day a stream-stream join silently produces garbage.

RangeAssignor: skewed, but aligned

RangeAssignor works per topic: sort the partitions, sort the consumers, carve the partitions into contiguous ranges. With 8 partitions and 3 consumers you get 3-3-2 — the first consumers always take the extra partitions, for every topic they subscribe to. Subscribe one group to five 8-partition topics and consumer 0 carries five extra partitions while consumer 2 carries none. That is the famous Range skew.

But look at what the per-topic sorting buys: partition N of every subscribed topic lands on the same consumer. If impressions and clicks are both keyed by campaign_id, both have 8 partitions, and both were written with the same partitioner, then all events for one campaign — from both topics — arrive at one process. You can join them in local memory with no shuffle, no external store. This property is called co-partitioning, and Range-style assignment is the only reason it survives group rebalancing.

RoundRobinAssignor throws every topic-partition into one pool and deals them out like cards. Load: even. Alignment: destroyed — impressions-3 and clicks-3 now live on different consumers, and your in-memory join is quietly wrong.

StickyAssignor and its successor CooperativeStickyAssignor optimize a different axis: keep the previous assignment as intact as possible across rebalances. Cooperative rebalancing additionally kills the stop-the-world pause — consumers only release the partitions that actually move. For a plain fan-out consumer group this is what you want in 2026.

The actual decision table

You are…	Pick
joining topics on a shared key	Range (and see checklist)
running a plain high-volume fan-out	CooperativeSticky
on Kafka Streams	nothing — it brings its own

The co-partitioning checklist, all four or nothing:

Same partition count on every joined topic.
Same key and serialization.
Same partitioner on every producer.
A Range-family assignor on the consumer group.

Break any one of them — someone “rebalances” partition counts, one producer uses murmur2 and another crc32 — and the join degrades without a single error in any log. The only alarm you’ll get is a business metric drifting.

In Go this is explicit: franz-go takes kgo.Balancers(kgo.CooperativeStickyBalancer()) (or kgo.RangeBalancer()), segmentio/kafka-go takes GroupBalancers. Choose consciously — the default depends on the library, and as shown above, the default is a semantic decision, not a tuning knob.

Trident 660, first thousand kilometers

Sat, 20 Jun 2026 00:00:00 GMT

🧪 Sample seed note. Placeholder content demonstrating the garden structure — replace with your own text.

The spec sheet says 660 cc, three cylinders, 81 hp. What it doesn’t say is what a triple feels like when you live between a twin and an inline-four in your head: torque low like the twin, then instead of running out of breath it just keeps pulling, smoother and angrier, until the shift light. The sound between 6 and 8 thousand is the reason people keep this bike long after they can afford a bigger one.

What works

The engine is honest. No ride-by-wire theatrics in Road mode: throttle in, drive out. Rain mode exists; on Cyprus it gets used maybe four days a year.
Hairpins. On the Troodos switchbacks the low center of mass and the wide bars make the bike fall into corners with almost no effort. It flatters you exactly up to the point where it doesn’t — which is a fine teacher.
Commuting. Light clutch, no drama in traffic, mirrors that actually show the road. It disappears under you, in the best sense.

What the brochure skips

Heat. Thirty-eight degrees in Limassol traffic and the triple reminds you it’s a compact engine in a tight frame. Moving, it’s fine; standing, you learn to time the lights.
The tank. Fourteen liters is optimistic marketing for “range”. Riding it like it asks to be ridden, the low-fuel bar shows up around 180 km, and mountain villages do not compete on petrol station density.
Wind. Naked means naked. Above 120 km/h your neck is the windscreen; the aftermarket flyscreen moved from “cosmetic” to “ordered” within two weekends.

Verdict at 1000 km

It’s a first “real” bike that doesn’t feel like a compromise and a second bike that doesn’t feel like a step down. Servicing is cheap, the triple makes every tunnel a concert, and the whole machine communicates so clearly that you end up riding better than you are. The plan was to ride it for a season and trade up. The plan is now under review.

Why ClickHouse wants your inserts in batches

Wed, 18 Mar 2026 00:00:00 GMT

🧪 Sample seed note. Placeholder content demonstrating the garden structure — replace with your own text.

MergeTree is not a B-tree you poke rows into. Every INSERT becomes a brand-new part — a directory on disk with one file pair per column, plus checksums and metadata. The table you query is the union of all active parts, and a background process constantly merges them into bigger ones. That design is why ClickHouse scans billions of rows per second. It is also why it punishes chatty writers.

What a tiny insert actually costs

Insert one row and ClickHouse still pays the full price of a part: create the directory, write every column file, fsync, register the part. On a Replicated* table it additionally writes a replication log entry that every replica must fetch and apply. One row, dozens of filesystem operations, one round of replication traffic.

Do that a thousand times a second and two things happen:

Merges fall behind. The merge scheduler was designed for parts with thousands-to-millions of rows, not thousands of parts with one row.
The table throttles you. Once a partition accumulates parts_to_delay_insert active parts (1000 by default), inserts get slowed down; at parts_to_throw_insert (3000) you start catching TOO_MANY_PARTS exceptions in production at the worst possible moment.

You can watch the pressure build up:

SELECT table, count() AS active_parts
FROM system.parts
WHERE active
GROUP BY table
ORDER BY active_parts DESC;

If active_parts for a hot table grows monotonically during peak traffic, your writers are winning against the merges. They will not win for long.

The rule of thumb

Aim for one insert per table per second, tens of thousands of rows per insert. The exact numbers are workload-dependent, but the shape of the rule is not: fewer, fatter inserts are always cheaper than many thin ones. In our pipelines the sweet spot landed around 50–100k rows or one second of accumulation, whichever comes first.

Where to batch

In the application. A buffered channel and a ticker: flush on len(buf) >= N or every second. Full control over durability — you decide what happens to the buffer on shutdown. This is what we run in the Go consumers that land Kafka topics into ClickHouse.
async_insert = 1. The server batches for you: inserts land in an in-memory buffer and are flushed as one part. Turn on wait_for_async_insert if you want the acknowledgment to mean “data is in a part” rather than “data is in a buffer” — with it off, a crash between buffer and flush loses rows silently.
The Buffer engine. Same idea, table-shaped, older. It works, but the buffer lives in RAM of the node and is lost on a hard restart, and it adds one more table to reason about. I reach for it last.

The part nobody tells you

Batching interacts with insert deduplication on replicated tables: a retried identical block is dropped by its checksum, which is exactly what you want from at-least-once consumers — but only if your batches are deterministic. Build them by offset range, not by wall clock, and a consumer restart re-produces byte-identical blocks that dedup for free.

Batch because the storage engine is built from parts. Everything else — async inserts, Buffer tables, Kafka engine — is just someone else doing the batching for you, with durability semantics you should read twice.

Lock-free config reloads in Go with atomic.Pointer

Fri, 15 May 2026 00:00:00 GMT

🧪 Sample seed note. Placeholder content demonstrating the garden structure — replace with your own text.

A recurring shape in high-load services: a lookup structure — deduplication set, targeting rules, a denylist — that is read on every request and replaced wholesale every N seconds from some source of truth. Hundreds of goroutines read it; exactly one goroutine writes it; the write is never an edit, always a full replacement.

That last property is the key that unlocks everything.

Why not RWMutex

sync.RWMutex is correct here and wrong anyway. Every RLock is an atomic RMW on shared state — at hundreds of thousands of reads per second across many cores, readers contend with each other on the lock word itself, and the cache line holding it ping-pongs between cores. You pay this tax on the hot path to protect against a write that happens once a minute.

sync.Map solves a different problem (disjoint key sets, incremental updates). For build-then-replace workloads it buys complexity, not speed.

The pattern

Treat the structure as an immutable snapshot. Readers grab the current one; the reloader builds the next one off to the side and swaps a pointer:

type Snapshot struct {
	seen map[uint64]struct{} // never mutated after publish
}

var current atomic.Pointer[Snapshot]

// The zero value of atomic.Pointer is nil — seed it before the hot path
// runs, or every request panics until the first successful reload.
func init() {
	current.Store(&Snapshot{seen: map[uint64]struct{}{}})
}

// Hot path: one atomic load, zero locks, zero contention.
func Seen(id uint64) bool {
	_, ok := current.Load().seen[id]
	return ok
}

// Cold path: runs in one goroutine, e.g. on a ticker.
func reload(ctx context.Context, src Source) error {
	next, err := buildSnapshot(ctx, src) // minutes of work allowed here
	if err != nil {
		return err // keep serving the old snapshot — stale beats broken
	}
	current.Store(next)
	return nil
}

atomic.Pointer (Go 1.19+) makes this typed and impossible to get wrong at the call site. A reader that loaded the old snapshot finishes its request on the old snapshot — perfectly consistent, just up to one reload stale. The garbage collector retires the old map once the last such reader returns.

The fine print

Immutability is a contract, not a mechanism. Nothing stops a confused reader from writing to the map and racing every other goroutine. Keep the map unexported, expose only query functions.
Memory doubles during the swap. Old and new snapshots coexist while the build runs. For a 2 GB table, plan 4+ GB — or your “lock-free elegance” becomes an OOMKilled pod at the worst hour.
Failed reloads must not clear state. Return early, keep the old pointer, and export the moment of last success:

lastReload.Set(float64(time.Now().Unix())) // prometheus gauge

Alert when time() - last_successful_reload_seconds exceeds a few reload intervals — a service quietly serving week-old rules is the failure mode nobody notices until money moves.

Writes on the hot path change the game. If readers must also mark ids as seen, a read-only snapshot no longer fits — reach for sharded mutexes or a pair of rotating generations instead. The atomic-swap trick is for read-heavy, replace-rarely data. Know when you’ve left its territory.

dethlex — digital garden

Kafka partition assignment: Range, RoundRobin, and why joins care

RangeAssignor: skewed, but aligned

RoundRobin and Sticky: even, but blind

The actual decision table

Trident 660, first thousand kilometers

What works

What the brochure skips

Verdict at 1000 km

Why ClickHouse wants your inserts in batches

What a tiny insert actually costs

The rule of thumb

Where to batch

The part nobody tells you

Lock-free config reloads in Go with atomic.Pointer

Why not RWMutex

The pattern

The fine print