plucky (3) mongoc_collection_watch.3.gz

Provided by: libmongoc-doc_1.30.0-1_all bug

SYNOPSIS
          mongoc_change_stream_t*
          mongoc_collection_watch (const mongoc_collection_t *coll,
                                   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 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


       2009-present, MongoDB, Inc.