Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
MONGOC_DATABASE_WATCH(3)	   libmongoc	      MONGOC_DATABASE_WATCH(3)

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	 data-
       base.  If  the change stream needs to re-establish connection, the same
       read preference will be used. This may happen if	the change stream  en-
       counters	a resumable error.

       WARNING:
	  A change stream is only supported with majority read concern.

       This  function  is considered a retryable read operation.  Upon a tran-
       sient 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 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 af-
	 ter	 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  com-
	 mand 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 com-
	 mand.	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.

1.30.2				 Apr 12, 2025	      MONGOC_DATABASE_WATCH(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mongoc_database_watch&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help