Skip to content

KLL: weighted update, matching datasketches-java - #582

Merged
leerho merged 6 commits into
masterfrom
kll-weighted-update
Nov 19, 2026
Merged

leerho merged 6 commits into
masterfrom
kll-weighted-update

Conversation

@leerho

@leerho leerho commented Nov 15, 2026

Copy link
Copy Markdown
Member

Adds kll_sketch::update(item, weight), equivalent to calling update(item) weight times. It follows the weighted update of the KLL sketches in datasketches-java.

This builds on #542 by Shani Elharrar, whose two commits are kept here unchanged, with fixes on top.

Behavior

  • If weight is smaller than the free space in level zero, the item is inserted weight times as plain updates. No compaction can happen on this path.
  • Otherwise, the update builds an exact sketch with one copy of the item at each level whose bit is set in weight, and merges it in. This costs one merge with a sketch of at most 61 items, however large the weight.
  • A weight of 1 is a plain update. A weight of 0, or above 2^61 - 1 (kll_constants::MAX_WEIGHT), throws std::invalid_argument. These are the same rules as in Java, which cannot read an image with n >= 2^63.
  • NaN items are ignored, as in update(item).
  • Serialization is unchanged.

Fixes on top of #542

  • The small-weight path wrote through a null pointer on a new sketch: since perf: kll_sketch allocates its items on first use #558, the items storage is allocated on first use. The weighted update now allocates first, like update(item), so a failed allocation also leaves the sketch unchanged.
  • Each copy is constructed before it is counted, so a failed copy leaves a valid sketch.
  • Weights of 2^61 and above are rejected, as described above, instead of folding the high bits into level 60.

Also included

  • kll_helper::floor_of_log2_of_fraction looped forever once numer >= 2^63, because doubling denom overflowed to zero. Any merge that reached n >= 2^63 hung. This is the first commit from Add weighted update to kll_sketch #542. Java computes the same bound without a loop, so it is not affected.
  • The KLL iterator started at level 0 without skipping empty levels. When level zero was empty, which a merge can leave, every item was reported with weight 1. Weighted updates with an even weight leave level zero empty every time, but plain merges hit it too: in 2,000 random merge trials on master, 384 had wrong iterator weights. Quantile queries were not affected, since the sorted view reads the levels directly. Java's iterator skips empty levels and is correct.

Tests

  • Weighted update sections in kll_sketch_test.cpp: zero weight, NaN, same as repeated updates in exact mode, one item with a large weight, the maximum weight with a serialization round trip, weights above the maximum, weight 1, the first weighted update of a new sketch on both paths, large weights into a full sketch, estimation mode within the k=200 error bound, and strings.
  • Allocation failures in kll_sketch_allocation_test.cpp: a failed first weighted update leaves the sketch unchanged on both paths, and failing each allocation of a stream of weighted updates in turn leaves a valid, usable sketch.
  • A test that iterator weights sum to n after merges that leave level zero empty. It fails on master.

All tests pass under ASan and UBSan.

🤖 Generated with Claude Code

shanielh and others added 4 commits November 15, 2026 10:53
…numerators

Doubling denom until it exceeds numer overflows to zero once numer >= 2^63,
so the loop never terminated. ub_on_num_levels(n) calls it with the merged
stream weight, which made a merge reaching n >= 2^63 hang. Compare against
numer / 2 instead, which is equivalent and cannot overflow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
update(item, weight) is equivalent to calling update(item) weight times.
A weight that fits into the free space of level zero is applied as plain
updates; a larger one builds an exact sketch holding one copy of the item
at each level whose bit is set in the weight and merges it, so the cost is
logarithmic in the weight. This mirrors the weighted update in
datasketches-java.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The const_iterator started at level 0 without skipping empty levels.
When level 0 is empty, which a merge can leave, every item was reported
with weight 1 instead of the weight of its level. Quantile queries were
not affected: the sorted view reads the levels directly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Reject weights above 2^61 - 1 (kll_constants::MAX_WEIGHT), as
  datasketches-java does, instead of folding the high bits into level 60.
  Java cannot read an image with n >= 2^63.
