From 61cd203e329a5e62ce341bfb3b7cd8c1cd029f5b Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:18:00 -0400 Subject: [PATCH 01/12] DOCSP-41137: Count Documents --- source/read.txt | 20 +++--- source/read/count.txt | 138 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 148 insertions(+), 10 deletions(-) create mode 100644 source/read/count.txt diff --git a/source/read.txt b/source/read.txt index 88f0faf2..7290d11c 100644 --- a/source/read.txt +++ b/source/read.txt @@ -18,15 +18,15 @@ 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 +.. toctree:: + :titlesonly: + :maxdepth: 1 .. /read/specify-a-query .. /read/retrieve .. /read/project .. /read/specify-documents-to-return - .. /read/count + /read/count .. /read/distinct .. /read/cursors .. /read/change-streams @@ -88,8 +88,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` guide. Count Documents Returned from a Query ------------------------------------- @@ -104,8 +104,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` guide. Estimated Document Count ------------------------ @@ -120,8 +120,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` guide. Retrieve Distinct Values ------------------------ diff --git a/source/read/count.txt b/source/read/count.txt new file mode 100644 index 00000000..fe328207 --- /dev/null +++ b/source/read/count.txt @@ -0,0 +1,138 @@ +.. _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. + +.. _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. + +.. 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: + +.. code-block:: kotlin + + collection.countDocuments() + +Count Specific Documents +~~~~~~~~~~~~~~~~~~~~~~~~ + +To return a count of documents that match specific search criteria, specify your query +in the ``countDocuments()`` method, as shown in the following example: + +.. code-block:: kotlin + + collection.countDocuments(eq("author", "Leslie")) + +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. 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 + + * - Property + - 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. + + * - ``collection`` + - | An instance of ``Collation``. + + * - ``hint`` + - | Gets or sets the index to scan for documents. + +.. _kotlin-sync-estimated-count: + +Retrieve an Estimated Count +--------------------------- + +You can get an estimate of the number of documents in a collection by calling +the ``estimatedDocumentCount()`` method. The method estimates the amount of +documents based on collection metadata, which can be faster than performing an +accurate count. + +The following example estimates the number of documents in a collection: + +.. code-block:: kotlin + + collection.estimatedDocumentCount() + +Customize Estimated Count Behavior +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``estimatedDocumentDount()`` method accepts optional parameters in the form of an +``EstimatedDocumentCountOptions`` object, which represents options you can use to configure +the count operation. 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 + + * - Property + - Description + + * - ``comment`` + - | A comment to attach to the operation. + + * - ``maxTime`` + - | The maximum amount of time to allow the operation to run, in milliseconds. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `countDocuments() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__ +- `estimatedDocumentCount() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__ \ No newline at end of file From a64a6d593d529a7dfd3a279a81e3077cac634a79 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:20:39 -0400 Subject: [PATCH 02/12] Link fix --- source/read.txt | 7 ------- 1 file changed, 7 deletions(-) diff --git a/source/read.txt b/source/read.txt index 7290d11c..f3da27bd 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,14 +22,7 @@ Read Data from MongoDB :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 Overview -------- From d88905e615017fa249b8edbbd2ea7de6af73dddd Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:26:24 -0400 Subject: [PATCH 03/12] Fix --- source/index.txt | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/source/index.txt b/source/index.txt index fbce2892..cff4b8e2 100644 --- a/source/index.txt +++ b/source/index.txt @@ -2,9 +2,14 @@ {+driver-long+} ========================== +.. facet:: + :name: programming_language + :values: kotlin + +.. meta:: + :keywords: home + .. toctree:: - :titlesonly: - :maxdepth: 1 /read /faq From 9ea14c2a6f650ea6728c3c8fb2fd6bc3fe75033d Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:27:00 -0400 Subject: [PATCH 04/12] Fix --- source/read.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/read.txt b/source/read.txt index f3da27bd..7290d11c 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,7 +22,14 @@ Read Data from MongoDB :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 Overview -------- From aaf531c90cee4129ba65eaa16f6d135d4dc6206a Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:28:32 -0400 Subject: [PATCH 05/12] Attempted fix --- source/read.txt | 7 ------- 1 file changed, 7 deletions(-) diff --git a/source/read.txt b/source/read.txt index 7290d11c..f3da27bd 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,14 +22,7 @@ Read Data from MongoDB :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 Overview -------- From 8f9fedab1252a8ded1dc136b15ecbcaf52bba6fd Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:33:05 -0400 Subject: [PATCH 06/12] Test fix --- source/index.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/index.txt b/source/index.txt index cff4b8e2..da8d60f3 100644 --- a/source/index.txt +++ b/source/index.txt @@ -1,4 +1,5 @@ -========================== +.. _kotlin-sync-index: + {+driver-long+} ========================== From e7ec682cb82bcd60d81595745b56cc6823d53194 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:45:02 -0400 Subject: [PATCH 07/12] Actual fix --- snooty.toml | 4 +++- source/index.txt | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) 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 da8d60f3..4658472c 100644 --- a/source/index.txt +++ b/source/index.txt @@ -1,5 +1,6 @@ .. _kotlin-sync-index: +========================== {+driver-long+} ========================== From 238134a9c47d1cbfadc16322362d54a44638743d Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 9 Jul 2024 13:50:15 -0400 Subject: [PATCH 08/12] Link fix --- source/read/count.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read/count.txt b/source/read/count.txt index fe328207..47b161a0 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -134,5 +134,5 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -- `countDocuments() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__ -- `estimatedDocumentCount() <{+api+}/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__ \ No newline at end of file +- `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 From ecc88ddd1e1cf325d3ad85ce6a05d9ccc16100ed Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 10 Jul 2024 09:28:28 -0400 Subject: [PATCH 09/12] Address feedback --- source/read.txt | 6 ++-- source/read/count.txt | 69 ++++++++++++++++++++++++++++++++----------- 2 files changed, 55 insertions(+), 20 deletions(-) diff --git a/source/read.txt b/source/read.txt index f3da27bd..0cdf1f55 100644 --- a/source/read.txt +++ b/source/read.txt @@ -82,7 +82,7 @@ The following example returns the number of documents in the specified collectio :dedent: To learn more about the ``countDocuments()`` method, see the -:ref:`kotlin-sync-accurate-count` guide. +:ref:`kotlin-sync-accurate-count` section of the Count Documents guide. Count Documents Returned from a Query ------------------------------------- @@ -98,7 +98,7 @@ the given filter: :dedent: To learn more about the ``countDocuments()`` method, see the -:ref:`kotlin-sync-accurate-count` guide. +:ref:`kotlin-sync-accurate-count` section of the Count Documents guide. Estimated Document Count ------------------------ @@ -114,7 +114,7 @@ collection based on collection metadata: :dedent: To learn more about the ``estimatedDocumentCount()`` method, see the -:ref:`kotlin-sync-estimated-count` guide. +: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 index 47b161a0..838f8a4d 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -23,6 +23,14 @@ 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 @@ -32,7 +40,7 @@ Use the ``countDocuments()`` method to count the number of documents that are in collection. To count the number of documents that match specified search critera, pass a query filter to the ``countDocuments()`` method. -.. To learn more about specifying a query, see :ref:`kotlin-sync-specify-query`. +.. TODO: To learn more about specifying a query, see :ref:`kotlin-sync-specify-query`. Count All Documents ~~~~~~~~~~~~~~~~~~~ @@ -48,19 +56,30 @@ Count Specific Documents ~~~~~~~~~~~~~~~~~~~~~~~~ To return a count of documents that match specific search criteria, specify your query -in the ``countDocuments()`` method, as shown in the following example: +in the ``countDocuments()`` method. The following example prints a count of all documents +in the ``movies`` collection with a ``year`` field value equal to ``1930``: -.. code-block:: kotlin +.. io-code-block:: - collection.countDocuments(eq("author", "Leslie")) + .. 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. If you don't specify any options, the driver does not customize the count -operation. +operation. You can set these options by instantiating a new ``CountOptions`` object, +setting the object's fields using the corresponding setter 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()``: @@ -68,7 +87,7 @@ The following table describes the options you can set to customize ``countDocume :widths: 30 70 :header-rows: 1 - * - Property + * - Option - Description * - ``comment`` @@ -83,21 +102,27 @@ The following table describes the options you can set to customize ``countDocume * - ``maxTime`` - | The maximum amount of time to allow the operation to run, in milliseconds. - * - ``collection`` - - | An instance of ``Collation``. + * - ``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 --------------------------- -You can get an estimate of the number of documents in a collection by calling -the ``estimatedDocumentCount()`` method. The method estimates the amount of -documents based on collection metadata, which can be faster than performing an -accurate 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 estimates the number of documents in a collection: @@ -108,10 +133,12 @@ The following example estimates the number of documents in a collection: Customize Estimated Count Behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``estimatedDocumentDount()`` method accepts optional parameters in the form of an +The ``estimatedDocumentCount()`` method accepts optional parameters in the form of an ``EstimatedDocumentCountOptions`` object, which represents options you can use to configure -the count operation. If you don't specify any options, the driver does not customize the -count operation. +the count operation. You can set these options by instantiating a new +``EstimatedDocumentCountOptions`` object, setting the object's fields using the +corresponding setter 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()``: @@ -119,7 +146,7 @@ The following table describes the options you can set to customize ``estimatedDo :widths: 30 70 :header-rows: 1 - * - Property + * - Option - Description * - ``comment`` @@ -128,6 +155,14 @@ The following table describes the options you can set to customize ``estimatedDo * - ``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") + print(collection.estimatedDocumentCount(options)) + API Documentation ----------------- From de04ef9feb93ca75fa090029be1ad6f72a826ab1 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 10 Jul 2024 09:35:36 -0400 Subject: [PATCH 10/12] Fix --- source/read/count.txt | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/source/read/count.txt b/source/read/count.txt index 838f8a4d..daccef2f 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -48,9 +48,17 @@ 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: -.. code-block:: kotlin +.. io-code-block:: + + .. input:: + :language: kotlin + + print(collection.countDocuments()) - collection.countDocuments() + .. output:: + :visible: false + + 21349 Count Specific Documents ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,12 +68,12 @@ in the ``countDocuments()`` method. The following example prints a count of all in the ``movies`` collection with a ``year`` field value equal to ``1930``: .. io-code-block:: - + .. input:: :language: kotlin print(collection.countDocuments(eq("year", "1930"))) - + .. output:: :visible: false @@ -112,6 +120,7 @@ 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) @@ -124,11 +133,19 @@ Use the ``estimatedDocumentCount()`` method to retrieve an estimate of the numbe 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 estimates the number of documents in a collection: +The following example prints the estimated number of documents in a collection: -.. code-block:: kotlin +.. io-code-block:: + + .. input:: + :language: kotlin + + print(collection.estimatedDocumentCount()) + + .. output:: + :visible: false - collection.estimatedDocumentCount() + 21349 Customize Estimated Count Behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -161,7 +178,7 @@ the ``estimatedDocumentCount()`` operation: .. code-block:: kotlin val options = EstimatedDocumentCountOptions().comment("Retrieving count") - print(collection.estimatedDocumentCount(options)) + collection.estimatedDocumentCount(options) API Documentation ----------------- From 3969be94d788110788bac34c466318d9f724097e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 10 Jul 2024 09:38:11 -0400 Subject: [PATCH 11/12] Fix --- source/read/count.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/read/count.txt b/source/read/count.txt index daccef2f..50d85a0a 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -85,7 +85,7 @@ 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 setter methods, and passing it to the +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. @@ -154,7 +154,7 @@ The ``estimatedDocumentCount()`` method accepts optional parameters in the form ``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 setter methods, and passing it to the ``estimatedDocumentCount()`` method. +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()``: From e0e807a5c9883e5b3869748c6f5163f9e5b0cd6c Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 10 Jul 2024 10:32:10 -0400 Subject: [PATCH 12/12] Feedback --- source/read/count.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/read/count.txt b/source/read/count.txt index 50d85a0a..e0ffe21b 100644 --- a/source/read/count.txt +++ b/source/read/count.txt @@ -65,7 +65,7 @@ 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 with a ``year`` field value equal to ``1930``: +in the ``movies`` collection that have a ``year`` field value equal to ``1930``: .. io-code-block::