Skip to content

Commit d279d23

Browse files
kennethdyerkennethdyer
authored
DOCSP-15109 Resume Token Expansion (#2049)
* DOCSP-15109 Updates _id token * DOCSP-15109 Updates token sources * DOCSP-15109 Updates token sources * DOCSP-15109 Refactors resume token text * DOCSP-15109 Refactors resume token text * DOCSP-15109 Fixes code block * DOCSP-15109 Fixes code block * DOCSP-15109 Fixes per Dave * DOCSP-15109 Fixes per Dave * DOCSP-15109 Fixes per Dave * DOCSP-15109 Fixes per Dave * DOCSP-15109 Fixes build error * DOCSP-15109 Fixes build error * DOCSP-15109 Fixes build error * DOCSP-15109 Fixes per Valentin
1 parent ba6353d commit d279d23

File tree

2 files changed

+133
-16
lines changed

2 files changed

+133
-16
lines changed

‎source/changeStreams.txt‎

Lines changed: 127 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -745,8 +745,8 @@ Change streams are resumable by specifying a resume token to either
745745
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
746746

747747
You can resume a change stream after a specific event by passing a resume token
748-
to ``resumeAfter`` when opening the cursor. For the resume token, use the
749-
``_id`` value of the :ref:`change stream event document <change-stream-output>`.
748+
to ``resumeAfter`` when opening the cursor.
749+
750750
See :ref:`change-stream-resume-token` for more information on the resume token.
751751

752752
.. important::
@@ -943,9 +943,9 @@ You can start a new change stream after a specific event by passing a resume
943943
token to ``startAfter`` when opening the cursor. Unlike
944944
:ref:`resumeAfter <change-stream-resume-after>`, ``startAfter`` can
945945
resume notifications after an :ref:`invalidate event <change-event-invalidate>`
946-
by creating a new change stream. For the resume token, use the ``_id`` value of
947-
the :ref:`change stream event document <change-stream-output>`. See
948-
:ref:`change-stream-resume-token` for more information on the resume token.
946+
by creating a new change stream.
947+
948+
See :ref:`change-stream-resume-token` for more information on the resume token.
949949

950950
.. important::
951951

@@ -958,27 +958,139 @@ the :ref:`change stream event document <change-stream-output>`. See
958958
Resume Tokens
959959
~~~~~~~~~~~~~
960960

961-
The ``_id`` value of a :ref:`change stream event document
962-
<change-stream-output>` acts as the resume token:
961+
The resume token is available from multiple sources:
963962

964-
.. code-block:: none
963+
.. list-table::
964+
:header-rows: 1
965+
:stub-columns: 1
966+
:widths: 20 80
965967

966-
{
967-
"_data" : <BinData|hex string>
968-
}
968+
* - Source
969+
- Description
969970

970-
.. tip::
971+
* - :ref:`Change Events <change-event-resume-token>`
972+
- Each change event notification includes a resume token
973+
on the ``_id`` field.
971974

972-
.. include:: /includes/extracts/4.2-changes-change-stream-modification-error.rst
975+
* - :ref:`Aggregation <aggregate-resume-token>`
976+
- The :pipeline:`$changeStream` aggregation stage includes
977+
a resume token on the ``cursor.postBatchResumeToken`` field.
973978

974-
.. include:: /includes/extracts/changestream-resume-token-versions-4.2-greater.rst
979+
This field only appears when using the :dbcommand:`aggregate`
980+
command.
975981

976-
.. include:: /includes/extracts/changestream-resume-token-hex-change.rst
982+
* - :ref:`Get More <getMore-resume-token>`
983+
- The :dbcommand:`getMore` command includes a resume token on the
984+
``cursor.postBatchResumeToken`` field.
985+
986+
.. versionchanged:: 4.2
987+
988+
.. include:: /includes/extracts/4.2-changes-change-stream-modification-error.rst
977989

978990
.. tip::
979991

980992
.. include:: /includes/note-decode-resume-tokens.rst
981993

994+
.. _change-event-resume-token:
995+
996+
Resume Tokens from Change Events
997+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
998+
999+
Change event notifications include a resume token on the ``_id`` field:
1000+
1001+
.. code-block:: json
1002+
:copyable: false
1003+
:emphasize-lines: 2-4
1004+
1005+
1006+
{
1007+
"_id": {
1008+
"_data": "82635019A0000000012B042C0100296E5A1004AB1154ACACD849A48C61756D70D3B21F463C6F7065726174696F6E54797065003C696E736572740046646F63756D656E744B65790046645F69640064635019A078BE67426D7CF4D2000004"
1009+
},
1010+
"operationType": "insert",
1011+
"clusterTime": Timestamp({ "t": 1666193824, "i": 1 }),
1012+
"collectionUUID": new UUID("ab1154ac-acd8-49a4-8c61-756d70d3b21f"),
1013+
"wallTime": ISODate("2022-10-19T15:37:04.604Z"),
1014+
"fullDocument": {
1015+
"_id": ObjectId("635019a078be67426d7cf4d2"'),
1016+
"name": "Giovanni Verga"
1017+
},
1018+
"ns": {
1019+
"db": "test",
1020+
"coll": "names"
1021+
},
1022+
"documentKey": {
1023+
"_id": ObjectId("635019a078be67426d7cf4d2")
1024+
}
1025+
}
1026+
1027+
1028+
.. _aggregate-resume-token:
1029+
1030+
Resume Tokens from ``aggregate``
1031+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1032+
1033+
When using the :dbcommand:`aggregate` command, the :pipeline:`$changeStream`
1034+
aggregation stage includes a resume token on the
1035+
``cursor.postBatchResumeToken`` field:
1036+
1037+
.. code-block:: json
1038+
:copyable: false
1039+
:emphasize-lines: 4-6
1040+
1041+
{
1042+
"cursor": {
1043+
"firstBatch": [],
1044+
"postBatchResumeToken": {
1045+
"_data": "8263515EAC000000022B0429296E1404"
1046+
},
1047+
"id": Long("4309380460777152828"),
1048+
"ns": "test.names"
1049+
},
1050+
"ok": 1,
1051+
"$clusterTime": {
1052+
"clusterTime": Timestamp({ "t": 1666277036, "i": 1 }),
1053+
"signature": {
1054+
"hash": Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
1055+
"keyId": Long("0")
1056+
}
1057+
},
1058+
"operationTime": Timestamp({ "t": 1666277036, "i": 1 })
1059+
}
1060+
1061+
.. _getMore-resume-token:
1062+
1063+
Resume Tokens from ``getMore``
1064+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1065+
1066+
The :dbcommand:`getMore` command also includes a resume token on the
1067+
``cursor.postBatchResumeToken`` field:
1068+
1069+
.. code-block:: json
1070+
:copyable: false
1071+
:emphasize-lines: 4-6
1072+
1073+
{
1074+
"cursor": {
1075+
"nextBatch": [],
1076+
"postBatchResumeToken": {
1077+
"_data": "8263515979000000022B0429296E1404"
1078+
},
1079+
"id": Long("7049907285270685005"),
1080+
"ns": "test.names"
1081+
},
1082+
"ok": 1,
1083+
"$clusterTime": {
1084+
"clusterTime": Timestamp( { "t": 1666275705, "i": 1 } ),
1085+
"signature": {
1086+
"hash": Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0),
1087+
"keyId": Long("0")
1088+
}
1089+
},
1090+
"operationTime": Timestamp({ "t": 1666275705, "i": 1 })
1091+
}
1092+
1093+
9821094
Use Cases
9831095
---------
9841096

‎source/reference/command/getMore.txt‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,8 @@ For example, a document similar to the one below may be returned when
131131
"zipcode" : "220000"
132132
}
133133
],
134-
"partialResultsReturned" : true
134+
"partialResultsReturned" : true,
135+
"postBatchResumeToken": "< Resume Token >"
135136
},
136137
"ok" : 1,
137138
"operationTime" : Timestamp(1586385239, 2),
@@ -173,6 +174,10 @@ For example, a document similar to the one below may be returned when
173174
shards are unavailable include the ``partialResultsReturned``
174175
flag in the output.
175176

177+
The ``postBatchResumeToken`` field can be used with the
178+
:pipeline:`$changeStream` pipeline to start or resume
179+
a change stream from this point.
180+
176181
* - ``"ok"``
177182

178183
- Indicates whether the command has succeeded (``1``) or failed

0 commit comments

Comments
 (0)