- Allocate the items storage before writing into it. Since items are
  allocated lazily, the small-weight path wrote through a null pointer
  on a new sketch. Allocating first also leaves the sketch unchanged
  when the allocation fails.
- Construct each copy before counting it, so that a failed copy leaves
  a valid sketch.
- A weight of 1 is a plain update, as in Java.
- Check the item before the weight, as in Java.
- Tests: the maximum weight, weights above it, weight 1, the first
  weighted update of a new sketch on both paths, and allocation failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coveralls

coveralls commented Nov 15, 2026 •

Copy link
Copy Markdown

Coverage Report for CI Build 44436712044

Warning

Build has drifted: This PR's base is out of sync with its target branch, so coverage data may include unrelated changes.
Quick fix: rebase this PR. Learn more →

Coverage increased (+0.1%) to 96.974%

Details

  • Coverage increased (+0.1%) from the base build.
  • Patch coverage: 47 of 47 lines across 2 files are fully covered (100%).
  • 92 coverage regressions across 13 files.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

92 previously-covered lines in 13 files lost coverage.

Top 10 Files by Coverage Loss Lines Losing Coverage Coverage
kll/include/kll_sketch_impl.hpp 34 95.51%
tdigest/include/tdigest_impl.hpp 20 95.83%
filters/include/bloom_filter_impl.hpp 10 93.28%
hll/include/CouponHashSet-internal.hpp 5 96.45%
hll/include/CouponList-internal.hpp 5 97.17%
count/include/count_min_impl.hpp 4 98.25%
hll/include/Hll4Array-internal.hpp 4 97.4%
hll/include/HllSketch-internal.hpp 4 97.14%
hll/include/AuxHashMap-internal.hpp 2 98.71%
common/include/quantiles_sorted_view_impl.hpp 1 98.59%

Coverage Stats

Coverage Status
Relevant Lines: 17083
Covered Lines: 16566
Line Coverage: 96.97%
Coverage Strength: 1907459.12 hits per line

💛 - Coveralls

Both deserializers, from bytes and from a stream, must allocate only what
a newly built empty sketch does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread kll/include/kll_sketch_impl.hpp Outdated
}
items_size_ = levels_[num_levels_];
items_ = allocator_.allocate(items_size_);
for (uint32_t i = 0; i < items_size_; ++i) new (&items_[i]) T(item);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because of this logic, If bad_alloc happens, we should deallocate in L248. If not, this is memory leak.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, thanks. If a copy of the item throws, the destructor doesn't run, so the storage and the copies already made leaked. Fixed in 0ab4ab6: the constructor now destroys the copies it made and frees the storage before rethrowing.

Comment thread kll/include/kll_sketch_impl.hpp Resolved
The constructor that builds the weighted sketch now destroys the copies it
made and frees its storage if a copy throws. The weighted update resets the
sorted view before changing anything. merge() now forwards an rvalue source
to merge_higher_levels(), so its higher levels are moved rather than copied,
and the merge the weighted update makes copies no items.

