Zettel — MessageBus Routing, BucketId Prefix Splitting, and Ideal State Convergence

Vespa’s elastic content layer (vespa/storage/src/vespa/storage/distributor/) partitions documents across variable-depth 64-bit BucketId prefixes and maps each bucket deterministically to a ranked preference list of storage nodes using the cluster state version published by vespa/clustercontroller-core.

Mechanism & Upstream Grounding

1. Document-to-Bucket Hashing (vespa/document/src/vespa/document/bucket/):
   • Every DocumentId (id:<namespace>:<doctype>:<key-value>:<user-specific>) is hashed into a 58-bit location + 6-bit prefix-length count (BucketId). Co-located user/group keys share high-order location bits so group-scoped queries and visits hit a single bucket subtree.
2. Stateless Rendezvous / Ideal-State Placement (vespa/storage/src/vespa/storage/common/content_bucket_space.cpp):
   • Given the current ClusterState (node capacities, up/down/maintenance states, and hierarchical distribution groups), the Ideal State algorithm hashes (BucketId, node_index) to select the owning distributor and the ordered replica list (redundancy copies, searchable-copies ready in proton).
3. Dynamic Split/Join & Background Merge (vespa/storage/src/vespa/storage/distributor/operations/idealstate/):
   • When a bucket exceeds bucket-split-size or bucket-split-count, the distributor increments its used-bit count (splitting one prefix into two child buckets); when sibling buckets shrink below half the threshold, they are joined.

Boundary Conditions & Trade-offs

• Zero Central Metadata Bottleneck: Neither clients nor messagebus hops consult a central bucket directory table; any node with the compact ClusterState string computes bucket ownership locally in microseconds (see feeding-operations).