Distributed Vector Search — Configuration Reference

Settings, flags and defaults for Distributed Vector Search: the controller in the master leader, the weed-vector-worker engines, and the query router in every S3 gateway.

Controller ([master.vector] in master.toml)

The controller runs in whichever master leads. It reads [master.vector] from that master’s own master.toml, so keep the section identical on every master. An invalid value stops the master at startup.

Rules: 1 ≤ min_width ≤ max_fanout, 1 ≤ min_replicas ≤ max_replicas, max_scan_mb ≥ 0, qps_per_group > 0, and positive warm-up limits and durations. replica_cooldown and leader_settle may be 0.

Per-index bounds

[[master.vector.index]]
key = "s3://bucket/vector/index"   # the index's table URI
min_width = 4
max_width = 8
min_replicas = 2
max_replicas = 4

key is required. An S3 Vectors index’s table URI is s3://<vector bucket>/vector/<index name>. Each bound is optional, must be a positive integer, and replaces the cluster default for that index. A minimum may not exceed its maximum, and max_fanout still caps max_width.

Sizing

On every tick, for each index:

• resident: the largest index size reported by a gateway within stats_ttl: its segments plus its unsegmented tail.
• budget: the median --capacity-bytes of the engines that are not draining.
• E: the number of engines that are not draining.

W_mem  = clamp(ceil(resident / (0.8 × budget)), min_width, max_width)
W_scan = clamp(max(W_mem, ceil(resident / max_scan_mb)), min_width, max_width)
W      = max(W_mem, min(W_scan, floor(E / min_replicas)))
R      = clamp(ceil(peak QPS / qps_per_group), min_replicas, max_replicas)

Here max_width is the per-index bound, capped by max_fanout. R rises at once and falls to the peak seen during replica_cooldown. When R × W is more than E, the later groups get fewer engines or are dropped.

Placement

• Level 1, controller only. Each index gets R groups of up to W engines. Zones are ordered per index by hash, and group g takes zone g mod (number of zones). Within a zone, engines are ranked by weighted rendezvous score -w / ln(h), where w is the engine’s capacity. A group fills from its own zone first, then from any zone. Each group ranks engines by its own key, so an engine joining or leaving moves few others. Groups that share a zone still interact: when a group replaces a lost member with an engine that a later group held, the later group picks a replacement too.
• Level 2, gateways and engines. Within a group, segments are assigned in id order. Each goes to the member with the highest hash whose load stays within 1.25× the group’s average bytes, otherwise to the least loaded member. Each tail fragment is placed the same way, as a segment with an equal share of the tail’s bytes. Level 2 uses integer arithmetic only, so the Go router and the Rust engines compute the same mapping; shared test vectors pin the two together.
• Make-before-break. The controller keeps a serving and a target placement for each index. Engines warm the target. Serving switches to the target once every new owner reports warm, or after warmup_timeout.

Engines (weed-vector-worker)

Engine states: joining (registered, not serving), warming (loading its target slots), serving, draining (planned removal: still serving until queries move off). An engine whose session stays lost past restart_grace is gone, and its slots are placed elsewhere.

Query router (every S3 gateway)

The router needs no flags. It finds the controller through the gateway’s masters and uses the gateway’s -dataCenter as its zone.

1. Resolve the index’s latest version. The version is cached, and writes through the gateway invalidate it.
2. List the version’s segments from any serving engine. The list is cached per version, because versions are immutable.
3. Watch the index’s placement, and pick a group: the gateway’s own zone first, then the group with fewer outstanding requests.
4. Map segments and tail fragments to the group’s members. A member that is down or shedding load hands its share to its owner in another group (warm), or else to another member (cold).
5. Send one SearchSegments per engine, with the query’s remaining deadline.
6. Merge the partial top-k lists into the global top-k.

With no placement (no controller, or no serving engine), the query goes to the single weed-vector. Only QueryVectors takes the distributed path. Writes and index management go to the single engine.

Errors

An engine that sheds load means the cluster is short of capacity, not that the caller is sending too fast, so the gateway never reports it as TooManyRequestsException.

Versions

Index versions are immutable. Engines keep opened versions in an LRU. There is no per-query lease: version cleanup keeps every version that was the latest at any point in the last hour, however old its commit, and no query runs that long.