Merge pull request #128 from gmiller-mdb/DOCSP-45192-read-data-page

DOCSP-45192-read-data-page

Author: gmiller-mdb

source/includes/usage-examples/read-code-examples.rb

@@ -0,0 +1,45 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+uri = '<connection string>'
+
+Mongo::Client.new(uri) do |client|
+
+  # start-find-one
+  document = collection.find(name: '<value>').first
+  puts document
+  # end-find-one
+
+  # start-find-many
+  results = collection.find(founded_year: '<value>')
+  # end-find-many
+
+  # start-count-collection
+  result = collection.count_documents
+  puts "Number of documents: #{result}"
+  # end-count-collection
+
+  # start-count-accurate
+  result = collection.count_documents('key': '<value>')
+  puts "value: #{result}"
+  # end-count-accurate
+
+  # start-count-estimate
+  result = collection.estimated_document_count
+  puts "Estimated number of documents: #{result}"
+  # end-count-estimate
+
+  # start-distinct
+  results = collection.distinct('field')
+  # end-distinct
+
+  # start-monitor-changes
+  stream = collection.watch
+  collection.insert_one(a: 1)
+  doc = stream.first
+  process(doc)
+  # end-monitor-changes

source/includes/usage-examples/sample-app-intro.rst

@@ -1,3 +1,5 @@
+.. _ruby-read-sample:
+
 Sample Application
 ~~~~~~~~~~~~~~~~~~
 

source/includes/usage-examples/sample-read-app.rb

@@ -0,0 +1,17 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+uri = '<connection string>'
+
+Mongo::Client.new(uri) do |client|
+  database = client.use('<database name>')
+  collection = database['<collection name>']
+
+ # Start example code here
+
+  # End example code here
+end

source/read.txt

@@ -29,3 +29,140 @@ Read Data from MongoDB
    Distinct Field Values </read/distinct>
    Count Documents </read/count>
    Cursors </read/cursors>
+
+Overview
+--------
+
+On this page, you can see copyable code examples that show common {+driver-short+} methods you
+can use to read data from MongoDB.
+
+.. tip::
+
+  To learn more about any of the methods shown on this page, see the link
+  provided in each section.
+
+To use an example from this page, copy the code example into the
+:ref:`ruby-read-sample` below or your own application.
+Be sure to replace all placeholders in the code examples, such as ``<connection string URI>``, with
+the relevant values for your MongoDB deployment.
+
+.. _read-sample:
+
+.. include:: /includes/usage-examples/sample-app-intro.rst
+
+.. literalinclude:: /includes/usage-examples/sample-read-app.rb
+   :language: ruby
+   :copyable:
+   :linenos:
+   :emphasize-lines: 14-16
+
+Find One
+--------
+
+The following example retrieves a document that matches the criteria specified by the
+given filter:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-find-one
+   :end-before: end-find-one
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``first`` method, see the :ref:`Retrieve Data <ruby-retrieve>` 
+guide.
+
+Find Multiple
+-------------
+
+The following example retrieves all documents that match the criteria specified by the
+given filter:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-find-many
+   :end-before: end-find-many
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``find`` method, see the :ref:`Retrieve Data <ruby-retrieve>` 
+guide.
+
+Count Documents in a Collection
+-------------------------------
+
+The following example returns the number of documents in the specified collection:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-count-collection
+   :end-before: end-count-collection
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``count_documents`` method, see the :ref:`Count Documents <ruby-count>`
+guide.
+
+Count Documents Returned from a Query
+-------------------------------------
+
+The following example returns the number of documents in the specified
+collection that match the query criteria:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-count-accurate
+   :end-before: end-count-accurate
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``countDocuments()`` method, see the :ref:`Count Documents <ruby-count>` 
+guide.
+
+Estimated Document Count
+------------------------
+
+The following example returns an approximate number of documents in the specified
+collection based on collection metadata:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-count-estimate
+   :end-before: end-count-estimate
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``estimated_document_count()`` method, see the :ref:`Count Documents <ruby-count>` 
+guide.
+
+Retrieve Distinct Values
+------------------------
+
+The following example returns all distinct values of the specified field name in a given
+collection:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-distinct
+   :end-before: end-distinct
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``distinct`` method, see the :ref:`<ruby-distinct>` guide.
+
+Monitor Data Changes
+--------------------
+
+The following example creates a change stream for a given collection and prints out
+subsequent change events in that collection:
+
+.. literalinclude:: /includes/usage-examples/read-code-examples.rb
+   :start-after: start-monitor-changes
+   :end-before: end-monitor-changes
+   :language: ruby
+   :copyable:
+   :dedent:
+
+To learn more about the ``watch()`` method, see the :ref:`Monitor Data Changes <ruby-change-streams>` guide.
+
+