Creates a cursor for the changeStream of this collection, as configured by the builder.
Creates a cursor for the changeStream of this collection, as configured by the builder.
The resulting cursor implicitly has a tailable
and awaitData
behavior, and requires some special handling:
1. The cursor will never be exhausted, unless the change stream is invalidated (see
https://docs.mongodb.com/manual/reference/change-events/#invalidate-event).
Therefore, you need to ensure that either:
- you consume a bounded number of events from the stream (such as when using collect
, foldWhile
, etc.)
- you close the cursor explicitly when you no longer need it (the cursor provider needs to support such a
functionality)
- you only start a finite number of unbounded cursors which follow the lifecycle of your whole application (for
example they will be shut down along with the driver when the app goes down).
In particular, using fold
with the default unbounded maxSize
will yield a Future which will never resolve.
2. The cursor may yield no results within any given finite time bounds, if there are no changes in the underlying collection. Therefore, the Futures resulting from the cursor operations may never resolve. Unless you are in a fully reactive scenario, you may want to add some timeout behavior to the resulting Future. In that case, remember to explicitly close the cursor when the timeout triggers, so that you don't leak the cursor (the cursor provider needs to support such a functionality).
3. New change streams return no data when the cursor is initially established (only subsequent GetMore commands
will actually return the subsequent events). Therefore, such a cursor head
will always be empty. Only folding
the cursor (directly or through a higher-level cursor provider) will provide the next change event.
4. Resumed change streams (via id or operation time) will return the next event when the cursor is initially
established, if there is is some next event. Therefore, head
is guaranteed to eventually return the next
change event beyond the resume point, when such an event appears.
A builder for the
watch
collection helper, which allows to consume the collection's ChangeStream.