reckon_db_temporal (reckon_db v1.6.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()}.

opts/0

-type opts() :: #{direction => forward | backward, limit => pos_integer()}.

timestamp/0

-type timestamp() :: integer().

Microseconds since epoch (epoch_us format)

Functions

read_range(StoreId, StreamId, FromTimestamp, ToTimestamp)

-spec read_range(atom(), binary(), timestamp(), timestamp()) -> {ok, [event()]} | {error, term()}.

Read events within a time range [FromTimestamp, ToTimestamp].

Returns events where FromTimestamp is less than or equal to epoch_us, and epoch_us is less than or equal to ToTimestamp.

Example:

  %% Get all events from the first week of 2025
  From = 1735689600000000,  %% Jan 1, 2025
  To   = 1736294400000000,  %% Jan 8, 2025
  {ok, Events} = reckon_db_temporal:read_range(my_store, <<"orders-123">>, From, To).

read_range(StoreId, StreamId, FromTimestamp, ToTimestamp, Opts)

-spec read_range(atom(), binary(), timestamp(), timestamp(), opts()) ->
                    {ok, [event()]} | {error, term()}.

Read events within a time range with options.

read_until(StoreId, StreamId, Timestamp)

-spec read_until(atom(), binary(), timestamp()) -> {ok, [event()]} | {error, term()}.

Read all events from a stream up to (and including) a timestamp.

Returns events where epoch_us is less than or equal to Timestamp, sorted by version (ascending). This is useful for reconstructing aggregate state at a point in time.

Example:

  %% Get all events up to January 1, 2025 00:00:00 UTC
  Timestamp = 1735689600000000, %% microseconds
  {ok, Events} = reckon_db_temporal:read_until(my_store, <<"orders-123">>, Timestamp).

read_until(StoreId, StreamId, Timestamp, Opts)

-spec read_until(atom(), binary(), timestamp(), opts()) -> {ok, [event()]} | {error, term()}.

Read events up to a timestamp with options.

Options: - direction: forward (default) or backward - limit: Maximum number of events to return

version_at(StoreId, StreamId, Timestamp)

-spec version_at(atom(), binary(), timestamp()) -> {ok, integer()} | {error, term()}.

Get the stream version at a specific timestamp.

Returns the version of the last event with epoch_us less than or equal to Timestamp. This is useful for determining what version to replay up to.

Returns: - {ok, Version} if events exist before the timestamp - {ok, -1} if no events exist before the timestamp - {error, Reason} on failure