[CXX-1514] Aggregation, runCommand, and index management examples for Docs Created: 09/Feb/18  Updated: 28/Oct/23  Resolved: 04/Apr/18

Status: Closed
Project: C++ Driver
Component/s: Documentation
Affects Version/s: None
Fix Version/s: 3.3.0-rc0

Type: Task Priority: Minor - P4
Reporter: Rathi Gnanasekaran Assignee: Ryan Timmons
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by DRIVERS-448 Aggregation, runCommand, and index ma... Closed

 Description   

Here are the examples. They should be delimited with

// Start <delimiter>
[code]
// End <delimiter>

as has been done for the CRUD examples and such. I've attached the mongoexported datasets I used for the agg examples if one wants to make sure everything is working.

Delimiter Shell Snippet Notes
Aggregation Example 1

db.sales.aggregate( 
  [ 
    { $match : { "items.fruit":"banana" } },
    { $sort : { "date" : 1 } }
])

Simple agg example
Aggregation Example 2

db.sales.aggregate(
   [
      {
         $unwind: "$items"
      },
      { $match: {
         "items.fruit" : "banana",
      }},
      {
        $group : {
           _id : { day: { $dayOfWeek: "$date" } },
           count: { $sum: "$items.quantity" }
        }
      },
      {
        $project: {
          dayOfWeek: "$_id.day",
          numberSold: "$count",
          _id:0
        }
      },
      {
        $sort: { "numberSold": 1 }
      }
   ]
)

Aggregation - $match, $group, $project, $unwind, $sum, $sort, $dayOfWeek
Aggregation Example 3

db.sales.aggregate([
  {
     $unwind: "$items"
  },
  {
    $group : {
       _id : { day : { $dayOfWeek : "$date" } },
       items_sold : { $sum : "$items.quantity" },
       revenue: { $sum : { $multiply : [ "$items.quantity", "$items.price" ] } }
    }
  },
  {
    $project : {
      day : "$_id.day",
      revenue : 1,
      items_sold : 1,
      discount: {
        $cond : { if : { $lte : [ "$revenue", 250 ] }, then : 25, else : 0 }
      }
    }
  } 
 ])

Aggregation - $unwind, $group, $sum, $dayOfWeek, $multiply, $project, $cond.
If you're testing this one, change $revenue, 250 to a smaller number since the dataset I've attached doesn't have that many documents currently
Aggregation Example 4

db.air_alliances.aggregate( [
   {
      $lookup : {
        from : "air_airlines",
        let : { constituents: "$airlines" },
        pipeline : [ 
          {  
            $match : { $expr : { $in : [ "$name", "$$constituents" ] } } 
            } 
        ],
        as : "airlines"
      }
   },
   {
     $project : {
       "_id" : 0,
       "name" : 1,
       airlines : { 
          $filter : {
            input : "$airlines",
            as : "airline",
            cond : { $eq: ["$$airline.country", "Canada"] }
          }
       }
     }
   }
])

Aggregation - $lookup, $filter, $match
runCommand Example 1

db.runCommand({buildInfo: 1})

 
runCommand Example 2

db.runCommand({collStats:"restaurants"})

 
Index Example 1

db.records.createIndex( { score: 1 } )

Indexes - builds simple ascending index
Index Example 2

db.restaurants.createIndex(
   { cuisine: 1, name: 1 },
   { partialFilterExpression: { rating: { $gt: 5 } } }
)

Indexes - builds multikey index with partial filter expression


 Comments   
Comment by Githook User [ 04/Apr/18 ]

Author:

{'email': 'jesse@mongodb.com', 'name': 'A. Jesse Jiryu Davis', 'username': 'ajdavis'}

Message: CXX-1514 Fix unused variables in doc examples, 2
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/1970a4a3323cd9e8f4a162f89c2c095e8c299290

Comment by A. Jesse Jiryu Davis [ 28/Mar/18 ]

ryan.timmons could you look into this Travis failure?:

https://travis-ci.org/mongodb/mongo-cxx-driver/jobs/359414637

It logged a server error,

arguments to $lookup must be strings, let: { constituents: "$airlines" } is type object

Perhaps the original example was wrong, or the C++ translation of the example is wrong, or the server version we're testing against in Travis is too old for this use of $lookup.

If the last of these is true, we'll need a guard against running the example against an old server. See get_max_wire_version and get_server_version in client_helpers.hh.

Comment by Githook User [ 28/Mar/18 ]

Author:

{'email': 'jesse@mongodb.com', 'name': 'A. Jesse Jiryu Davis', 'username': 'ajdavis'}

Message: CXX-1514 Fix unused variables in doc examples
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/f6e90e82abbf71d75d97890aa36c051c7c047be1

Comment by Ryan Timmons [ 19/Mar/18 ]

CR links for posterity because I can't get rietveld<->jira to play nicely:
https://mongodbcr.appspot.com/189650001/
http://mongodbcr.appspot.com/191580002

I created CXX-1530 to investigate the "correct" way to format examples to be included on docs.

All of the examples are now present in master and are ready to be incorporated into docs. I don't know the workflow from this point - should this ticket be closed or re-assigned to track that work?

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'ryan.timmons@10gen.com', 'name': 'Ryan Timmons', 'username': 'rtimmons'}

Message: CXX-1514 Add aggregation, runCommand, and index examples
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/cce071ed75db9d83778a08129e8d05088ebad9e6

Comment by Githook User [ 19/Mar/18 ]

Author:

{'email': 'ryan.timmons@10gen.com', 'name': 'Ryan Timmons', 'username': 'rtimmons'}

Message: CXX-1514 Add first 2 aggregation docs examples
Branch: master
https://github.com/mongodb/mongo-cxx-driver/commit/f4b9ce6e0146989613b397ce910f853da3f37837

Comment by Ryan Timmons [ 15/Mar/18 ]

Per DRIVERS-448, we'll omit any seed data or expected results for now. I'm going to assert that the operations complete successfully and return no rows (or whatever the equivalent result is for these commands on an empty database).

Preliminary CR for the first two examples:
https://mongodbcr.appspot.com/189650001/

Comment by A. Jesse Jiryu Davis [ 13/Mar/18 ]

Ryan, there are some JSON files attached to DRIVERS-448, that's the data in the collections. What I can't figure out is whether the Docs Team shared with us the expected output when the example aggregations are applied to collections loaded with that data. Could you check with Allison Moore and Sue Kerschbaumer, and also check with them whether users will have access to the example input and expected output? And finally see if they're willing and able to make the airlines.json file smaller.

Comment by Ryan Timmons [ 12/Mar/18 ]

rathi.gnanasekaran i'm taking a look at this now.
You mentioned that you attached the mongoexported datasets but I don't see them anywhere - can you clarify?

Also curious if you had the "expected" output of these queries - would save me from possibly having the incorrect results.

(Forgive me if I'm being dense - new to the project so please lemme know if there's some background I may be missing.)

Comment by A. Jesse Jiryu Davis [ 08/Mar/18 ]

Ryan, look at CXX-1249 for inspiration. Here, we should start a separate file instead of adding more to the same documentation_examples.cpp file. The idea is to produce a new test file that is both a series of code snippets for use in the MongoDB Manual, as well as an actual series of tests that compile and run, to prove that the snippets we publish in the Manual are valid.

Submit a code review after writing the first few examples, don't do all the examples at once.

Generated at Wed Feb 07 22:02:54 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.