[DRIVERS-2181] Snapshot Query Examples for the Manual Created: 31/Jan/22 Updated: 06/Dec/22 |
|
| Status: | Implementing |
| Project: | Drivers |
| Component/s: | Docs Examples |
| Fix Version/s: | None |
| Type: | Task | Priority: | Major - P3 |
| Reporter: | Jeffrey Allen | Assignee: | Unassigned |
| Resolution: | Unresolved | Votes: | 0 |
| Labels: | None | ||
| Remaining Estimate: | Not Specified | ||
| Time Spent: | Not Specified | ||
| Original Estimate: | Not Specified | ||
| Issue Links: |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Driver Changes: | Needed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Downstream Changes Summary: | NA |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Driver Compliance: |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Description |
|
The server documentation team would like to add driver examples for snapshot queries. I've mocked up the examples we want to use in Python. I've also included the delineation we'd like to use:
The examples will appear on this page: https://docs-mongodbcom-staging.corp.mongodb.com/docs/docsworker-xlarge/DOCS-15065/tutorial/long-running-queries/ Let me know if you need any more information. Thank you for your help! |
| Comments |
| Comment by Githook User [ 06/Dec/22 ] | ||||
|
Author: {'name': 'Kyle Kloberdanz', 'email': 'kyle.kloberdanz@mongodb.com', 'username': 'kkloberdanz'}Message: Kyle/snapshot example 2 (#1156) Implement snapshot query example number two for the manual. Related: DRIVERS-2181 | ||||
| Comment by Githook User [ 05/Dec/22 ] | ||||
|
Author: {'name': 'Kyle Kloberdanz', 'email': 'kyle.kloberdanz@mongodb.com', 'username': 'kkloberdanz'}Message: Cxx 2454 (#904)
related: DRIVERS-2181 | ||||
| Comment by Githook User [ 16/Nov/22 ] | ||||
|
Author: {'name': 'Kyle Kloberdanz', 'email': 'kyle.kloberdanz@mongodb.com', 'username': 'kkloberdanz'}Message: Add test_example_59 (#1143) related: DRIVERS-2181 Implement a snapshot query example for the manual. Co-authored-by: Kevin Albertson <kevin.albertson@10gen.com> | ||||
| Comment by Jeremy Mikola [ 17/Mar/22 ] | ||||
|
Note to implementers: As noted in | ||||
| Comment by Jeremy Mikola [ 08/Mar/22 ] | ||||
|
Ah, thanks for clarifying. That wasn't clear from any of the driver specs, but I suppose it is addressed in the server manual. In that case, it sounds like there's no issue with the current shell example that passes an explicit readConcern option with level: "snapshot". For a single operation, we don't need to collect the cluster time. jeffrey.allen's Python example in the issue description suggests using a snapshot-enabled session for both examples, so I'll stick with that for the PHP language example (and expect other drivers will as well). I suppose if we do want the shell examples on that page to be consistent (with one another and any driver examples), the docs team can switch to using a snapshot-enabled session for the second example as well. I'll leave that for the docs team to discuss outside of this ticket, though. | ||||
| Comment by A. Jesse Jiryu Davis [ 08/Mar/22 ] | ||||
|
Oh! Yes it does. A single read operation can see inconsistent results if other processes are writing as the read iterates the cursor. An aggregation that touches many docs benefits from snapshot isolation. | ||||
| Comment by Jeremy Mikola [ 08/Mar/22 ] | ||||
|
Independent of whether we're demonstrating mongo, mongosh, or a particular driver, I think there is a more basic question at the end of my last comment: does it make sense to show an example consisting of only a single read operation? | ||||
| Comment by A. Jesse Jiryu Davis [ 08/Mar/22 ] | ||||
|
Yeah, let's ask the mongosh team if/how the shell supports snapshot reads. I believe we never implemented it for the old mongo shell. If mongosh doesn't have a convenient, driver-like API for snapshot reads let's just say it isn't supported. It's not helpful to describe atClusterTime or try to teach users to construct atClusterTime manually. | ||||
| Comment by Jeremy Mikola [ 08/Mar/22 ] | ||||
|
jeffrey.allen: Let me know if this requires a separate DOCSP ticket, but I had some feedback on the staging link you shared in the issue description above. The second example includes the following shell code:
I'm not familiar with how the shell has implemented snapshot reads, but my understanding is that the feature requires the readConcern command option to specify both a level of "snapshot" and an atClusterTime value (see: Snapshot Read Commands in the drivers' Snapshot Sessions spec). Even though drivers added "snapshot" as an enum value or constant on their ReadConcern classes, I don't believe users will be expected to use this directly. The feature seems to be used entirely through a client session with snapshot enabled. Without atClusterTime specified, Snapshot Read Concern suggests that providing a level of "snapshot" alone will have no other effect than instructing the server to return a cluster time in the response (for use with a future command's readConcern.atClusterTime field). Perhaps there is a more general issue with the second example, since it only include a single operation. This is in contrast to the first example, which runs two aggregate operations with the same client session, which ensures the second operation will re-use the cluster time returned by the first. | ||||
| Comment by Alexander Golin (Inactive) [ 09/Feb/22 ] | ||||
|
Thanks so much jeffrey.allen! We'll be doing another round of DRIVERS triage on Monday, will keep you posted if we have any questions! | ||||
| Comment by Jeffrey Allen [ 09/Feb/22 ] | ||||
|
Hey alexander.golin, I've updated the description of the ticket with an additional example. The docs where the examples will live have been reviewed by the appropriate parties and we're happy with these examples. I'm unblocking this ticket and moving it back into Needs Triage. Let me know if you need anything else from me. Thank you |