DOCSP-41137: Count Documents

snooty.toml

@@ -6,7 +6,9 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
                 "https://www.mongodb.com/docs/atlas/objects.inv"
               ]
 
-toc_landing_pages = []
+toc_landing_pages = [
+    "/read"
+]
 
 [constants]
 driver-long = "MongoDB Kotlin Sync Driver"

source/index.txt

@@ -1,10 +1,17 @@
+.. _kotlin-sync-index:
+
 ==========================
 {+driver-long+}
 ==========================
 
+.. facet::
+   :name: programming_language
+   :values: kotlin
+
+.. meta::
+   :keywords: home
+
 .. toctree::
-   :titlesonly:
-   :maxdepth: 1
 
    /read
    /faq

source/read.txt

@@ -18,18 +18,11 @@ Read Data from MongoDB
    :description: Learn how to use the Kotlin Sync Driver to read data from MongoDB.
    :keywords: usage examples, query, find, code example
 
-.. .. toctree::
-..    :titlesonly:
-..    :maxdepth: 1
-
-   .. /read/specify-a-query
-   .. /read/retrieve
-   .. /read/project
-   .. /read/specify-documents-to-return
-   .. /read/count
-   .. /read/distinct
-   .. /read/cursors
-   .. /read/change-streams
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   /read/count
 
 Overview
 --------
@@ -88,8 +81,8 @@ The following example returns the number of documents in the specified collectio
    :copyable:
    :dedent:
 
-.. TODO: To learn more about the ``count_documents()`` method, see the
-.. :ref:`kotlin-sync-accurate-count` guide.
+To learn more about the ``countDocuments()`` method, see the
+:ref:`kotlin-sync-accurate-count` section of the Count Documents guide.
 
 Count Documents Returned from a Query
 -------------------------------------
@@ -104,8 +97,8 @@ the given filter:
    :copyable:
    :dedent:
 
-.. TODO: To learn more about the ``countDocuments()`` method, see the
-.. :ref:`kotlin-sync-accurate-count` guide.
+To learn more about the ``countDocuments()`` method, see the
+:ref:`kotlin-sync-accurate-count` section of the Count Documents guide.
 
 Estimated Document Count
 ------------------------
@@ -120,8 +113,8 @@ collection based on collection metadata:
    :copyable:
    :dedent:
 
-.. TODO: To learn more about the ``estimatedDocumentCount()`` method, see the
-.. :ref:`kotlin-sync-estimated-count` guide.
+To learn more about the ``estimatedDocumentCount()`` method, see the
+:ref:`kotlin-sync-estimated-count` section of the Count Documents guide.
 
 Retrieve Distinct Values
 ------------------------

source/read/count.txt

@@ -0,0 +1,190 @@
+.. _kotlin-sync-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 retrieve accurate and estimated counts of the
+number of documents in a collection.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``movies`` collection in the ``sample_mflix``
+database from the :atlas:`Atlas sample datasets </sample-data>`. 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.
+
+.. _kotlin-sync-accurate-count:
+
+Retrieve an Accurate Count
+--------------------------
+
+Use the ``countDocuments()`` method to count the number of documents that are in a
+collection. To count the number of documents that match specified search
+critera, pass a query filter to the ``countDocuments()`` method.
+
+.. TODO: To learn more about specifying a query, see :ref:`kotlin-sync-specify-query`.
+
+Count All Documents
+~~~~~~~~~~~~~~~~~~~
+
+To return a count of all documents in the collection, call the ``countDocuments()`` method
+with no arguments, as shown in the following example:
+
+.. io-code-block::
+
+   .. input::
+      :language: kotlin
+
+      print(collection.countDocuments())
+
+   .. output::
+       :visible: false
+
+       21349
+
+Count Specific Documents
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To return a count of documents that match specific search criteria, specify your query
+in the ``countDocuments()`` method. The following example prints a count of all documents
+in the ``movies`` collection that have a ``year`` field value equal to ``1930``:
+
+.. io-code-block::
+
+   .. input::
+       :language: kotlin
+
+       print(collection.countDocuments(eq("year", "1930")))
+
+   .. output::
+      :visible: false
+
+      10
+
+Customize Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``countDocuments()`` method accepts optional parameters in the form of a
+``CountOptions`` object, which represents options you can use to configure the count
+operation. You can set these options by instantiating a new ``CountOptions`` object,
+setting the object's fields using the corresponding methods, and passing it to the
+``countDocuments()`` method. If you don't specify any options, the driver does not
+customize the count operation.
+
+The following table describes the options you can set to customize ``countDocuments()``:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``comment``
+     - | A comment to attach to the operation.
+
+   * - ``skip``
+     - | The number of documents to skip before returning results.
+
+   * - ``limit``
+     - | The maximum number of documents to count. Must be a positive integer.
+
+   * - ``maxTime``
+     - | The maximum amount of time to allow the operation to run, in milliseconds.
+
+   * - ``collation``
+     - | The collation to use for the operation.
+
+   * - ``hint``
+     - | Gets or sets the index to scan for documents.
+
+The following example uses a ``CountOptions`` object to add a comment to the
+``countDocuments()`` operation:
+
+.. code-block:: kotlin
+
+   val options = CountOptions().comment("Retrieving count")
+   collection.countDocuments(options)
+
+.. _kotlin-sync-estimated-count:
+
+Retrieve an Estimated Count
+---------------------------
+
+Use the ``estimatedDocumentCount()`` method to retrieve an estimate of the number of
+documents in a collection. The method estimates the amount of documents based on
+collection metadata, which can be faster than performing an accurate count.
+
+The following example prints the estimated number of documents in a collection:
+
+.. io-code-block::
+
+   .. input::
+      :language: kotlin
+
+      print(collection.estimatedDocumentCount())
+
+   .. output::
+       :visible: false
+
+       21349
+
+Customize Estimated Count Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``estimatedDocumentCount()`` method accepts optional parameters in the form of an
+``EstimatedDocumentCountOptions`` object, which represents options you can use to configure
+the count operation. You can set these options by instantiating a new
+``EstimatedDocumentCountOptions`` object, setting the object's fields using the
+corresponding methods, and passing it to the ``estimatedDocumentCount()`` method.
+If you don't specify any options, the driver does not customize the count operation.
+
+The following table describes the options you can set to customize ``estimatedDocumentCount()``:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Option
+     - Description
+
+   * - ``comment``
+     - | A comment to attach to the operation.
+
+   * - ``maxTime``
+     - | The maximum amount of time to allow the operation to run, in milliseconds.
+
+The following example uses an ``EstimatedDocumentCountOptions`` object to add a comment to
+the ``estimatedDocumentCount()`` operation:
+
+.. code-block:: kotlin
+
+   val options = EstimatedDocumentCountOptions().comment("Retrieving count")
+   collection.estimatedDocumentCount(options)
+
+API Documentation
+-----------------
+
+To learn more about any of the methods or types discussed in this
+guide, see the following API documentation:
+
+- `countDocuments() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__
+- `estimatedDocumentCount() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__