Hash-tag co-location.

Valkey cluster distributes keys across 16384 slots by a hash of the key name — so two related keys can land on two nodes, and a multi-key command across them raises CROSSSLOT. A hash tag, a {...} substring, changes what is hashed: Valkey hashes only the tag, so every key carrying the same tag value shares one slot.

Give three keys the same tag value and they all land on one slot:

An operation across the three runs on one node. Drop the tag and the whole key is hashed instead, scattering the keys to different slots. The slot is CRC16(substring) % 16384 — pure arithmetic over the key bytes, so a client can compute it without asking the server. R2.04 was the fallback for keys that cannot share a slot; this module is the prevention it substitutes for.

The basic pattern: group all of an entity's keys behind one tag value — the entity id.

With the keys co-located you can update several fields atomically with MULTI/EXEC, run a Lua script touching all of them, and use WATCH for optimistic locking across them.

A shared slot is what makes each of these legal across the entity's keys. A transaction across related keys:

Every command runs atomically because the keys share a slot. A Lua script across keys reads two hashes and writes a third — all co-located, called with three keys on one slot (EVAL <script> 3 user:{123}:profile user:{123}:settings user:{123}:cache). Optimistic locking with WATCH works the same way — watch two co-located keys, read, then MULTI/EXEC; if either changes before EXEC, the transaction aborts.

The same move recurs across entity kinds — one tag value per entity, atomic operations across its keys. An order with line items carries the {order_id} tag on its header, items, totals, and status, so an atomic status transition writes the header and the history in one MULTI/EXEC. A counter with inventory shares the {sku} tag across stock, reserved, and sold, so a Lua reserve reads stock and, if enough, DECRBYs stock and INCRBYs reserved in one atomic script. A session with related state shares the {session_id} tag across data, user, cart, and expiry, so session operations stay race-free.

Where you put the braces determines what is hashed. Three rules, and the explorer at the top of the page is each of them made concrete. The first {...} wins — the first balanced tag determines the slot:

The convention is to put the entity id in the tag. An empty tag {} hashes the whole key (key:{}:suffix → the whole key → slot 14786), so avoid an empty tag unless that is intended. And only the first tag is used — {a}:{b}:key hashes a (slot 15495) and ignores b; two tags do not combine.

Co-location concentrates load. If one entity is extremely hot — a celebrity user, a viral product — its slot becomes a bottleneck. Three mitigations: shard within the entity across tagged sub-keys (user:{123}:followers:0, …:1) so the load splits while the keys stay co-located; separate the hot data onto its own untagged key on a different slot; and accept eventual consistency for read-heavy data by replicating to a non-tagged read replica.

A tag co-locates one entity's keys; it offers no guarantee across entities (a transfer between two users reaches for the cross-shard detection of R2.04), across cluster-wide commands (KEYS/SCAN/FLUSHDB ignore slots), or during resharding (a slot can migrate, and clients retry).

Every multi-key command requires its keys on one slot in cluster mode. The tag is what arranges that, so each of these becomes available across an entity's keys:

EchoMQ's queue keys are co-located by exactly this rule, and the grammar makes it a law rather than a convention. EchoMQ.Keyspace.queue_key/2 (echo/apps/echo_mq/lib/echo_mq/keyspace.ex) returns "emq:{" <> q <> "}:" <> type — so the pending set, the active set, the schedule, the dead set, and a job's own row all carry the same {q} tag and answer one slot by construction. The hashtag is the queue name. The slot is computed client-side by slot/1: CRC16-XMODEM (polynomial 0x1021) over the hashtag, modulo 16384, so the connector can route and partition without a server round trip. The functional-Elixir craft behind the echo data layer is taught by the /elixir state chapter.

Each dive takes the mechanic one layer deeper, in order: the tag rule and the real slot computation first, then why a multi-key script raises CROSSSLOT off one slot and how the {q} tag keeps a queue's claim legal, then how slot/1 computes that slot client-side so the connector routes without a round trip.