A new test makes each item copy of a weighted update throw in turn, and
checks for leaks and a stale sorted view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leerho
leerho requested a review from proost November 19, 2026 01:24
new (&items_[index]) T(conditional_forward<FwdSk>(other.items_[i]));
}
if (other.num_levels_ >= 2) { merge_higher_levels(other, final_n); }
if (other.num_levels_ >= 2) { merge_higher_levels(std::forward<FwdSk>(other), final_n); }

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Forwarding other into merge_higher_levels only avoids copies on the (self_pop == 0) && (other_pop > 0) branch in populate_work_arrays (kll_sketch_impl.hpp:963). Once this is in estimation mode and has items at the same higher level as other ((self_pop > 0) && (other_pop > 0), line 968), populate_work_arrays calls the 8-argument kll_helper::merge_sorted_arrays(const T* buf_a, ..., const T* buf_b, ...) (kll_helper_impl.hpp:164), which has two issues when an item copy (or comparator) throws:

  1. other.items_ is passed as const T* without forwarding, so elements from other are still copy-constructed (new (&buf_c[c]) T(buf_b[b++])). In addition, buf_a (this->items_) is also const T*, so new (&buf_c[c]) T(std::move(buf_a[a])) (kll_helper_impl.hpp:177, 180) produces const T&& and invokes T's copy constructor rather than its move constructor right before calling buf_a[a++].~T().
  2. If any copy or comparison throws inside populate_work_arrays, workbuf's deleter (kll_sketch_impl.hpp:891) deallocates raw memory without destroying the objects already constructed in workbuf (leaking them), while this->items_ has already destroyed elements in levels_[0]..levels_[lvl] and [levels_[lvl], a) without updating levels_. Subsequent destruction in ~kll_sketch() (kll_sketch_impl.hpp:146) then calls ~T() a second time on those destroyed slots (double-free / UB).

The new fragile_item test (kll_sketch_allocation_test.cpp:319) does not reach this branch because k = 200 with 5 updates stays at num_levels_ == 1 (self_pop == 0 for all lvl >= 1). Changing that fixture to k = 8 with 9 initial updates and weight = 18 reproduces a leak at fail_at = 5 and an ASan double-free in ~kll_sketch() at fail_at = 6.

Taking non-const T* buf_a in merge_sorted_arrays (and forwarding from buf_b when other is an rvalue), along with tracking constructed elements in workbuf and destroyed slots in this->items_ on unwind, would close this gap.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, confirmed. Your fixture SEGVs under ASan. I was wrong in my earlier reply: the weighted update's merge copies no items only while this sketch has nothing at the levels it merges into. In estimation mode it still copied, after this sketch's items had already been moved out. The same was true of merge(const&) before this PR.

Fixed in #585. The merge now copies other's items into the work buffer first. If a copy throws, it destroys them, and this sketch is unchanged. After that, this sketch's items are merged in front of them using moves only, so nothing is copied from a const T*. Your fixture is one of the tests. The helpers now use the sketch's comparator instead of C().

