feat(hll): expose composite cardinality estimates

[edouardmulliez]

When an HLL sketch retains valid update history, estimate() uses HIP and can return different estimates for the same values inserted in different orders. Callers currently cannot explicitly select the composite estimator, even though it is already implemented internally.

Add HllSketch::composite_estimate() and HllUnion::composite_estimate(), matching Java's getCompositeEstimate(). The methods query the existing register-based composite estimator in HLL mode and the existing coupon-count estimator in LIST/SET modes. They preserve HIP state, the behavior of estimate(), and the serialization format. The API docs explain the accuracy tradeoff and include usage examples.

[notfilippo]

Thanks!

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open findings

• Changing this from private to pub expands the crate’s public API surface (and potentially exposes… · New
• This test assumes n=100 is always in LIST/SET mode, but if the implementation’s promotion… · New
• These assert_ne! checks are inherently flaky: HIP estimates for different insertion orders can… · New
• These assert_ne! checks are inherently flaky: HIP estimates for different insertion orders can… · New

What changed in this PR

Expose a public composite cardinality estimator for HLL sketches/unions so callers can request insertion-order-independent estimates (matching Java’s getCompositeEstimate()), without affecting HIP state or serialization.

Changes:

• Add HllSketch::composite_estimate() and HllUnion::composite_estimate() APIs with docs/examples.
• Wire composite estimation through HLL array implementations and the shared estimator.
• Add integration tests covering composite estimate behavior, HIP preservation, and union behavior.

File	Description
tests-integration/​tests/​hll_test/​main.rs	Registers the new estimate integration test module.
tests-integration/​tests/​hll_test/​estimate.rs	Adds tests for composite estimate properties and HIP preservation.
datasketches/​src/​hll/​union.rs	Exposes HllUnion::composite_estimate() with documentation.
datasketches/​src/​hll/​sketch.rs	Exposes HllSketch::composite_estimate() and clarifies estimate() behavior in docs.
datasketches/​src/​hll/​estimator.rs	Makes the underlying composite estimator callable from more places.
datasketches/​src/​hll/​array4.rs	Adds register-based composite estimate for HLL4 arrays.
datasketches/​src/​hll/​array6.rs	Adds register-based composite estimate for HLL6 arrays.
datasketches/​src/​hll/​array8.rs	Adds register-based composite estimate for HLL8 arrays.
CHANGELOG.md	Documents the new public APIs.

🧠 Review effort: Lite

---

Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.

[tisonkun]

Generally looks good. Thanks for your contribution!

But I wonder if we can improve the document a bit, because I remember that we intentionally reduce some implementation details from user documents. Maybe we don't have to mention HLL mode, set mode and list mode. And the comparison to Java method may be irrelevant for Rust users.

[edouardmulliez]

Thanks a lot @notfilippo and @tisonkun for the review and the follow-up to improve the documentation!

That was really fast!