[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:
Depends
is depended on by DOCS-15065 Rewrite "Perform Long-Running Queries... Closed
Issue split
split to CSHARP-4055 Snapshot Query Examples for the Manual Backlog
split to RUST-1187 Snapshot Query Examples for the Manual Backlog
split to CDRIVER-4295 Snapshot Query Examples for the Manual Closed
split to CXX-2454 Snapshot Query Examples for the Manual Closed
split to GODRIVER-2310 Snapshot Query Examples for the Manual Closed
split to MOTOR-894 Snapshot Query Examples for the Manual Closed
split to PHPLIB-789 Snapshot Query Examples for the Manual Closed
split to PYTHON-3127 Snapshot Query Examples for the Manual Closed
split to RUBY-2909 Snapshot Query Examples for the Manual Closed
Related
related to SERVER-63887 SnapshotUnavailable error on sharded ... Closed
Driver Changes: Needed
Downstream Changes Summary:

NA

Driver Compliance:
Key Status/Resolution FixVersion
CDRIVER-4295 Fixed 1.24.0
CXX-2454 Done 3.8.0
CSHARP-4055 Backlog
GODRIVER-2310 Done
MOTOR-894 Fixed 3.0
PYTHON-3127 Fixed 4.1
PHPLIB-789 Fixed 1.13.0-beta1, 1.13.0
RUBY-2909 Fixed 2.18.0
RUST-1187 Backlog
SWIFT-1494 Won't Do

 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:

// Start Snapshot Query Example 1
 
client = MongoClient()
db = client.pets
with client.start_session(snapshot=True) as s:
   adoptablePetsCount = db.cats.aggregate(
       [ { "$match": { "adoptable": true } }, { "$count": "adoptableCatsCount" } ],
       session=s
   ).next()["adoptableCatsCount"]
 
   adoptablePetsCount += db.dogs.aggregate(
       [ { "$match": { "adoptable": True} }, { "$count": "adoptableDogsCount" } ],
       session=s
   ).next()["adoptableDogsCount"]
 
print(adoptablePetsCount)
 
// End Snapshot Query Example 1
 
// Start Snapshot Query Example 2
client = MongoClient()
db = client.retail
with client.start_session(snapshot=True) as s:
  total = db.sales.aggregate( [
     {
        $match: {
           $expr: {
              $gt: [
                 "$saleDate",
                 {
                    $dateSubtract: {
                       startDate: "$$NOW",
                       unit: "day",
                       amount: 1
                    }
                 }
              ]
            }
         }
     },
     { $count: "totalDailySales" }
  ], session=s
  ).next()["totalDailySales"]
 
// End Snapshot Query Example 2

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)

CDRIVER-4295

Implement snapshot query example number two for the manual.

Related: DRIVERS-2181
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/30fdc1c12dc7e4c801649eb2e5e4c245814f88da

Comment by Githook User [ 05/Dec/22 ]

Author:

{'name': 'Kyle Kloberdanz', 'email': 'kyle.kloberdanz@mongodb.com', 'username': 'kkloberdanz'}

Message: Cxx 2454 (#904)

CXX-2454 Create C++ driver snapshot query example for manual.

related: DRIVERS-2181
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/6d5188b88d6ee1a907613e457c65e9e62d8130df

Comment by Githook User [ 16/Nov/22 ]

Author:

{'name': 'Kyle Kloberdanz', 'email': 'kyle.kloberdanz@mongodb.com', 'username': 'kkloberdanz'}

Message: Add test_example_59 (#1143)

CDRIVER-4295

related: DRIVERS-2181

Implement a snapshot query example for the manual.

Co-authored-by: Kevin Albertson <kevin.albertson@10gen.com>
Branch: master
https://github.com/mongodb/mongo-c-driver/commit/42296dbb85422c85df276c281d3de22a2604051b

Comment by Jeremy Mikola [ 17/Mar/22 ]

Note to implementers: As noted in RUBY-2909, work-arounds may be required for SnapshotUnavailable(246) errors (see: replica sets and sharded clusters).

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:

db.sales.aggregate( 
  [ /* pipeline */ ],
  { readConcern: "snapshot" }
);

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

Generated at Thu Feb 08 08:24:56 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.