BanyanDB Docs: Clarify shard allocation mechanism in Meta Nodes section

[OmCheeLin]

Problem

The documentation in docs/concept/clustering.md (lines 56-58) states that Meta Nodes store "information about the shard allocation of each Data Node", which can be misleading. This phrasing suggests that explicit shard-to-node mappings are stored, but the actual implementation uses a deterministic round-robin algorithm to calculate assignments dynamically.

Current Implementation

Based on code analysis (pkg/node/round_robin.go):

• Meta Nodes store Group configurations (shard_num, replicas) and Node registration information
• Liaison Nodes calculate shard-to-node assignments using: node = (shard_index + replica_id) % node_count
• No explicit shard allocation mappings are stored in etcd

Suggested Fix

Clarify that Meta Nodes store the configuration information needed for shard allocation (not the allocation results themselves), and that Liaison Nodes dynamically calculate assignments using a deterministic algorithm. This would:

1. Accurately reflect the implementation
2. Explain the design benefit (simplified scaling without manual mapping updates)
3. Align with the existing description in section 5.2 (line 118) that mentions round-robin assignment

Other

Currently, metadata nodes do not store shard-to-node mappings, which seems to differ from many other database designs. Each query requires the liaison node to query all data nodes and then deduplicate.

While this increases horizontal scalability and reduces operational costs, it increases query latency. This seems unsuitable if I want to quickly query and alert when system metrics are abnormal.

[wu-sheng]

@hanahmily Could you clarify of this?

[hanahmily]

Good find, the meta node does not store allocation info. Would you please update the document?

While this increases horizontal scalability and reduces operational costs, it increases query latency. This seems unsuitable if I want to quickly query and alert when system metrics are abnormal.

The metrics query scenario emphasizes the most recent data, which is mostly stored in memory. According to the benchmark, the metrics query operates quickly enough for this scenario.

[wu-sheng]

Words fix via apache/skywalking-banyandb#902