diff --git a/source/includes/read/count.rb b/source/includes/read/count.rb new file mode 100644 index 00000000..5d347830 --- /dev/null +++ b/source/includes/read/count.rb @@ -0,0 +1,45 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +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 diff --git a/source/read.txt b/source/read.txt index 316d2bce..b1a428a9 100644 --- a/source/read.txt +++ b/source/read.txt @@ -25,3 +25,4 @@ Read Data from MongoDB Retrieve Data Specify Documents to Return Specify Fields to Return + Count Documents diff --git a/source/read/count.txt b/source/read/count.txt new file mode 100644 index 00000000..ae5b2141 --- /dev/null +++ b/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 `. 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 ` 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 ` 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 ` 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>`__ \ No newline at end of file