DOCSP-45197: Count documents

source/includes/read/count.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-db-coll
+  database = client.use('sample_training')
+  collection = database['companies']
+  # end-db-coll
+
+  # Counts all documents in the collection
+  # start-count-all
+  result = collection.count_documents
+  puts "Number of documents: #{result}"
+  # end-count-all
+
+  # Counts documents that have a "founded_year" value of 2010
+  # start-count-accurate
+  result = collection.count_documents(founded_year: 2010)
+  puts "Number of companies founded in 2010: #{result}"
+  # end-count-accurate
+
+  # Counts a maximum of 100 documents that have a "number_of_employees" value of 50
+  # start-modify-accurate
+  result = collection.count_documents({ number_of_employees: 50 }, limit: 100)
+  puts "Number of companies with 50 employees: #{result}"
+  # end-modify-accurate
+
+  # Estimates the number of documents in the collection
+  # start-count-estimate
+  result = collection.estimated_document_count
+  puts "Estimated number of documents: #{result}"
+  # end-count-estimate
+
+  # Estimates the number of documents in the collection and sets a time limit on the operation
+  # start-modify-estimate
+  result = collection.estimated_document_count(max_time_ms: 1000)
+  puts "Estimated number of documents: #{result}"
+  # end-modify-estimate
+end

source/read.txt

@@ -25,3 +25,4 @@ Read Data from MongoDB
    Retrieve Data </read/retrieve>
    Specify Documents to Return </read/specify-documents-to-return>
    Specify Fields to Return </read/project>
+   Count Documents </read/count>

source/read/count.txt

@@ -0,0 +1,255 @@
+.. _ruby-count:
+
+===============
+Count Documents
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: number, amount, estimation, code example
+
+Overview
+---------
+
+In this guide, you can learn how to use the {+driver-short+} to retrieve an accurate
+and estimated count of the number of documents in a collection. The following methods
+count documents in a collection:
+
+- ``count_documents``: Returns the exact number of documents that
+  match a query filter or that exist in a collection
+
+- ``estimated_document_count``: Returns the estimated number of documents
+  that exist in a collection
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``companies`` collection in the ``sample_training``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
+from your {+language+} application, create a ``Mongo::Client`` object that connects to
+an Atlas cluster and assign the following values to your ``database`` and ``collection``
+variables:
+
+.. literalinclude:: /includes/read/count.rb
+    :language: ruby
+    :dedent:
+    :start-after: start-db-coll
+    :end-before: end-db-coll
+
+To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+.. _ruby-accurate-count:
+
+Retrieve an Accurate Count
+--------------------------
+
+Use the ``count_documents`` method to count the number of documents
+in a collection. To count the number of documents that match specific search criteria,
+pass a query filter to the ``count_documents`` method.
+
+.. TODO: To learn more about specifying a query, see the :ref:`ruby-specify-query` guide.
+
+.. _ruby-count-all:
+
+Count All Documents
+~~~~~~~~~~~~~~~~~~~
+
+To return a count of all documents in the collection, call the
+``count_documents`` method without passing a query filter, as shown
+in the following example:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.rb
+      :start-after: start-count-all
+      :end-before: end-count-all
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of documents: 9500
+
+.. _ruby-count-specific:
+
+Count Specific Documents
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To return a count of documents that match specific search criteria, pass a query
+filter to the ``count_documents`` method.
+
+The following example counts the number of documents in which the value of the
+``founded_year`` field is ``2010``:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.rb
+      :start-after: start-count-accurate
+      :end-before: end-count-accurate
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of companies founded in 2010: 33
+
+Customize Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``count_documents`` method by
+passing a second parameter that specifies option values. The following table
+describes the options you can set to customize the count operation:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``collation``
+     - | The collation to use for the operation.
+       | **Type**: ``Hash``
+
+   * - ``hint``
+     - | The index to use for the operation.
+       | **Type**: ``Hash``
+
+   * - ``comment``
+     - | The comment to attach to the operation.
+       | **Type**: ``Object``
+
+   * - ``limit``
+     - | The maximum number of documents to count. This value must be a positive integer.
+       | **Type**: ``Integer``
+
+   * - ``max_time_ms``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``Integer``
+
+   * - ``skip``
+     - | The number of documents to skip before counting documents.
+       | **Type**: ``Integer``
+
+   * - ``read``
+     - | The read preference to use for the operation. To learn more, see
+         :manual:`Read Preference </core/read-preference/>` in the {+mdb-server+} manual.
+       | **Type**: ``Hash``
+
+The following example uses the ``count_documents`` method to count the number of
+documents in which the ``number_of_employees`` field has the value ``50`` and instructs the
+operation to count a maximum of ``100`` results:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.rb
+      :start-after: start-modify-accurate
+      :end-before: end-modify-accurate
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Number of companies with 50 employees: 100
+
+.. important::
+
+    When you pass an options parameter to the ``count_documents`` method,
+    you must enclose the query filter in brackets (``{}``).
+
+.. _ruby-estimated-count:
+
+Retrieve an Estimated Count
+---------------------------
+
+You can retrieve an estimate of the number of documents in a collection by calling
+the ``estimated_document_count`` method. The method estimates the amount
+of documents based on collection metadata, which might be faster than
+performing an accurate count.
+
+The following example estimates the number of documents in a collection:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.rb
+      :start-after: start-count-estimate
+      :end-before: end-count-estimate
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Estimated number of documents: 9500
+
+Customize Estimated Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can modify the behavior of the ``estimated_document_count`` method
+by passing a parameter that specifies option values. The
+following table describes the options you can set to customize
+the operation:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``comment``
+     - | The comment to attach to the operation.
+       | **Type**: ``Object``
+
+   * - ``max_time_ms``
+     - | The maximum amount of time in milliseconds that the operation can run.
+       | **Type**: ``Integer``
+
+   * - ``read``
+     - | The read concern to use for the operation. To learn more, see
+         :manual:`Read Concern </reference/read-concern/>` in the {+mdb-server+} manual.
+       | **Type**: ``Hash``
+
+The following example uses the ``estimated_document_count`` method to return an
+estimate of the number of documents in the collection and sets a timeout of
+``1000`` milliseconds on the operation:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/count.rb
+      :start-after: start-modify-estimate
+      :end-before: end-modify-estimate
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      Estimated number of documents: 9500
+
+API Documentation
+-----------------
+
+To learn more about any of the methods discussed in this
+guide, see the following API documentation:
+
+- `count_documents <{+api-root+}/Mongo/Collection.html#count_documents-instance_method>`__ 
+- `estimated_document_count <{+api-root+}/Mongo/Collection.html#estimated_document_count-instance_method>`__