mongoc_client_watch - mongoc_client_watch()
mongoc_change_stream_t*
mongoc_client_watch (mongoc_client_t *client,
const bson_t *pipeline,
const bson_t *opts);
A helper function to create a change stream. It is preferred to
call this function over using a raw aggregation to create a change
stream.
This function uses the read preference and read concern of the
client. If the change stream needs to re-establish connection, the same read
preference will be used. This may happen if the change stream encounters a
resumable error.
WARNING:
A change stream is only supported with majority read
concern.
This function is considered a retryable read operation. Upon a
transient error (a network error, errors due to replica set failover, etc.)
the operation is safely retried once. If retryreads is false in the
URI (see mongoc_uri_t) the retry behavior does not apply.
- db: A mongoc_client_t specifying the client which the change
stream listens to.
- pipeline: A bson_t representing an aggregation pipeline
appended to the change stream. This may be an empty document.
- opts: A bson_t containing change stream options.
opts may be NULL or a BSON document with additional command
options:
- batchSize: An int32 representing number of documents
requested to be returned on each call to
mongoc_change_stream_next
- resumeAfter: A Document representing the logical starting
point of the change stream. The result of
mongoc_change_stream_get_resume_token() or the _id field of
any change received from a change stream can be used here. This option is
mutually exclusive with startAfter and
startAtOperationTime.
- startAfter: A Document representing the logical starting
point of the change stream. Unlike resumeAfter, this can resume
notifications after an "invalidate" event. The result of
mongoc_change_stream_get_resume_token() or the _id field of
any change received from a change stream can be used here. This option is
mutually exclusive with resumeAfter and
startAtOperationTime.
- startAtOperationTime: A Timestamp. The change stream only
provides changes that occurred at or after the specified timestamp. Any
command run against the server will return an operation time that can be
used here. This option is mutually exclusive with resumeAfter and
startAfter.
- maxAwaitTimeMS: An int64 representing the maximum amount of
time a call to mongoc_change_stream_next will block waiting for
data
- fullDocument: A UTF-8 string. Set this option to
"updateLookup" to direct the change stream cursor to lookup the
most current majority-committed version of the document associated to an
update change stream event.
A newly allocated mongoc_change_stream_t which must be
freed with mongoc_change_stream_destroy when no longer in use. The
returned mongoc_change_stream_t is never NULL. If there is an
error, it can be retrieved with mongoc_change_stream_error_document,
and subsequent calls to mongoc_change_stream_next will return
false.
mongoc_database_watch
mongoc_collection_watch
2017-present, MongoDB, Inc