Skip to content

Commit c414a00

Browse files
kennethdyerkennethdyer
authored
DOCSP-15108 $changeStream backport to v4.4 (#1570)
* DOCSP-15108 $changeStream Aggregation Stage Reference (#869) * DOCSP-15108 Initial stub * DOCSP-15108 Fixes toc and links for changeStream * DOCSP-15108 Typo * DOCSP-15108 parameters and return stubs * DOCSP-15108 Adds explanation and populates basic example * DOCSP-15108 Refactor content * DOCSP-15108 Option descriptions * DOCSP-15108 Return document description * DOCSP-15108 Updates YaML for changeStream listings * DOCSP-15108 Updates YaML for changeStream listings * DOCSP-15108 Updates reference * Reverts aggregation.txt * DOCSP-15108 Vale checks * DOCSP-15108 Vale checks * DOCSP-15108 Extra example * DOCSP-15108 Extra example * DOCSP-15108 Updates reference * DOCSP-15108 Fixes build error * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Updates per Dave feedback. * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Dave * DOCSP-15108 Fixes per Valentin Kavalenka * DOCSP-15108 Fixes per Valentin Kavalenka * DOCSP-15108 Fixes per Valentin Kavalenka * DOCSP-15108 Fixes per Valentin Kavalenka * DOCSP-15108 Fixes per Katya * DOCSP-15108 Fixes * DOCSP-15108 Fixes per Bernard * DOCSP-15108 Fixes per Bernard * DOCSP-15108 Fixes per Bernard Gorman * DOCSP-15108 Fixes per Bernard Gorman * DOCSP-15108 Fixes per Bernard Gorman * DOCSP-15108 Fixes per Bernard Gorman * DOCSP-15108 Removes 6.0 features * DOCSP-15108 Fixes build error
1 parent 6a34b56 commit c414a00

File tree

4 files changed

+142
-3
lines changed

4 files changed

+142
-3
lines changed

‎source/includes/extracts-agg-stages.yaml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ content: |
3131
to evenly distribute the documents into the specified number
3232
of buckets.
3333
34+
* - :pipeline:`$changeStream`
35+
36+
- Returns a :ref:`Change Stream <changeStreams>` cursor for the
37+
collection. This stage can only occur once in an aggregation
38+
pipeline and it must occur as the first stage.
39+
3440
* - :pipeline:`$collStats`
3541
3642
- Returns statistics regarding a collection or view.
@@ -243,6 +249,12 @@ content: |
243249
* - Stage
244250
- Description
245251
252+
* - :pipeline:`$changeStream`
253+
254+
- Returns a :ref:`Change Stream <changeStreams>` cursor for the
255+
collection. This stage can only occur once in an aggregation
256+
pipeline and it must occur as the first stage.
257+
246258
* - :pipeline:`$currentOp`
247259
248260
- Returns information on active and/or dormant operations for

‎source/reference/change-events.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
1+
.. _change-events:
22

33
=============
44
Change Events

‎source/reference/operator/aggregation-pipeline.txt

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ Stages
1717
``db.collection.aggregate()`` Stages
1818
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1919

20-
All except the :pipeline:`$out`, :pipeline:`$merge`, and :pipeline:`$geoNear` stages can
21-
appear multiple times in a pipeline.
20+
All except the :pipeline:`$out`, :pipeline:`$merge`, :pipeline:`$geoNear`,
21+
and :pipeline:`$changeStream` stages can appear multiple times in a pipeline.
2222

2323
.. include:: /includes/extracts/operators-toc-explanation.rst
2424

@@ -86,6 +86,11 @@ Alphabetical Listing of Stages
8686
boundaries are automatically determined in an attempt to evenly
8787
distribute the documents into the specified number of buckets.
8888

89+
* - :pipeline:`$changeStream`
90+
91+
- Returns a :ref:`Change Stream <changeStreams>` cursor for the
92+
collection or database. This stage can only occur once in an
93+
aggregation pipeline and it must occur as the first stage.
8994

9095
* - :pipeline:`$collStats`
9196

@@ -312,6 +317,7 @@ Alphabetical Listing of Stages
312317
/reference/operator/aggregation/addFields
313318
/reference/operator/aggregation/bucket
314319
/reference/operator/aggregation/bucketAuto
320+
/reference/operator/aggregation/changeStream
315321
/reference/operator/aggregation/collStats
316322
/reference/operator/aggregation/count
317323
/reference/operator/aggregation/currentOp

‎source/reference/operator/aggregation/changeStream.txt

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
===========================
2+
$changeStream (aggregation)
3+
===========================
4+
5+
.. contents:: On this page
6+
:local:
7+
:backlinks: none
8+
:depth: 1
9+
:class: singlecol
10+
11+
Definition
12+
----------
13+
14+
.. pipeline:: $changeStream
15+
16+
Returns a :ref:`Change Stream <changeStreams>` cursor on a collection, a database,
17+
or an entire cluster. Must be used as the first stage in an aggregation pipeline.
18+
19+
The :pipeline:`$changeStream` stage has the following syntax:
20+
21+
.. code-block:: text
22+
23+
{
24+
$changeStream: {
25+
allChangesForCluster: <boolean>,
26+
fullDocument: <string>,
27+
fullDocumentBeforeChange: <string>,
28+
resumeAfter: <int>
29+
startAfter: <document>
30+
startAtOperationTime: <timestamp>
31+
}
32+
}
33+
34+
.. list-table::
35+
:header-rows: 1
36+
37+
* - Parameter
38+
- Description
39+
40+
* - ``allChangesForCluster``
41+
- Optional: Sets whether the change stream should include all changes
42+
in the cluster. May only be opened on the ``admin`` database.
43+
44+
* - ``fullDocument``
45+
- Optional: Specifies whether change notifications include a copy of the
46+
full document when modified by ``update`` operations.
47+
48+
* ``default``: Change notifications do not include the full document
49+
for ``update`` operations.
50+
51+
* ``updateLookup``: Change notifications includes a copy of the
52+
document modified by the change. This document is the current
53+
majority-committed document or ``null`` if it no longer exists.
54+
55+
In the case of partial updates, the change notification also
56+
provides a description of the change.
57+
58+
* - ``fullDocumentBeforeChange``
59+
- Include the full document from before the change.
60+
This field accepts the following values:
61+
62+
* ``off``: Disables inclusion of the document from before the change.
63+
* ``whenAvailable``: Includes document from before the change.
64+
The query does not fail if the unmodified document is not available.
65+
* ``required``: Includes document from before the change. The query
66+
fails if the unmodified document is not available.
67+
68+
* - ``resumeAfter``
69+
- Specifies a resume token as the logical starting point for
70+
the change stream. Cannot be used with ``startAfter`` or
71+
``startAtOperationTime`` fields.
72+
73+
* - ``startAfter``
74+
- Specifies a resume token as the logical starting point for
75+
the change stream. Cannot be used with ``resumeAfter`` or
76+
``startAtOperationTime`` fields.
77+
78+
* - ``startAtOperationTime``
79+
- Specifies a time as the logical starting point for the change stream.
80+
Cannot be used with ``resumeAfter`` or ``startAfter`` fields.
81+
82+
83+
Examples
84+
--------
85+
86+
To create a change stream cursor using the aggregation stage, run
87+
the :dbcommand`aggregate` command
88+
89+
.. code-block:: javascript
90+
91+
var cur = db.names.aggregate( [
92+
{ $changeStream: {} }
93+
] )
94+
cur.next()
95+
96+
When the change stream detects a change, the ``next()`` method returns a change
97+
event notification. For example:
98+
99+
.. code-block:: json
100+
:copyable: false
101+
102+
{
103+
"_id": {
104+
_data: "8262E2EE54000000022B022C0100296E5A100448E5E3DD01364019AE8FE8C6859527E046645F6964006462E2EE54C8756C0D5CF6F0720004"
105+
},
106+
"operationType": "insert",
107+
"clusterTime": Timestamp({ t: 1659039316, i: 2 }),
108+
"fullDocument": {
109+
"_id": ObjectId("62e2ee54c8756c0d5cf6f072"),
110+
"name": "Walker Percy"
111+
},
112+
"ns": {
113+
"db": "test",
114+
"coll": "names"
115+
},
116+
"documentKey": { _id: ObjectId("62e2ee54c8756c0d5cf6f072") }
117+
}
118+
119+
For more information on change stream notifications, see :ref:`Change Events
120+
<change-events>`
121+

0 commit comments

Comments
 (0)