NAME
Math::Histo::Sketch - DDSketch Bounded-Relative-Error Dynamic Quantile Sketch
SYNOPSIS
use Math::Histo::Sketch;
# Create a sketch guaranteeing <= 1% relative error (alpha = 0.01)
my $sketch = Math::Histo::Sketch->new(alpha => 0.01, max_bins => 1024);
# Stream samples
$sketch->insert(42.5);
$sketch->insert_w(100.0, 2.5); # with weight 2.5
$sketch->insert_n([10.5, 20.2, 30.8, 42.1]);
# Query quantiles
my $p50 = $sketch->quantile(0.50);
my $p90 = $sketch->quantile(0.90);
my $p99 = $sketch->quantile(0.99);
my $p999 = $sketch->quantile(0.999);
# Merge sketches across distributed workers
$sketch->merge($other_sketch);
# Binary wire format serialization
my $blob = $sketch->serialize_binary;
my $restored = Math::Histo::Sketch->from_binary($blob);DESCRIPTION
Math::Histo::Sketch implements the DDSketch streaming quantile sketch algorithm (Masson et al., VLDB 2019). It provides mathematically guaranteed relative error bounds:
|q_estimated - q_true| / q_true <= alphaFeatures: - Bounded memory with dynamic collapsing logarithmic binning. - Fully mergeable across threads or distributed network nodes. - Handles positive numbers, negative numbers, and exact zeros.
CONSTRUCTORS
- new(%options)
-
Options: -
alpha: Target relative error guarantee in (0, 1) (default: 0.01 = 1% relative error). -max_bins: Maximum bin budget before collapsing (default: 2048). - from_binary($blob): Deserializes sketch from canonical binary wire format.
METHODS
- insert($value): Stream a single sample.
- insert_w($value, $weight): Stream a weighted sample.
- insert_n(\@values, [\@weights]): Stream an array of samples from a Perl array reference.
- insert_packed_f64($packed_values, [$packed_weights]) (or insert_packed): Ingest binary float64 string directly (e.g.
pack('d*', ...)). - quantile($q): Query quantile for $q in [0, 1] with alpha relative error.
- merge($other): Merge another DDSketch into $sketch in-place.
- min(): Minimum sample observed.
- max(): Maximum sample observed.
- total_weight(): Sum of all sample weights.
- num_entries(): Total count of insertions.
- reset(): Reset sketch state to empty.
- serialize_binary(): Serialize to compact Little-Endian binary byte string.
SEE ALSO
AUTHOR
Steffen Mueller <cpan@steffen-mueller.net>
LICENSE
MIT License. Copyright (c) 2026 Steffen Mueller and libhisto contributors.