MONGOC_DATABASE_WATCH(3)

📦
version 2.5.6 · 16 versions
, in epel 10

MONGOC_DATABASE_WATCH 💅✨

(that's a libmongoc page, bestie — section 3, the library one 🎀)

okay so welcome to the glow-up of mongoc_database_watch — the function that lets you watch a whole database like it's your fave reality show and every change is a plot twist 🌸

✨ SYNOPSIS ✨

mongoc_change_stream_t*
mongoc_database_watch (const mongoc_database_t *db,
                       const bson_t *pipeline,
                       const bson_t *opts);

💖 DESCRIPTION 💖

so this is the helper function that creates a change stream. and like, yes, you could hand-roll a raw aggregation to do the same thing, but bestie — it is preferred to call this function over using a raw aggregation. trust. 🫶

this function uses the read preference and read concern of the database. and if the change stream ever needs to re-establish connection, it uses that same read preference again — which can happen if the change stream encounters a resumable error. no cap. 🔥

⚠️ WARNING: a change stream is only supported with majority read concern. literally that one. don't come at me with anything else. 💀

this function is considered a retryable read operation. so upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. but — if retryreads is false in the URI (see mongoc_uri_t), the retry behavior does not apply. periodt. 👑

🌈 PARAMETERS 🌈

  • db — a mongoc_database_t specifying the database which the change stream listens to. it's giving main character energy, the whole db is the show 💅
  • pipeline — a bson_t representing an aggregation pipeline appended to the change stream. it may be an empty document, so no pressure. 🦋
  • opts — a bson_t containing change stream options. (more on these in a sec, bestie 👀)
✨ Changed in version 2.0.0: batchSize of 0 is applied to the aggregate command. 0 was previously ignored. so if you were relying on the old ignore-y behavior… she's gone. 😭

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). if omitted or negative, the value is ignored and server defaults are used (see Cursor Batches for a description of server defaults). lowkey the most misunderstood option in the whole doc, ngl. 🍓
  • 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. pick one, bestie, this is not a polycule 💀
  • startAfter — a Document representing the logical starting point of the change stream. unlike resumeAfter, this can resume notifications after an "invalidate" event (iconic behavior honestly). 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. yes she will just sit there. patient queen. 🌸
  • 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. that's the whole point, and it ate. 🔥
  • 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. the before pic!! 📸
  • showExpandedEvents — set to true to return an expanded list of change stream events. available only on MongoDB versions >=6.0. check your version first, i'm begging 🧚
  • 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. so if you're on old MongoDB, string only, no exceptions 💅

🎀 RETURNS 🎀

a newly allocated mongoc_change_stream_t which must be freed with mongoc_change_stream_destroy() when no longer in use. (yes, that means you. free her. 🫶)

the returned mongoc_change_stream_t is never NULL — like, ever, so don't @ me. 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()

(the whole watch family, we love a cohesive unit 💜)

🌟 AUTHOR 🌟

MongoDB, Inc

2009-present, MongoDB, Inc.

and that's the whole page, bestie — no crumbs left 🦋✨ this was MONGOC_DATABASE_WATCH(3) from libmongoc, version 2.5.6, dated Oct 09, 2026. go forth and watch that database. slay. 💅🌸

📦 where this page comes from