if (weight == 0) throw std::invalid_argument("weight must be at least 1");
if (weight > kll_constants::MAX_WEIGHT) {
throw std::invalid_argument("weight must be less than 2^61: " + std::to_string(weight));
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAX_WEIGHT (2^61 - 1) bounds a single call, but merge (const uint64_t final_n = n_ + other.n_; at line 319) and the small-weight path do not check for uint64_t overflow on n_:

  • 5 calls of update(x, MAX_WEIGHT) already push n_ >= 2^63 (producing images beyond Java's signed long range).
  • 9 calls of update(x, MAX_WEIGHT) wrap n_ modulo 2^64 to 2^61 - 9. Because kll_helper::sum_the_sample_weights wraps modulo 2^64 in the same way, assert_correct_total_weight() still passes on k = 200, silently leaving a corrupted get_n() (and on k = 8, accumulating 68+ items at level 60 eventually throws "depth > 60" mid-merge after mutating min_item_ and level zero).

Checking weight > std::numeric_limits<uint64_t>::max() - n_ (and other.n_ > std::numeric_limits<uint64_t>::max() - n_ in merge, analogous to Java's Math.addExact) before mutating the sketch would prevent silent wraparound.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. #585 caps n at 2^63 - 1, Java's Long.MAX_VALUE, since Java's merge uses Math.addExact on a signed long. update(), the weighted update and merge() now throw std::overflow_error before changing anything. With n below 2^63, a sketch can't reach the 62 levels that make level_capacity throw "depth > 60", so that failure partway through a merge goes away too.

template<typename FwdT>
void kll_sketch<T, C, A>::update(FwdT&& item, uint64_t weight) {
if (!check_update_item(item)) { return; }
if (weight == 0) throw std::invalid_argument("weight must be at least 1");

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Throwing on weight == 0 matches datasketches-java's KllSketch, though two points may be worth discussing for cross-sketch / cross-language alignment:

  1. In datasketches-rust (feat(kll): add weighted update datasketches-rust#293), we made KllSketch::update_with_weight(item, 0) a no-op to match frequent_items_sketch::update(item, 0) (which is also a no-op in both Java and C++) and CountMinSketch, since repeating update(item) zero times is naturally an identity operation when weight is unsigned (e.g., pre-aggregated bucket counts that can be 0). Happy to discuss whether we want to keep KLL aligned with Java's exception here or align zero-weight handling across sketches; we documented the difference explicitly on the Rust side for now.
  2. Because check_update_item(item) runs on line 199 before the weight validation, sketch.update(NaN, 0) (and sketch.update(NaN, MAX_WEIGHT + 1)) returns silently while sketch.update(1.0f, 0) throws std::invalid_argument.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both follow datasketches-java. Its update(item, weight) returns on NaN first, then throws on a weight below 1, and C++ does the same in the same order. Whether a weight of 0 should be a no-op in every language is a good question, but it's a cross-language change, so I'd rather take it to dev@ than decide it here. For now C++ matches Java.

}
allocate_items(); // first, so that a failure leaves the sketch unchanged
reset_sorted_view(); // before any change, so that a failed copy can't leave a stale view
if (weight < levels_[0]) { // fits into level zero without compaction

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

internal_update() only compacts when levels_[0] == 0, so weight == levels_[0] also fits into level zero without compaction. With <, hitting the exact capacity boundary (for example, k = 200 with 150 updates followed by update(x, 50)) takes the merge path and transitions into estimation mode (num_levels_ = 6, 153 retained items) at n == k, whereas 50 plain update(x) calls keep all 200 items in exact mode. Using <= keeps exact mode up to n == k unless < is intentionally kept to mirror Java's guard.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is intentional. Java uses the same guard (weight < levelsArr[0]). With <=, C++ would build a different sketch from Java for the same input at that boundary, and we keep the two byte-identical.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense! One related detail just as an FYI (no action needed here): for k > 200 (DEFAULT_K), #569 initializes a new C++ sketch with items_size_ = 200 and levels_[0] = 200 (until reserve() or lazy growth), whereas Java heap KLL initializes levelsArr = {k, k}. As a result, on a fresh k = 400 sketch, update(x, 250) has 250 < levels_[0] false in C++ (taking the merge path into estimation mode) while 250 < levelsArr[0] is true in Java (staying in level zero).

/**
* Updates this sketch with the given data item repeated the given number of times.
* The result is equivalent to calling update(item) weight times, at a cost that grows
* with the logarithm of the weight rather than with the weight itself.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: when weight < levels_[0] (up to 65,534 for MAX_K), update(item, weight) runs an O(weight) copy loop into level zero rather than O(log(weight)). Describing the two paths (direct level-zero insertion when weight fits in the remaining free space, and merging a binary-level sketch otherwise) would avoid overstating the complexity bound for large k.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, fixed in #585. The doc now describes both paths.

}

SECTION("weighted update: estimation mode") {
kll_float_sketch sketch(200, std::less<float>(), 0);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: seeding random_utils::random_bit explicitly at the start of this section (as in weight 1 is a plain update on line 933) would keep it deterministic when executed standalone via Catch2 -c "weighted update: estimation mode", instead of testing 10,000 queries against the 99% confidence bound RANK_EPS_FOR_K_200 under a clock-based seed.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in #585. The section now seeds random_bit.

@leerho
leerho merged commit cbbccee into master Nov 19, 2026
35 checks passed
@leerho
leerho deleted the kll-weighted-update branch November 19, 2026 17:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants