Struct DDSketch 

pub struct DDSketch<M: IndexMapping = LogarithmicMapping, S: Store = CollapsingLowestDenseStore> { /* private fields */ }

A fast and fully-mergeable quantile sketch with relative-error guarantees.

This implementation supports most of the capabilities of the various official DDSketch implementations, such as:

• support for tracking negative and positive values
• multiple store types (sparse, dense, collapsing)
• configurable index interpolation schemes (only logarithmic currently supported)

Defaults to using a “low collapsing” dense store with a logarithmic index mapping. This works well for tracking values like time durations/latencies where the tail latencies (higher percentiles) matter most.

Example

use ddsketch::canonical::DDSketch;

let mut sketch = DDSketch::with_relative_accuracy(0.01).unwrap();
sketch.add(1.0);
sketch.add(2.0);
sketch.add(3.0);

let median = sketch.quantile(0.5).unwrap();

Implementations

impl DDSketch<LogarithmicMapping, CollapsingLowestDenseStore>

pub fn with_relative_accuracy( relative_accuracy: f64, ) -> Result<Self, &'static str>

Creates a new DDSketch with the given relative accuracy.

Defaults to logarithmic mapping and the “low collapsing” dense store, with a maximum of 2048 bins per store.

Errors

If the relative accuracy is not between 0 and 1, an error is returned.

impl<M: IndexMapping, S: Store> DDSketch<M, S>

pub fn new(mapping: M, positive_store: S, negative_store: S) -> Self

Creates a new DDSketch with the given mapping and stores.

pub fn add(&mut self, value: f64)

Adds a single value to the sketch.

pub fn add_n(&mut self, value: f64, n: u64)

Adds a value to the sketch with the given count.

This is useful for weighted values or pre-aggregated data.

pub fn quantile(&self, q: f64) -> Option<f64>

Returns the approximate value at the given quantile.

The quantile must be in the range of [0, 1].

Returns None if the sketch is empty, or if the quantile is out of bounds. Otherwise, returns the approximate value.

pub fn merge(&mut self, other: &Self)

where M: PartialEq,

Merges another sketch into this one.

The other sketch must use the same mapping type.

pub fn is_empty(&self) -> bool

Returns true if the sketch is empty.

pub fn count(&self) -> u64

Returns the total number of values added to the sketch.

pub fn clear(&mut self)

Clears the sketch, removing all values.

pub fn mapping(&self) -> &M

Returns a reference to the index mapping.

pub fn positive_store(&self) -> &S

Returns a reference to the positive value store.

pub fn negative_store(&self) -> &S

Returns a reference to the negative value store.

pub fn zero_count(&self) -> u64

Returns the count of values mapped to zero.

pub fn relative_accuracy(&self) -> f64

Returns the relative accuracy of this sketch.

pub fn from_proto( proto: &ProtoDDSketch, mapping: M, ) -> Result<Self, ProtoConversionError>

where S: Default,

Creates a DDSketch from a protobuf DDSketch message.

This validates that the protobuf’s index mapping is compatible with the mapping type M, then populates the stores with the bin data.

Arguments

• proto - The protobuf DDSketch message to convert from
• mapping - The mapping instance to use (must be compatible with proto’s mapping)

Errors

Returns an error if:

• The protobuf is missing a mapping
• The mapping parameters don’t match the provided mapping
• Any bin counts are negative or non-integer
• The zero count is negative or non-integer

Note

The protobuf DDSketch does not include sum, min, max, or count fields. These are computed or set to defaults:

• count: sum of all bin counts plus zero_count
• sum, min, max: set to sentinel defaults (cannot be recovered from proto)

pub fn to_proto(&self) -> ProtoDDSketch

Converts this DDSketch to a protobuf DDSketch message.

Note

The protobuf DDSketch does not include sum, min, max, or count fields. This information is lost in the conversion.

Trait Implementations

impl<M: Clone + IndexMapping, S: Clone + Store> Clone for DDSketch<M, S>

fn clone(&self) -> DDSketch<M, S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<M: Debug + IndexMapping, S: Debug + Store> Debug for DDSketch<M, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M: IndexMapping + Default, S: Store + Default> Default for DDSketch<M, S>

fn default() -> Self

Returns the “default value” for a type.

impl<M: IndexMapping + PartialEq, S: Store + PartialEq> PartialEq for DDSketch<M, S>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<M: IndexMapping + PartialEq, S: Store + PartialEq> Eq for DDSketch<M, S>