SYNOPSIS

          mongoc_change_stream_t*
          mongoc_database_watch (const mongoc_database_t *db,
                                 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 database. 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

       • db: A mongoc_database_t <> specifying the database which the change stream listens to.

       • pipeline: A bson_t  <https://www.mongoc.org/libbson/current/bson_t.html>  representing  an  aggregation
         pipeline appended to the change stream. This may be an empty document.

       • opts: A bson_t <https://www.mongoc.org/libbson/current/bson_t.html> containing change stream options.

       Changed in version 2.0.0: batchSize of 0 is applied to the aggregate command. 0 was previously ignored.

       opts may be NULL or a BSON document with additional command options:

       • batchSize:  An  int32  requesting  a limit of documents returned in each server reply. If positive, the
         batchSize is applied to both aggregate and getMore commands. If 0, the batchSize is only applied to the
         aggregate command (Useful to request an immediate cursor  without  significant  server-side  work.  See
         Aggregate Data Specifying Batch Size <https://www.mongodb.com/docs/manual/reference/command/aggregate/#
         aggregate-data-specifying-batch-size>).  If  omitted  or  negative,  the  value  is  ignored and server
         defaults   are   used   (See   Cursor    Batches    <https://www.mongodb.com/docs/manual/core/cursors/#
         cursor-batches> for a description of server defaults).

       • 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  <https://www.mongoc.org/libbson/current/bson_value_t.html>  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_collection_watch() <>

Author

       MongoDB, Inc

Copyright

       2009-present, MongoDB, Inc.

2.2.1                                             Dec 11, 2025                          MONGOC_DATABASE_WATCH(3)