You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@datasketches.apache.org by "tisonkun (via GitHub)" <gi...@apache.org> on 2026/08/11 01:59:34 UTC

[PR] docs: correct public sketch semantics (datasketches-rust)

tisonkun opened a new pull request, #196:
URL: https://github.com/apache/datasketches-rust/pull/196

   ## Summary
   
   - correct Bloom membership examples: positive results mean possibly present, while negative results mean definitely absent in normal operation
   - document Hll4, Hll6, and Hll8 as isomorphic register representations with identical accuracy for the same lg_k
   - explain how HLL union coupon-mode replay and array-mode downsampling determine the result's effective lg_k and error distribution
   - correct the documented widths of the four 64-bit SketchSlice readers
   - clarify that core Frequencies operations require Eq + Hash, while FrequentItemValue is required only for built-in serialization
   - align Theta and Tuple Jaccard seed-error documentation with the empty-input fast paths
   
   The broader post-invert Bloom contract remains tracked in #194.
   
   ## Validation
   
   - cargo x check
   - cargo x test
   - cargo x lint
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196#discussion_r3754843098


##########
datasketches/src/frequencies/mod.rs:
##########


Review Comment:
   Applied. The overview now states only the core Eq + Hash requirement, while the Serialization section states only the FrequentItemValue requirement.



##########
datasketches/src/hll/union.rs:
##########
@@ -45,6 +45,12 @@ use crate::hll::mode::Mode;
 /// the union of all input sketches. It automatically handles sketches with
 /// different configurations and modes.
 ///
+/// Coupon-mode inputs are replayed into the current gadget without reducing its `lg_k`. An
+/// array-mode input with a smaller `lg_k` reduces the gadget to that value; larger array inputs are
+/// downsampled to the gadget's current configuration. Once reduced, the effective `lg_k` remains
+/// lower until [`reset`](Self::reset), so estimates and bounds reflect the reduced register count.
+/// The requested [`HllType`] changes only the result representation, not its statistical accuracy.
+///

Review Comment:
   They are internal representation concepts. I removed those terms from both the HllUnion type documentation and the module overview, and kept the contract in terms of the observable effective lg_k and its effect on accuracy.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun merged PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196#discussion_r3754830780


##########
datasketches/src/hll/union.rs:
##########
@@ -45,6 +45,12 @@ use crate::hll::mode::Mode;
 /// the union of all input sketches. It automatically handles sketches with
 /// different configurations and modes.
 ///
+/// Coupon-mode inputs are replayed into the current gadget without reducing its `lg_k`. An
+/// array-mode input with a smaller `lg_k` reduces the gadget to that value; larger array inputs are
+/// downsampled to the gadget's current configuration. Once reduced, the effective `lg_k` remains
+/// lower until [`reset`](Self::reset), so estimates and bounds reflect the reduced register count.
+/// The requested [`HllType`] changes only the result representation, not its statistical accuracy.
+///

Review Comment:
   Is `Coupon-mode` and `array-mode` user facing concept?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196#discussion_r3754827028


##########
datasketches/src/frequencies/mod.rs:
##########


Review Comment:
   Maybe keep each section focused. Need not mention the other part.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196#discussion_r3754843098


##########
datasketches/src/frequencies/mod.rs:
##########


Review Comment:
   Applied. The overview now states only the core  requirement, while the Serialization section states only the  requirement.



##########
datasketches/src/hll/union.rs:
##########
@@ -45,6 +45,12 @@ use crate::hll::mode::Mode;
 /// the union of all input sketches. It automatically handles sketches with
 /// different configurations and modes.
 ///
+/// Coupon-mode inputs are replayed into the current gadget without reducing its `lg_k`. An
+/// array-mode input with a smaller `lg_k` reduces the gadget to that value; larger array inputs are
+/// downsampled to the gadget's current configuration. Once reduced, the effective `lg_k` remains
+/// lower until [`reset`](Self::reset), so estimates and bounds reflect the reduced register count.
+/// The requested [`HllType`] changes only the result representation, not its statistical accuracy.
+///

Review Comment:
   They are internal representation concepts. I removed those terms from both the  type documentation and the module overview, and kept the contract in terms of the observable effective  and its effect on accuracy.



##########
datasketches/src/hll/mod.rs:
##########
@@ -42,24 +42,29 @@
 //!
 //! # HLL Types
 //!
-//! Three target HLL types are supported, trading precision for memory:
+//! The three target HLL types are isomorphic representations of the same registers. Given the
+//! same `lg_k` and input, they produce identical estimates and error distributions; they trade
+//! memory layout and update performance, not statistical precision:
 //!
-//! * [`HllType::Hll4`]: 4 bits per bucket (most compact)
-//! * [`HllType::Hll6`]: 6 bits per bucket (balanced)
-//! * [`HllType::Hll8`]: 8 bits per bucket (highest precision)
+//! * [`HllType::Hll4`]: 4 bits per bucket plus an auxiliary table for rare exceptions (most
+//!   compact)
+//! * [`HllType::Hll6`]: 6 bits per bucket (fixed-size middle ground)

Review Comment:
   Applied. The Hll4 bullet now stays at the user-visible 4-bit/compact trade-off and no longer mentions the auxiliary table.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: correct public sketch semantics (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #196:
URL: https://github.com/apache/datasketches-rust/pull/196#discussion_r3754825616


##########
datasketches/src/hll/mod.rs:
##########
@@ -42,24 +42,29 @@
 //!
 //! # HLL Types
 //!
-//! Three target HLL types are supported, trading precision for memory:
+//! The three target HLL types are isomorphic representations of the same registers. Given the
+//! same `lg_k` and input, they produce identical estimates and error distributions; they trade
+//! memory layout and update performance, not statistical precision:
 //!
-//! * [`HllType::Hll4`]: 4 bits per bucket (most compact)
-//! * [`HllType::Hll6`]: 6 bits per bucket (balanced)
-//! * [`HllType::Hll8`]: 8 bits per bucket (highest precision)
+//! * [`HllType::Hll4`]: 4 bits per bucket plus an auxiliary table for rare exceptions (most
+//!   compact)
+//! * [`HllType::Hll6`]: 6 bits per bucket (fixed-size middle ground)

Review Comment:
   ```suggestion
   //! * [`HllType::Hll4`]: 4 bits per bucket (most compact)
   ```
   
   Need not expose internal concepts.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org