[zzylol]

Why

Hydra answers a subpopulation's item frequency (query_key / query_frequency), but not the subpopulation's total mass. Queries like count by (g) therefore cannot be answered from a Hydra grid, and a caller holding a Count-Min Hydra has to reject them.

What

• Hydra::query_group_total(key) returns a subpopulation's estimated total mass. The key argument is the same positional, full-width key as query_key.
• HydraCounter::total_mass() returns one cell's total mass, read from the counter's own state:
  • Count-Min: the sum of any one inner row. Every insert adds its count to exactly one counter per row, so this is the cell's exact mass.
  • KLL: the retained weight (KLL::count), which compaction preserves.
  • Count Sketch, HyperLogLog, UnivMon: an error. Count Sketch rows hold signed updates, HyperLogLog keeps no counts, and UnivMon's mass is already an estimate that HydraQuery::L1Norm returns.
• Wire format: unchanged. No state is added; the total is derived from cells that are already serialized, so existing bytes decode and answer the new query.

How

The subpopulation hashes to one cell per row, as in query_key. Each row's estimate is that cell's total_mass(), and the answer is the median over rows, the same combination query_key uses. The subkey hashing is factored into a private subkey_hash helper that both queries share.

The doc comment states this error bound. Let n_Q be the true total, N the total inserted mass, D the number of key columns, w the column count and r the row count:

n_Q <= estimate <= n_Q + 4 * N * (2^D - 1) / w
with probability >= 1 - P[Binomial(r, 1/4) > r/2]   (0.84 at r = 3, 0.90 at r = 5)

A cell holds n_Q plus the mass of every other subkey hashed to it. The expected excess is at most M/w, where M = N(2^D - 1) is the mass after fan-out. By Markov's inequality, a row exceeds 4M/w with probability at most 1/4, so the median fails only when a majority of rows fail. The lower bound assumes non-negative update counts.

Alternative considered: a dedicated total cell per subkey, updated on insert. It would need new grid state and a wire-format change, and it would add nothing for Count-Min or KLL cells, which already hold their exact mass.

Before this PR

hydra.query_frequency(&[Some("us"), None], &item)?; // one item's count in region=us
// no way to get region=us's total count

After this PR

hydra.query_group_total(&[Some("us"), None])?;      // total count in region=us
hydra.query_group_total(&[Some("us"), Some("ios")])?;

Verification

The tests were written first; they did not compile before the method was added.

• hydra_group_total_matches_exact_totals: weighted rows with distinct items per row. Count-Min and KLL grids return exact totals for every one-column and two-column group, return 0 for an unseen group, and return exactly twice the totals after a self-merge.
• hydra_group_total_rejects_misuse: wrong arity, an unconstrained key, and Count Sketch, HyperLogLog and UnivMon counters all return errors.
• hydra_group_total_obeys_documented_bound: a narrow 5 x 64 grid with D = 2, 180 weighted rows and 243 groups. Every estimate is at least the exact total, all 243 groups overestimate (so collisions are exercised), and 0 groups exceed the bound 4M/w = 202.5. The test asserts that the violation rate is at most P[Bin(5, 1/4) >= 3] = 0.104.
• The full CI-equivalent suite (cargo fmt --check, clippy -D warnings with and without --all-features, cargo test with and without --all-features, cargo doc) was run on a separate Linux machine.
• Screenshots and measurements: not applicable (library API).

Limitations and follow-up

• Count-Min and KLL cells only. A Count Sketch Hydra would need a separate per-cell mass counter, which means a wire-format change, and is out of scope here.
• The bound uses the median, like the rest of Hydra. With non-negative counts every row overestimates, so a min over rows would give a tighter e^-r-style guarantee. This PR keeps the median for consistency with query_key; switching would be a small follow-up.
• Group totals for a Count-Min cell are summed in i64 and returned as f64, so they are exact up to 2^53.