@spec capabilities() :: ExDataSketch.Sketch.capabilities()

Returns the set of operation names supported by ExDataSketch.ULL.

See ExDataSketch.Sketch for the shared capability vocabulary.

Examples

iex> ExDataSketch.ULL.capabilities() |> MapSet.member?(:estimate)
true

iex> ExDataSketch.ULL.capabilities() |> MapSet.member?(:no_such_operation)
false

@spec count(t()) :: float()

Alias for estimate/1.

Examples

iex> ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.count()
0.0

@spec deserialize(binary()) :: {:ok, t()} | {:error, Exception.t()}

Deserializes an EXSK binary into a ULL sketch.

Returns {:ok, sketch} on success or {:error, reason} on failure.

Examples

iex> ExDataSketch.ULL.deserialize(<<"invalid">>)
{:error, %ExDataSketch.Errors.DeserializationError{message: "deserialization failed: invalid magic bytes, expected EXSK"}}

@spec estimate(t()) :: float()

Estimates the number of distinct items in the sketch.

Returns a floating-point estimate. The accuracy depends on the precision parameter p. ULL typically achieves ~20% lower relative error than HLL at the same precision.

Examples

iex> ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.estimate()
0.0

@spec from_enumerable(
  Enumerable.t(),
  keyword()
) :: t()

Creates a new ULL sketch from an enumerable of items.

Equivalent to new(opts) |> update_many(enumerable).

Options

Same as new/1.

Examples

iex> sketch = ExDataSketch.ULL.from_enumerable(["a", "b", "c"], p: 10)
iex> ExDataSketch.ULL.estimate(sketch) > 0.0
true

@spec merge(t(), t()) :: t()

Merges two ULL sketches.

Both sketches must have the same precision p. The result contains the register-wise maximum, which corresponds to the union of the two input multisets.

Returns the merged sketch. Raises ExDataSketch.Errors.IncompatibleSketchesError if the sketches have different parameters.

Examples

iex> a = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update("x")
iex> b = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update("y")
iex> merged = ExDataSketch.ULL.merge(a, b)
iex> ExDataSketch.ULL.estimate(merged) >= ExDataSketch.ULL.estimate(a)
true

@spec merge_many(Enumerable.t()) :: t()

Merges a non-empty enumerable of ULL sketches into one.

Raises Enum.EmptyError if the enumerable is empty.

Examples

iex> a = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update("x")
iex> b = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update("y")
iex> merged = ExDataSketch.ULL.merge_many([a, b])
iex> ExDataSketch.ULL.estimate(merged) > 0.0
true

@spec merger(keyword()) :: (t(), t() -> t())

Returns a 2-arity merge function suitable for combining sketches.

The returned function calls merge/2 on two sketches.

Examples

iex> is_function(ExDataSketch.ULL.merger(), 2)
true

@spec new(keyword()) :: t()

Creates a new ULL sketch.

Options

• :p - precision parameter, integer 4..26 (default: 14). Higher values use more memory but give better accuracy.
• :backend - backend module (default: ExDataSketch.Backend.Pure).
• :hash_fn - custom hash function (term -> non_neg_integer).
• :seed - hash seed (default: 0).

Examples

iex> sketch = ExDataSketch.ULL.new(p: 10)
iex> sketch.opts[:p]
10
iex> ExDataSketch.ULL.size_bytes(sketch)
1032

@spec reducer() :: (term(), t() -> t())

Returns a 2-arity reducer function suitable for Enum.reduce/3 and similar.

The returned function calls update/2 on each item.

Examples

iex> is_function(ExDataSketch.ULL.reducer(), 2)
true

@spec serialize(
  t(),
  keyword()
) :: binary()

Serializes the sketch to the ExDataSketch-native EXSK binary format.

The serialized binary includes magic bytes, version, sketch type, parameters, and state. See ExDataSketch.Codec for format details.

Options

• :format - serialization format: :v2 (default, EXSK v2 with CRC32C) or :v1 (legacy EXSK v1, compatible with v0.7.x readers). The v1 format is only valid for sketches using :phash2 hash strategy.

Examples

iex> sketch = ExDataSketch.ULL.new(p: 10)
iex> binary = ExDataSketch.ULL.serialize(sketch)
iex> <<"EXSK", _rest::binary>> = binary
iex> byte_size(binary) > 0
true

iex> sketch = ExDataSketch.ULL.new(p: 10, hash_strategy: :phash2)
iex> binary = ExDataSketch.ULL.serialize(sketch, format: :v1)
iex> <<"EXSK", 1, 15, _rest::binary>> = binary

@spec size_bytes(t()) :: non_neg_integer()

Returns the size of the sketch state in bytes.

Examples

iex> ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.size_bytes()
1032

@spec update(t(), term()) :: t()

Updates the sketch with a single item.

The item is hashed using ExDataSketch.Hash.hash64/1 before being inserted into the sketch.

Examples

iex> sketch = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update("hello")
iex> ExDataSketch.ULL.estimate(sketch) > 0.0
true

@spec update_many(t(), Enumerable.t()) :: t()

Updates the sketch with multiple items in a single pass.

More efficient than calling update/2 repeatedly because it minimizes intermediate binary allocations.

The internal batch size is controlled by :update_many_chunk_size, which must be set at new/1 time and cannot be changed per call.

Examples

iex> sketch = ExDataSketch.ULL.new(p: 10) |> ExDataSketch.ULL.update_many(["a", "b", "c"])
iex> ExDataSketch.ULL.estimate(sketch) > 0.0
true