Spear.read_stream
read_stream
, go back to Spear module for more information.
Specs
read_stream(Spear.Connection.t(), String.t(), Keyword.t()) :: {:ok, event_stream :: Enumerable.t()} | {:error, any()}
Reads a chunk of events from an EventStoreDB stream into an enumerable
Unlike stream!/3
, this function will only read one chunk of events at a time
specified by the :max_count
option. This function also does not raise in
cases of error, instead returning an ok- or error-tuple.
If the stream_name
EventStoreDB stream does not exist (is empty) and the
gRPC request succeeds for this function, {:ok, []}
will be returned.
Options
:from
- (default::start
) the EventStoreDB stream revision from which to read. Valid values include:start
,:end
, any non-negative integer representing the event number revision in the stream and events. Event numbers are inclusive (e.g. reading from0
will first return the event with revision0
in the stream, if one exists).:start
and:end
are treated as inclusive (e.g.:start
will return the first event in the stream). Events (eitherSpear.Event
or ReadResp records) can also be supplied and will be treated as inclusive.:direction
- (default::forwards
) the direction in which to read the EventStoreDB stream. Valid values include:forwards
and:backwards
. Reading the EventStoreDB stream forwards will return events in the order in which they were written to the EventStoreDB; reading backwards will return events in the opposite order.:resolve_links?
- (default:true
) whether or not to request that link references be resolved. See the moduledocs for more information about link resolution.:max_count
- (default:42
) the maximum number of events to read from the EventStoreDB stream. Any positive integer is valid. Even if the stream is longer than this:max_count
option, only:max_count
events will be returned from this function.:infinity
is not a valid value for:max_count
. Usestream!/3
for an enumerable which reads an EventStoreDB stream in its entirety in chunked network requests.:timeout
- (default:5_000
- 5s) the time allowed for the read of the single chunk of events in the EventStoreDB stream. Note that the gRPC request which reads events from the EventStoreDB is front-loaded in this function: the:timeout
covers the time it takes to read the events. The timeout may be exceeded:raw?:
- (default:false
) controls whether or not the enumerableevent_stream
is decoded toSpear.Event
structs from their rawReadResp
output. Settingraw?: true
prevents this transformation and leaves each event as aSpear.Records.Streams.read_resp/0
record. SeeSpear.Event.from_read_response/2
for more information.:credentials
- (default:nil
) a two-tuple{username, password}
to use as credentials for the request. This option overrides any credentials set in the connection configuration, if present. See the Security guide for more details.
Timing and Timeouts
The gRPC request which reads events from the EventStoreDB is front-loaded
in this function: this function returns immediately after receiving all data
off the wire from the network request. This means that the :timeout
option
covers the gRPC request and response time but not any time spend decoding
the response (see the Enumeration Characteristics section below for more
details on how the enumerable decodes messages).
The default timeout of 5s may not be enough time in cases of either reading very large numbers of events or reading events with very large bodies.
Note that up to the :max_count
of events is returned from this call
depending on however many events are in the EventStoreDB stream being read.
When tuning the :timeout
option, make sure to test against a stream which
is at least as long as :max_count
events.
Enumeration Characteristics
The event_stream
Enumerable.t/0
returned in the success case of this
function is a wrapper around the bytes received from the gRPC response. Note
that when the {:ok, event_stream}
is returned, the gRPC request has already
concluded.
This offers only marginal performance improvement: an enumerable is returned mostly for consistency in the Spear API.
Examples
# say we have 5 events in the stream "es_supported_clients"
iex> {:ok, events} = Spear.read_stream(conn, "es_supported_clients", max_count: 2)
iex> events |> Enum.count()
2
iex> {:ok, events} = Spear.read_stream(conn, "es_supported_clients", max_count: 10)
iex> events |> Enum.count()
5
iex> events |> Enum.take(1)
[
%Spear.Event{
body: %{"languages" => ["typescript", "javascript"], "runtime" => "NodeJS"},
id: "1fc908c1-af32-4d06-a9bd-3bf86a833fdf",
metadata: %{..},
type: "grpc-client"
}
]