1MONGOC_CLIENT_WATCH(3)             libmongoc            MONGOC_CLIENT_WATCH(3)
2
3
4

SYNOPSIS

6          mongoc_change_stream_t*
7          mongoc_client_watch (mongoc_client_t *client,
8                               const bson_t *pipeline,
9                               const bson_t *opts) BSON_GNUC_WARN_UNUSED_RESULT;
10
11       A  helper  function  to create a change stream. It is preferred to call
12       this function over using a raw aggregation to create a change stream.
13
14       This function uses the read preference and read concern of the  client.
15       If  the  change  stream needs to re-establish connection, the same read
16       preference will be used. This may happen if the change  stream  encoun‐
17       ters a resumable error.
18
19       WARNING:
20          A change stream is only supported with majority read concern.
21
22       This  function  is considered a retryable read operation.  Upon a tran‐
23       sient error (a network error, errors due to replica set failover, etc.)
24       the  operation  is  safely retried once.  If retryreads is false in the
25       URI (see mongoc_uri_t) the retry behavior does not apply.
26

PARAMETERS

28       • db: A mongoc_client_t specifying the client which the  change  stream
29         listens to.
30
31       • pipeline:  A  bson_t representing an aggregation pipeline appended to
32         the change stream. This may be an empty document.
33
34       • opts: A bson_t containing change stream options.
35
36       opts may be NULL or a BSON document with additional command options:
37
38       • batchSize: An int32 representing number of documents requested to  be
39         returned on each call to mongoc_change_stream_next()
40
41       • resumeAfter:  A  Document  representing the logical starting point of
42         the        change        stream.        The         result         of
43         mongoc_change_stream_get_resume_token()  or  the  _id  field   of any
44         change received from a change stream can be used here. This option is
45         mutually exclusive with startAfter and startAtOperationTime.
46
47       • startAfter: A Document representing the logical starting point of the
48         change stream. Unlike resumeAfter, this can resume notifications  af‐
49         ter      an      "invalidate"      event.      The      result     of
50         mongoc_change_stream_get_resume_token() or  the  _id  field   of  any
51         change  received  from a change stream can be used here.  This option
52         is mutually exclusive with resumeAfter and startAtOperationTime.
53
54       • startAtOperationTime: A Timestamp. The change  stream  only  provides
55         changes  that  occurred at or after the specified timestamp. Any com‐
56         mand run against the server will return an operation time that can be
57         used  here.  This  option  is mutually exclusive with resumeAfter and
58         startAfter.
59
60       • maxAwaitTimeMS: An int64 representing the maximum amount  of  time  a
61         call to mongoc_change_stream_next() will block waiting for data
62
63       • fullDocument: An optional UTF-8 string. Set this option to "default",
64         "updateLookup", "whenAvailable", or "required", If unset, The  string
65         "default" is assumed. Set this option to "updateLookup" to direct the
66         change stream cursor to lookup the  most  current  majority-committed
67         version of the document associated to an update change stream event.
68
69       • fullDocumentBeforeChange:  An  optional UTF-8 string. Set this option
70         to "whenAvailable", "required", or "off".  When  unset,  the  default
71         value  is  "off". Similar to "fullDocument", but returns the value of
72         the document before the associated change.
73
74       • showExpandedEvents: Set to true to return an expanded list of  change
75         stream events. Available only on MongoDB versions >=6.0
76
77       • comment: A bson_value_t specifying the comment to attach to this com‐
78         mand. The comment will appear in log messages, profiler  output,  and
79         currentOp  output.  Only string values are supported prior to MongoDB
80         4.4.
81

RETURNS

83       A newly allocated  mongoc_change_stream_t  which  must  be  freed  with
84       mongoc_change_stream_destroy()  when  no  longer  in  use. The returned
85       mongoc_change_stream_t is never NULL. If there is an error, it  can  be
86       retrieved  with  mongoc_change_stream_error_document(),  and subsequent
87       calls to mongoc_change_stream_next() will return false.
88
89       SEE ALSO:
90          mongoc_database_watch()
91
92          mongoc_collection_watch()
93
94

AUTHOR

96       MongoDB, Inc
97

99       2017-present, MongoDB, Inc
100
101
102
103
1041.25.1                           Nov 08, 2023           MONGOC_CLIENT_WATCH(3)
Impressum