diff --git a/snooty.toml b/snooty.toml index 18f84982..20234a84 100644 --- a/snooty.toml +++ b/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" diff --git a/source/index.txt b/source/index.txt index fbce2892..4658472c 100644 --- a/source/index.txt +++ b/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 diff --git a/source/read.txt b/source/read.txt index 88f0faf2..0cdf1f55 100644 --- a/source/read.txt +++ b/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 ------------------------ diff --git a/source/read/count.txt b/source/read/count.txt new file mode 100644 index 00000000..e0ffe21b --- /dev/null +++ b/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 `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` 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>`__ \ No newline at end of file