@spec add_stage(
  t(),
  struct()
) :: t()

Adds a filter stage to the chain.

The stage is automatically classified based on its module type:

• IBLT goes to the adjuncts list (not in query path)
• XorFilter is appended as a terminal query stage
• All other filters are appended as query stages

Raises InvalidChainCompositionError if the composition is invalid (e.g., adding a query stage after a XorFilter terminal).

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> length(ExDataSketch.FilterChain.stages(chain))
1

@spec adjuncts(t()) :: [struct()]

Returns the list of adjunct stages.

Examples

iex> ExDataSketch.FilterChain.adjuncts(ExDataSketch.FilterChain.new())
[]

Returns the set of capabilities supported by FilterChain.

@spec count(t()) :: non_neg_integer()

Returns the sum of counts across all query stages.

Examples

iex> ExDataSketch.FilterChain.count(ExDataSketch.FilterChain.new())
0

@spec delete(t(), term()) :: {:ok, t()}

Deletes an item from all query stages.

Raises UnsupportedOperationError if any query stage does not support :delete (e.g., Bloom or XorFilter).

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> cuckoo = ExDataSketch.Cuckoo.new()
iex> {:ok, cuckoo} = ExDataSketch.Cuckoo.put(cuckoo, "hello")
iex> chain = ExDataSketch.FilterChain.add_stage(chain, cuckoo)
iex> {:ok, chain} = ExDataSketch.FilterChain.delete(chain, "hello")
iex> ExDataSketch.FilterChain.member?(chain, "hello")
false

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

Deserializes an FCN1 binary into a FilterChain.

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

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> binary = ExDataSketch.FilterChain.serialize(chain)
iex> {:ok, recovered} = ExDataSketch.FilterChain.deserialize(binary)
iex> length(ExDataSketch.FilterChain.stages(recovered))
1

@spec member?(t(), term()) :: boolean()

Tests whether an item may be a member by querying all stages in order.

Short-circuits on the first false result. Adjuncts are not queried. Returns false if the chain has no query stages.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> bloom = ExDataSketch.Bloom.new(capacity: 100) |> ExDataSketch.Bloom.put("hello")
iex> chain = ExDataSketch.FilterChain.add_stage(chain, bloom)
iex> ExDataSketch.FilterChain.member?(chain, "hello")
true

@spec new() :: t()

Creates an empty FilterChain.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> ExDataSketch.FilterChain.stages(chain)
[]

@spec put(t(), term()) :: {:ok, t()} | {:error, :full}

Inserts an item into all query stages that support :put.

Skips static stages (XorFilter). Returns {:ok, chain} on success or {:error, :full} if a Cuckoo stage is full.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> {:ok, chain} = ExDataSketch.FilterChain.put(chain, "hello")
iex> ExDataSketch.FilterChain.member?(chain, "hello")
true

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

Serializes the FilterChain to the FCN1 binary format.

Each stage is serialized independently using its own serialize/1, then wrapped in a chain manifest.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> binary = ExDataSketch.FilterChain.serialize(chain)
iex> <<"FCN1", _rest::binary>> = binary
iex> byte_size(binary) > 0
true

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

Callback implementation for ExDataSketch.Sketch.size_bytes/1.

@spec stages(t()) :: [struct()]

Returns the list of query stages.

Examples

iex> ExDataSketch.FilterChain.stages(ExDataSketch.FilterChain.new())
[]

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

Inserts an item into all query stages that support :put, raising if a stage is full.

Added so ExDataSketch.FilterChain satisfies the ExDataSketch.Sketch behaviour's generic update/2 callback, which requires a bare-struct return. put/2 (returning {:ok, chain} | {:error, :full}) remains the family-idiomatic name for callers who need to detect a full stage.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> chain = ExDataSketch.FilterChain.update(chain, "hello")
iex> ExDataSketch.FilterChain.member?(chain, "hello")
true

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

Inserts every item in an enumerable via update/2, raising if a stage fills up partway through.

Added so ExDataSketch.FilterChain satisfies the ExDataSketch.Sketch behaviour's generic update_many/2 callback.

Examples

iex> chain = ExDataSketch.FilterChain.new()
iex> chain = ExDataSketch.FilterChain.add_stage(chain, ExDataSketch.Bloom.new(capacity: 100))
iex> chain = ExDataSketch.FilterChain.update_many(chain, ["a", "b", "c"])
iex> ExDataSketch.FilterChain.member?(chain, "a")
true