KllSketch
Defined in: packages/distillate/src/kll/kll.ts:64
A KLL sketch: quantiles and ranks of a stream of numbers, each within a
rank error of about 1.3% at the default k, in memory fixed by k.
Example
Section titled “Example”const latency = KllSketch.create(0.01);latency.add(12.5);Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new KllSketch(
params?):KllSketch
Defined in: packages/distillate/src/kll/kll.ts:84
Creates a sketch at an explicit k.
Parameters
Section titled “Parameters”params?
Section titled “params?”KllParams = {}
Accuracy and optional seed.
Returns
Section titled “Returns”KllSketch
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get count():
number
Defined in: packages/distillate/src/kll/kll.ts:290
Values recorded, weights included.
Returns
Section titled “Returns”number
isEmpty
Section titled “isEmpty”Get Signature
Section titled “Get Signature”get isEmpty():
boolean
Defined in: packages/distillate/src/kll/kll.ts:295
Whether no value has been recorded.
Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get k():
number
Defined in: packages/distillate/src/kll/kll.ts:285
Items the top level holds.
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get max():
number
Defined in: packages/distillate/src/kll/kll.ts:315
The largest value recorded, exactly; NaN while empty.
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get min():
number
Defined in: packages/distillate/src/kll/kll.ts:310
The smallest value recorded, exactly; NaN while empty.
Returns
Section titled “Returns”number
numLevels
Section titled “numLevels”Get Signature
Section titled “Get Signature”get numLevels():
number
Defined in: packages/distillate/src/kll/kll.ts:305
Levels of compaction, 1 until the first.
Returns
Section titled “Returns”number
retained
Section titled “retained”Get Signature
Section titled “Get Signature”get retained():
number
Defined in: packages/distillate/src/kll/kll.ts:300
Items the sketch holds.
Returns
Section titled “Returns”number
Methods
Section titled “Methods”add(
value,count?):void
Defined in: packages/distillate/src/kll/kll.ts:513
Records a value.
Parameters
Section titled “Parameters”number
Any number but NaN; infinities and -0 are ordered as
numbers.
count?
Section titled “count?”number = 1
How many times to record it; a positive safe integer.
Returns
Section titled “Returns”void
Throws
Section titled “Throws”ParamError when value is NaN, count is not a
positive safe integer, or the count would pass Number.MAX_SAFE_INTEGER.
Nothing is recorded.
cdf(
splits):number[]
Defined in: packages/distillate/src/kll/kll.ts:408
The cumulative distribution at splits: the fraction of the stream at or
below each, then 1 for everything, each within the rank error.
Parameters
Section titled “Parameters”splits
Section titled “splits”readonly number[]
Strictly increasing numbers, none NaN.
Returns
Section titled “Returns”number[]
splits.length + 1 fractions; all NaN while empty.
Throws
Section titled “Throws”ParamError when splits are not strictly increasing or
hold NaN.
equals()
Section titled “equals()”equals(
other):boolean
Defined in: packages/distillate/src/kll/kll.ts:260
Tests structural equality: true when other serializes to identical
bytes, meaning the same k, generator state, counts and items.
Parameters
Section titled “Parameters”KllSketch
The sketch to compare against.
Returns
Section titled “Returns”boolean
true if the two sketches are byte-for-byte identical.
normalizedRankError()
Section titled “normalizedRankError()”normalizedRankError(
pmf?):number
Defined in: packages/distillate/src/kll/kll.ts:326
Rank error at 99% confidence, as a fraction of count.
Parameters
Section titled “Parameters”boolean = false
true for the error over every rank of a CDF or PMF at
once, false (the default) for a single rank or quantile.
Returns
Section titled “Returns”number
The normalized rank error.
pmf(
splits):number[]
Defined in: packages/distillate/src/kll/kll.ts:429
The mass between splits: the fraction of the stream at or below the
first, then in each interval up to the next, then above the last.
Parameters
Section titled “Parameters”splits
Section titled “splits”readonly number[]
Strictly increasing numbers, none NaN.
Returns
Section titled “Returns”number[]
splits.length + 1 fractions summing to 1; all NaN while
empty.
Throws
Section titled “Throws”ParamError as KllSketch.cdf does.
quantile()
Section titled “quantile()”quantile(
q):number
Defined in: packages/distillate/src/kll/kll.ts:339
The value at quantile q: the item at rank floor(q * (count - 1)) of
the stream, within the rank error. q = 0 and q = 1 give min and
max exactly.
Parameters
Section titled “Parameters”number
The quantile, in [0, 1].
Returns
Section titled “Returns”number
The estimate, or NaN when the sketch is empty.
Throws
Section titled “Throws”ParamError when q is outside [0, 1].
quantiles()
Section titled “quantiles()”quantiles(
qs):number[]
Defined in: packages/distillate/src/kll/kll.ts:344
KllSketch.quantile for each of qs, in order.
Parameters
Section titled “Parameters”readonly number[]
Returns
Section titled “Returns”number[]
rank()
Section titled “rank()”rank(
x):number
Defined in: packages/distillate/src/kll/kll.ts:375
The fraction of the stream at or below x, within the rank error.
Parameters
Section titled “Parameters”number
Any number but NaN.
Returns
Section titled “Returns”number
The rank in [0, 1], or NaN when the sketch is empty.
toBytes()
Section titled “toBytes()”toBytes():
Uint8Array
Defined in: packages/distillate/src/kll/kll.ts:223
Serializes the sketch, generator state included, to a portable little-endian byte layout.
Returns
Section titled “Returns”Uint8Array
The serialized sketch, readable by KllSketch.fromBytes.
toJSON()
Section titled “toJSON()”toJSON():
FilterJSON
Defined in: packages/distillate/src/kll/kll.ts:270
Serializes the sketch to a JSON-safe envelope wrapping KllSketch.toBytes.
Returns
Section titled “Returns”The envelope, readable by KllSketch.fromJSON.
union()
Section titled “union()”union(
other):KllSketch
Defined in: packages/distillate/src/kll/kll.ts:448
Merges two sketches into a new one that answers as a single sketch fed both streams would, within the rank error. Both are left untouched.
The result keeps the smaller k, as HyperLogLog keeps the coarser
precision, so a coarse sketch merged with a fine one has the coarse one’s
accuracy.
Parameters
Section titled “Parameters”KllSketch
The sketch to merge with.
Returns
Section titled “Returns”KllSketch
A new sketch of both streams, which takes values and further unions.
Throws
Section titled “Throws”ParamError when the merged count would pass
Number.MAX_SAFE_INTEGER.
create()
Section titled “create()”
staticcreate(rankError):KllSketch
Defined in: packages/distillate/src/kll/kll.ts:104
Creates a sketch whose single-rank error meets rankError.
Parameters
Section titled “Parameters”rankError
Section titled “rankError”number
Target normalized rank error, e.g. 0.01 for 1%.
Returns
Section titled “Returns”KllSketch
A new, empty sketch.
fromBytes()
Section titled “fromBytes()”
staticfromBytes(bytes):KllSketch
Defined in: packages/distillate/src/kll/kll.ts:117
Restores a sketch from KllSketch.toBytes. It goes on taking values and flipping the coins the sketch that wrote it would have.
Parameters
Section titled “Parameters”Uint8Array
The serialized sketch.
Returns
Section titled “Returns”KllSketch
The reconstructed sketch.
Throws
Section titled “Throws”SerializationError when the frame is malformed or not a KLL sketch.
fromJSON()
Section titled “fromJSON()”
staticfromJSON(value):KllSketch
Defined in: packages/distillate/src/kll/kll.ts:280
Restores a sketch from its KllSketch.toJSON envelope.
Parameters
Section titled “Parameters”unknown
The parsed envelope.
Returns
Section titled “Returns”KllSketch
The reconstructed sketch.