esdb_aggregate_nif (reckon_db v1.2.6)

View Source

Optimized event aggregation operations for reckon-db.

This module provides high-performance event aggregation implementations:

  • aggregate_events: Bulk fold with tagged value semantics
  • sum_field: Vectorized sum accumulation for numeric fields
  • count_where: Count events matching a condition
  • merge_tagged_batch: Batch map merge with tagged values

The mode is automatically detected at startup based on whether the NIF library is available. Community edition users (hex.pm) will always use the Erlang fallbacks, which provide identical functionality.

Tagged Value Semantics

Tagged values control how fields are aggregated:

  • {sum, N}: Add N to the current value (numeric accumulation)
  • {overwrite, V}: Replace current value with V
  • Plain value: Replace current value (default behavior)

Usage

  %% Aggregate events with tagged value semantics
  Events = [#{amount => {sum, 100}}, #{amount => {sum, 50}}],
  Result = esdb_aggregate_nif:aggregate_events(Events, #{}, true),
  #{amount := 150} = Result.
 
  %% Sum a specific field across all events
  Total = esdb_aggregate_nif:sum_field(Events, amount).
 
  %% Check which mode is active
  nif = esdb_aggregate_nif:implementation().  %% Enterprise
  erlang = esdb_aggregate_nif:implementation(). %% Community

Summary

Functions

aggregate_events(Events, InitialState, Finalize)

Aggregate a list of events with tagged value semantics.

aggregation_stats(Events)

Get statistics about event aggregation.

count_where(Events, Field, Value)

Count events matching a simple field condition.

finalize(TaggedMap)

Finalize a tagged map by unwrapping all tagged values.

implementation()

Get the current implementation mode.

is_nif_loaded()

Check if the NIF is loaded (Enterprise mode).

merge_tagged_batch(Pairs, State)

Merge a batch of key-value pairs into a state map.

sum_field(Events, Field)

Sum a specific field across all events.

Functions

aggregate_events(Events, InitialState, Finalize)

-spec aggregate_events(Events :: [map()], InitialState :: map(), Finalize :: boolean()) -> map().

Aggregate a list of events with tagged value semantics.

Processes events in order, applying tagged value rules: - {sum, N} adds N to the current value - {overwrite, V} replaces the current value with V - Plain values replace the current value

If Finalize is true, the result will have tagged values unwrapped.

aggregation_stats(Events)

-spec aggregation_stats(Events :: [map()]) -> map().

Get statistics about event aggregation.

Returns counts and basic metrics about the event list.

count_where(Events, Field, Value)

-spec count_where(Events :: [map()], Field :: atom() | binary(), Value :: term()) -> non_neg_integer().

Count events matching a simple field condition.

Returns the number of events where the specified field equals the expected value.

finalize(TaggedMap)

-spec finalize(TaggedMap :: map()) -> map().

Finalize a tagged map by unwrapping all tagged values.

Converts {sum, N} to N and {overwrite, V} to V.

implementation()

-spec implementation() -> nif | erlang.

Get the current implementation mode.

is_nif_loaded()

-spec is_nif_loaded() -> boolean().

Check if the NIF is loaded (Enterprise mode).

merge_tagged_batch(Pairs, State)

-spec merge_tagged_batch(Pairs :: [{term(), term()}], State :: map()) -> map().

Merge a batch of key-value pairs into a state map.

Applies tagged value semantics to each pair.

sum_field(Events, Field)

-spec sum_field(Events :: [map()], Field :: atom() | binary()) -> number().

Sum a specific field across all events.

Efficiently accumulates numeric values from a named field. Handles tagged values ({sum, N}) and plain numeric values.