Skip to content

Commit af08e1e

Browse files
kennethdyerkennethdyer
authored
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
1 parent 756c484 commit af08e1e

File tree

3 files changed

+166
-2
lines changed

3 files changed

+166
-2
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.
@@ -280,6 +286,12 @@ content: |
280286
* - Stage
281287
- Description
282288
289+
* - :pipeline:`$changeStream`
290+
291+
- Returns a :ref:`Change Stream <changeStreams>` cursor for the
292+
collection. This stage can only occur once in an aggregation
293+
pipeline and it must occur as the first stage.
294+
283295
* - :pipeline:`$currentOp`
284296
285297
- Returns information on active and/or dormant operations for

‎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

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

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

8994
* - :pipeline:`$collStats`
9095

@@ -352,6 +357,7 @@ Alphabetical Listing of Stages
352357
/reference/operator/aggregation/addFields
353358
/reference/operator/aggregation/bucket
354359
/reference/operator/aggregation/bucketAuto
360+
/reference/operator/aggregation/changeStream
355361
/reference/operator/aggregation/collStats
356362
/reference/operator/aggregation/count
357363
/reference/operator/aggregation/currentOp

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

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
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+
showExpandedEvents: <boolean>,
30+
startAfter: <document>
31+
startAtOperationTime: <timestamp>
32+
}
33+
}
34+
35+
.. list-table::
36+
:header-rows: 1
37+
38+
* - Parameter
39+
- Description
40+
41+
* - ``allChangesForCluster``
42+
- Optional: Sets whether the change stream should include all changes
43+
in the cluster. May only be opened on the ``admin`` database.
44+
45+
* - ``fullDocument``
46+
- Optional: Specifies whether change notifications include a copy of the
47+
full document when modified by ``update`` operations.
48+
49+
* ``default``: Change notifications do not include the full document
50+
for ``update`` operations.
51+
52+
* ``required``: Change notifications includes a copy of the modified
53+
document as it appeared immediately after the change. If the
54+
document cannot be found, the change stream throws an error.
55+
56+
To use this option, you must first use the :dbcommand:`collMod`
57+
command to enable the ``changeStreamPreAndPostImages`` option.
58+
59+
.. versionadded:: 6.0
60+
* ``updateLookup``: Change notifications includes a copy of the
61+
document modified by the change. This document is the current
62+
majority-committed document or ``null`` if it no longer exists.
63+
64+
* ``whenAvailable``: Change notification includes a copy of the
65+
modified document as it appeared immediately after the change or
66+
``null`` if the document is unavailable.
67+
68+
To use this option, you must first use the :dbcommand:`collMod`
69+
command to enable the ``changeStreamPreAndPostImages`` option.
70+
71+
.. versionadded:: 6.0
72+
73+
In the case of partial updates, the change notification also
74+
provides a description of the change.
75+
76+
* - ``fullDocumentBeforeChange``
77+
- Include the full document from before the change.
78+
This field accepts the following values:
79+
80+
* ``off``: Disables inclusion of the document from before the change.
81+
* ``whenAvailable``: Includes document from before the change.
82+
The query does not fail if the unmodified document is not available.
83+
* ``required``: Includes document from before the change. The query
84+
fails if the unmodified document is not available.
85+
86+
* - ``resumeAfter``
87+
- Specifies a resume token as the logical starting point for
88+
the change stream. Cannot be used with ``startAfter`` or
89+
``startAtOperationTime`` fields.
90+
91+
* - ``showExpandedEvents``
92+
- Specifies whether to include additional change events, such as
93+
such as DDL and index operations.
94+
95+
.. versionadded:: 6.0
96+
97+
* - ``startAfter``
98+
- Specifies a resume token as the logical starting point for
99+
the change stream. Cannot be used with ``resumeAfter`` or
100+
``startAtOperationTime`` fields.
101+
102+
* - ``startAtOperationTime``
103+
- Specifies a time as the logical starting point for the change stream.
104+
Cannot be used with ``resumeAfter`` or ``startAfter`` fields.
105+
106+
107+
Examples
108+
--------
109+
110+
To create a change stream cursor using the aggregation stage, run
111+
the :dbcommand`aggregate` command
112+
113+
.. code-block:: javascript
114+
115+
var cur = db.names.aggregate( [
116+
{ $changeStream: {} }
117+
] )
118+
cur.next()
119+
120+
When the change stream detects a change, the ``next()`` method returns a change
121+
event notification. For example:
122+
123+
.. code-block:: json
124+
:copyable: false
125+
126+
{
127+
"_id": {
128+
_data: "8262E2EE54000000022B022C0100296E5A100448E5E3DD01364019AE8FE8C6859527E046645F6964006462E2EE54C8756C0D5CF6F0720004"
129+
},
130+
"operationType": "insert",
131+
"clusterTime": Timestamp({ t: 1659039316, i: 2 }),
132+
"wallTime": ISODate("2022-07-28T20:15:16.148Z"),
133+
"fullDocument": {
134+
"_id": ObjectId("62e2ee54c8756c0d5cf6f072"),
135+
"name": "Walker Percy"
136+
},
137+
"ns": {
138+
"db": "test",
139+
"coll": "names"
140+
},
141+
"documentKey": { _id: ObjectId("62e2ee54c8756c0d5cf6f072") }
142+
}
143+
144+
For more information on change stream notifications, see :ref:`Change Events
145+
<change-events>`
146+

0 commit comments

Comments
 (0)