1MONGOC_COLLECTION_WATCH(3)         libmongoc        MONGOC_COLLECTION_WATCH(3)
2
3
4

NAME

6       mongoc_collection_watch - mongoc_collection_watch()
7

SYNOPSIS

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

PARAMETERS

31       · coll: A  mongoc_collection_t  specifying  the  collection  which  the
32         change stream listens to.
33
34       · pipeline:  A  bson_t representing an aggregation pipeline appended to
35         the change stream. This may be an empty document.
36
37       · opts: A bson_t containing change stream options.
38
39       opts may be NULL or a BSON document with additional command options:
40
41       · batchSize: An int32 representing number of documents requested to  be
42         returned on each call to mongoc_change_stream_next
43
44       · resumeAfter:  A  Document  representing the logical starting point of
45         the change stream. The _id field   of  any  change  received  from  a
46         change  stream  can  be  used here. This option is mutually exclusive
47         with startAfter and startAtOperationTime.
48
49       · startAfter: A Document representing the logical starting point of the
50         change  stream.  Unlike  resumeAfter,  this  can resume notifications
51         after an "invalidate" event. The _id field  of  any  change  received
52         from  a  change  stream  can  be  used here.  This option is mutually
53         exclusive with resumeAfter and startAtOperationTime.
54
55       · startAtOperationTime: A Timestamp. The change  stream  only  provides
56         changes  that  occurred at or after the specified timestamp. Any com‐
57         mand run against the server will return an operation time that can be
58         used  here.  This  option  is mutually exclusive with resumeAfter and
59         startAfter.
60
61       · maxAwaitTimeMS: An int64 representing the maximum amount  of  time  a
62         call to mongoc_change_stream_next will block waiting for data
63
64       · fullDocument:  A  UTF-8  string. Set this option to "updateLookup" to
65         direct the change stream cursor to lookup  the  most  current  major‐
66         ity-committed  version of the document associated to an update change
67         stream event.
68

RETURNS

70       A newly allocated mongoc_change_stream_t which must be freed with  mon‐
71       goc_change_stream_destroy  when  no  longer  in  use. The returned mon‐
72       goc_change_stream_t is never NULL. If there is  an  error,  it  can  be
73       retrieved   with  mongoc_change_stream_error_document,  and  subsequent
74       calls to mongoc_change_stream_next will return false.
75

SEE ALSO

77       mongoc_client_watch
78
79       mongoc_database_watch
80

AUTHOR

82       MongoDB, Inc
83

85       2017-present, MongoDB, Inc
86
87
88
89
901.16.2                           Feb 25, 2020       MONGOC_COLLECTION_WATCH(3)
Impressum