Module generic 

Generic Tuple sketches: cardinality estimation where each distinct key carries a summary of a type you define.

Implement TupleSummary on your own type and it becomes usable as a sketch summary. C++ calls back into Rust to clone and combine summaries; see TupleSummary’s documentation for which methods must not panic.

For the common case of a fixed-width array of f64 per key, prefer ArrayOfDoublesSketch — it binds a concrete C++ instantiation with no callback overhead.

use apache_datasketches::tuple::generic::{TupleSketch, TupleSketchBuilder, TupleSummary};

#[derive(Clone)]
struct Count(u64);

impl TupleSummary for Count {
    type Update = ();
    fn create(_: &()) -> Self { Count(1) }
    fn union_combine(&mut self, other: &Self) { self.0 += other.0; }
    fn intersection_combine(&mut self, other: &Self) { self.0 += other.0; }
}

let mut sketch: TupleSketch<Count> = TupleSketchBuilder::new().build()?;
for key in 0..100u64 {
    sketch.update_u64(key, &());
}
// Updating a key that is already present combines the new summary into
// the retained one with `union_combine`, so key 42 ends up at 2.
sketch.update_u64(42, &());
println!("estimate: {}", sketch.get_estimate());

// `compact` freezes the sketch into an immutable snapshot; `entries`
// hands back each retained `(hash, summary)` pair, with the summary
// cloned back out of C++ as an owned `Count`.
let compact = sketch.compact(true);
assert_eq!(compact.get_num_retained(), 100);
assert!(compact.is_ordered());

let entries: Vec<(u64, Count)> = compact.entries().collect();
assert_eq!(entries.len(), 100);
// 99 keys were seen once and key 42 was seen twice.
assert_eq!(entries.iter().map(|(_, c)| c.0).sum::<u64>(), 101);

Structs

CompactTupleSketch

An immutable snapshot of a generic Tuple sketch, produced by TupleSketch::compact or by any set operation’s result.

TupleAnotB

Computes the set difference a - b over generic Tuple sketches.

TupleIntersection

Computes the intersection of generic Tuple sketches fed via Self::update. Summaries of keys present in every input are merged with TupleSummary::intersection_combine; a key present in only some of the inputs is dropped and its summary never reaches the callback.

TupleSketch

A mutable, update-only Tuple sketch carrying a user-defined summary S per distinct key. Build one with TupleSketchBuilder.

TupleSketchBuilder

Builder for TupleSketch, mirroring upstream’s update_tuple_sketch::builder. lg_k defaults to 12, resize_factor to ResizeFactor::X8, and p to 1.0 (no sampling). The seed is never exposed.

TupleUnion

A streaming union over generic Tuple sketches. Summaries for a key present in more than one input are merged with TupleSummary::union_combine.

TupleUnionBuilder

Builder for TupleUnion. lg_k defaults to 12, resize_factor to ResizeFactor::X8, p to 1.0.

Traits

TupleInput

Either generic Tuple sketch type can be fed into this module’s set operations. Sealed — the shims have concrete overloads for these two types only.

TupleSummary

A user-defined per-entry summary for TupleSketch.

Functions

tuple_jaccard_similarity

Estimates the Jaccard index (intersection-over-union) of two generic Tuple sketches.