SYNOPSIS

          mongoc_change_stream_t*
          mongoc_collection_watch (const mongoc_collection_t *coll,
                                   const bson_t *pipeline,
                                   const bson_t *opts) BSON_GNUC_WARN_UNUSED_RESULT;

       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 collection. 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.

PARAMETERS

       • coll: A mongoc_collection_t specifying the collection 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: An optional UTF-8 string. Set this option  to  "default",  "updateLookup",
         "whenAvailable",  or  "required",  If  unset,  The string "default" is assumed. 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.

       • fullDocumentBeforeChange:  An optional UTF-8 string. Set this option to "whenAvailable",
         "required", or "off". When unset, the default value is "off". Similar to "fullDocument",
         but returns the value of the document before the associated change.

       • showExpandedEvents:  Set  to  true  to  return an expanded list of change stream events.
         Available only on MongoDB versions >=6.0

       • comment: A bson_value_t specifying the comment to attach to this  command.  The  comment
         will  appear  in log messages, profiler output, and currentOp output. Only string values
         are supported prior to MongoDB 4.4.

RETURNS

       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.

       SEE ALSO:
          mongoc_client_watch()

          mongoc_database_watch()

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2017-present, MongoDB, Inc