reckon_db_filters (reckon_db v2.3.0)

View Source

Khepri event filters for reckon-db

Provides filter builders for Khepri event subscriptions. These filters are used to watch for new events matching specific criteria.

Summary

Types

event/0
subscription_type/0

Functions

by_event_pattern(EventPattern)

Create a filter matching events with a specific pattern in their metadata

by_event_payload(PayloadPattern)

Create a filter matching events with a specific pattern in their payload

by_event_type(EventType)

Create a filter for events of a specific type

by_stream(Stream)

Create a filter for all events in a specific stream

by_tags(Tags)

Create a filter matching events with specific tags

matches(Type, StreamId, Event)

In-memory predicate matching an #event{} record against a subscription's (Type, Selector) pair.

Types

event/0

-type event() ::
          #event{event_id :: binary(),
                 event_type :: binary(),
                 stream_id :: binary(),
                 version :: non_neg_integer(),
                 data :: map() | binary(),
                 metadata :: map(),
                 tags :: [binary()] | undefined,
                 timestamp :: integer(),
                 epoch_us :: integer(),
                 data_content_type :: binary(),
                 metadata_content_type :: binary(),
                 prev_event_hash :: binary() | undefined,
                 mac :: {KeyId :: non_neg_integer(), MacBytes :: binary()} | undefined,
                 signature :: binary() | undefined}.

subscription_type/0

-type subscription_type() ::
          stream | event_type | event_pattern | event_payload | tags | by_stream | by_event_type |
          by_event_pattern | by_event_payload | by_tags.

Functions

by_event_pattern(EventPattern)

-spec by_event_pattern(map()) -> khepri_evf:tree_event_filter().

Create a filter matching events with a specific pattern in their metadata

The pattern is a map that must be a subset of the event record.

by_event_payload(PayloadPattern)

-spec by_event_payload(map()) -> khepri_evf:tree_event_filter().

Create a filter matching events with a specific pattern in their payload

The pattern is checked against the data field of the event.

by_event_type(EventType)

-spec by_event_type(binary()) -> khepri_evf:tree_event_filter().

Create a filter for events of a specific type

Uses #event{} record pattern matching since events are stored as records.

by_stream(Stream)

-spec by_stream(binary()) -> khepri_evf:tree_event_filter() | {error, invalid_stream}.

Create a filter for all events in a specific stream

Special case: the binary <<"$all">> matches events in all streams.

by_tags(Tags)

-spec by_tags([binary()]) -> khepri_evf:tree_event_filter().

Create a filter matching events with specific tags

Note: Khepri's pattern matching doesn't natively support list membership, so this creates a broad filter that matches all events with tags. The actual tag filtering must be done by the subscription consumer. For efficient tag-based queries, use reckon_db_streams:read_by_tags/4.

matches(Type, StreamId, Event)

-spec matches(subscription_type(), binary() | map() | [binary()], event()) -> boolean().

In-memory predicate matching an #event{} record against a subscription's (Type, Selector) pair.

The Khepri event filters above are evaluated by Khepri itself on live triggers, but the catch-up replay path bypasses Khepri's trigger engine — it reads the global stream and delivers events directly to the subscriber. Without this predicate, every subscription with start_from = 0 would receive the entire log regardless of its declared selector. Use this to filter the catch-up batch before sending.

Tag membership uses set inclusion: the event must carry ALL of the requested tags (consistent with read_by_tags default match semantics).