hyperloglog

HyperLogLog - an algorithm for approximating the number of distinct elements

An improved version of HyperLogLog for the count-distinct problem, approximating the number of distinct elements in a multiset. This implementation offers enhanced performance, flexibility, and simplicity while maintaining accuracy.

Note on Implementation History

The initial version of this work (tagged as v0.1.0) was based on "Better with fewer bits: Improving the performance of cardinality estimation of large data streams - Qingjun Xiao, You Zhou, Shigang Chen". However, the current implementation has evolved significantly from this original basis, notably moving away from the tailcut method.

Current Implementation

The current implementation is based on the LogLog-Beta algorithm, as described in:

"LogLog-Beta and More: A New Algorithm for Cardinality Estimation Based on LogLog Counting" by Jason Qin, Denys Kim, and Yumei Tung (2016).

Key features of the current implementation:

• Metro hash used instead of xxhash
• Sparse representation for lower cardinalities (like HyperLogLog++)
• LogLog-Beta for dynamic bias correction across all cardinalities
• 8-bit registers for convenience and simplified implementation
• Order-independent insertions and merging for consistent results regardless of data input order
• Removal of tailcut method for a more straightforward approach
• Flexible precision allowing for 2^4 to 2^18 registers

This implementation is now more straightforward, efficient, and flexible, while remaining backwards compatible with previous versions. It provides a balance between precision, memory usage, speed, and ease of use.

Precision and Memory Usage

This implementation allows for creating HyperLogLog sketches with arbitrary precision between 2^4 and 2^18 registers. The memory usage scales with the number of registers:

• Minimum (2^4 registers): 16 bytes
• Default (2^14 registers): 16 KB
• Maximum (2^18 registers): 256 KB

Users can choose the precision that best fits their use case, balancing memory usage against estimation accuracy.

Note

A big thank you to Prof. Shigang Chen and his team at the University of Florida who are actively conducting research around "Big Network Data".

Contributing

Kindly check our contributing guide on how to propose bugfixes and improvements, and submit pull requests to the project.

Run the same checks used by CI before opening a pull request:

make ci

Individual targets are available for formatting (make fmt), linting (make lint), tests (make test), race-enabled tests (make test-race), and coverage (make coverage).

Version tags matching v*.*.* are validated by the release workflow before it publishes a GitHub Release with generated release notes. Tags with a pre-release suffix, such as v1.0.0-rc.1, publish as pre-releases.

License

© Axiom, Inc., 2026

Distributed under the MIT License (The MIT License).

See LICENSE for more information.