Skip to content

Commit b9a7270

Browse files
mcmorisimcmorisi
authored
DOCSP-41137: Count Documents (#4)
1 parent 4b28c95 commit b9a7270

File tree

4 files changed

+213
-21
lines changed

4 files changed

+213
-21
lines changed

‎snooty.toml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
66
"https://www.mongodb.com/docs/atlas/objects.inv"
77
]
88

9-
toc_landing_pages = []
9+
toc_landing_pages = [
10+
"/read"
11+
]
1012

1113
[constants]
1214
driver-long = "MongoDB Kotlin Sync Driver"

‎source/index.txt

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,17 @@
1+
.. _kotlin-sync-index:
2+
13
==========================
24
{+driver-long+}
35
==========================
46

7+
.. facet::
8+
:name: programming_language
9+
:values: kotlin
10+
11+
.. meta::
12+
:keywords: home
13+
514
.. toctree::
6-
:titlesonly:
7-
:maxdepth: 1
815

916
/read
1017
/faq

‎source/read.txt

Lines changed: 11 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -18,18 +18,11 @@ Read Data from MongoDB
1818
:description: Learn how to use the Kotlin Sync Driver to read data from MongoDB.
1919
:keywords: usage examples, query, find, code example
2020

21-
.. .. toctree::
22-
.. :titlesonly:
23-
.. :maxdepth: 1
24-
25-
.. /read/specify-a-query
26-
.. /read/retrieve
27-
.. /read/project
28-
.. /read/specify-documents-to-return
29-
.. /read/count
30-
.. /read/distinct
31-
.. /read/cursors
32-
.. /read/change-streams
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
24+
25+
/read/count
3326

3427
Overview
3528
--------
@@ -88,8 +81,8 @@ The following example returns the number of documents in the specified collectio
8881
:copyable:
8982
:dedent:
9083

91-
.. TODO: To learn more about the ``count_documents()`` method, see the
92-
.. :ref:`kotlin-sync-accurate-count` guide.
84+
To learn more about the ``countDocuments()`` method, see the
85+
:ref:`kotlin-sync-accurate-count` section of the Count Documents guide.
9386

9487
Count Documents Returned from a Query
9588
-------------------------------------
@@ -104,8 +97,8 @@ the given filter:
10497
:copyable:
10598
:dedent:
10699

107-
.. TODO: To learn more about the ``countDocuments()`` method, see the
108-
.. :ref:`kotlin-sync-accurate-count` guide.
100+
To learn more about the ``countDocuments()`` method, see the
101+
:ref:`kotlin-sync-accurate-count` section of the Count Documents guide.
109102

110103
Estimated Document Count
111104
------------------------
@@ -120,8 +113,8 @@ collection based on collection metadata:
120113
:copyable:
121114
:dedent:
122115

123-
.. TODO: To learn more about the ``estimatedDocumentCount()`` method, see the
124-
.. :ref:`kotlin-sync-estimated-count` guide.
116+
To learn more about the ``estimatedDocumentCount()`` method, see the
117+
:ref:`kotlin-sync-estimated-count` section of the Count Documents guide.
125118

126119
Retrieve Distinct Values
127120
------------------------

‎source/read/count.txt

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
.. _kotlin-sync-count:
2+
3+
===============
4+
Count Documents
5+
===============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: number, amount, estimation, code example
19+
20+
Overview
21+
---------
22+
23+
In this guide, you can learn how to retrieve accurate and estimated counts of the
24+
number of documents in a collection.
25+
26+
Sample Data
27+
~~~~~~~~~~~
28+
29+
The examples in this guide use the ``movies`` collection in the ``sample_mflix``
30+
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
31+
free MongoDB Atlas cluster and load the sample datasets, see the
32+
:atlas:`Get Started with Atlas </getting-started>` guide.
33+
34+
.. _kotlin-sync-accurate-count:
35+
36+
Retrieve an Accurate Count
37+
--------------------------
38+
39+
Use the ``countDocuments()`` method to count the number of documents that are in a
40+
collection. To count the number of documents that match specified search
41+
critera, pass a query filter to the ``countDocuments()`` method.
42+
43+
.. TODO: To learn more about specifying a query, see :ref:`kotlin-sync-specify-query`.
44+
45+
Count All Documents
46+
~~~~~~~~~~~~~~~~~~~
47+
48+
To return a count of all documents in the collection, call the ``countDocuments()`` method
49+
with no arguments, as shown in the following example:
50+
51+
.. io-code-block::
52+
53+
.. input::
54+
:language: kotlin
55+
56+
print(collection.countDocuments())
57+
58+
.. output::
59+
:visible: false
60+
61+
21349
62+
63+
Count Specific Documents
64+
~~~~~~~~~~~~~~~~~~~~~~~~
65+
66+
To return a count of documents that match specific search criteria, specify your query
67+
in the ``countDocuments()`` method. The following example prints a count of all documents
68+
in the ``movies`` collection that have a ``year`` field value equal to ``1930``:
69+
70+
.. io-code-block::
71+
72+
.. input::
73+
:language: kotlin
74+
75+
print(collection.countDocuments(eq("year", "1930")))
76+
77+
.. output::
78+
:visible: false
79+
80+
10
81+
82+
Customize Count Behavior
83+
~~~~~~~~~~~~~~~~~~~~~~~~
84+
85+
The ``countDocuments()`` method accepts optional parameters in the form of a
86+
``CountOptions`` object, which represents options you can use to configure the count
87+
operation. You can set these options by instantiating a new ``CountOptions`` object,
88+
setting the object's fields using the corresponding methods, and passing it to the
89+
``countDocuments()`` method. If you don't specify any options, the driver does not
90+
customize the count operation.
91+
92+
The following table describes the options you can set to customize ``countDocuments()``:
93+
94+
.. list-table::
95+
:widths: 30 70
96+
:header-rows: 1
97+
98+
* - Option
99+
- Description
100+
101+
* - ``comment``
102+
- | A comment to attach to the operation.
103+
104+
* - ``skip``
105+
- | The number of documents to skip before returning results.
106+
107+
* - ``limit``
108+
- | The maximum number of documents to count. Must be a positive integer.
109+
110+
* - ``maxTime``
111+
- | The maximum amount of time to allow the operation to run, in milliseconds.
112+
113+
* - ``collation``
114+
- | The collation to use for the operation.
115+
116+
* - ``hint``
117+
- | Gets or sets the index to scan for documents.
118+
119+
The following example uses a ``CountOptions`` object to add a comment to the
120+
``countDocuments()`` operation:
121+
122+
.. code-block:: kotlin
123+
124+
val options = CountOptions().comment("Retrieving count")
125+
collection.countDocuments(options)
126+
127+
.. _kotlin-sync-estimated-count:
128+
129+
Retrieve an Estimated Count
130+
---------------------------
131+
132+
Use the ``estimatedDocumentCount()`` method to retrieve an estimate of the number of
133+
documents in a collection. The method estimates the amount of documents based on
134+
collection metadata, which can be faster than performing an accurate count.
135+
136+
The following example prints the estimated number of documents in a collection:
137+
138+
.. io-code-block::
139+
140+
.. input::
141+
:language: kotlin
142+
143+
print(collection.estimatedDocumentCount())
144+
145+
.. output::
146+
:visible: false
147+
148+
21349
149+
150+
Customize Estimated Count Behavior
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+
The ``estimatedDocumentCount()`` method accepts optional parameters in the form of an
154+
``EstimatedDocumentCountOptions`` object, which represents options you can use to configure
155+
the count operation. You can set these options by instantiating a new
156+
``EstimatedDocumentCountOptions`` object, setting the object's fields using the
157+
corresponding methods, and passing it to the ``estimatedDocumentCount()`` method.
158+
If you don't specify any options, the driver does not customize the count operation.
159+
160+
The following table describes the options you can set to customize ``estimatedDocumentCount()``:
161+
162+
.. list-table::
163+
:widths: 30 70
164+
:header-rows: 1
165+
166+
* - Option
167+
- Description
168+
169+
* - ``comment``
170+
- | A comment to attach to the operation.
171+
172+
* - ``maxTime``
173+
- | The maximum amount of time to allow the operation to run, in milliseconds.
174+
175+
The following example uses an ``EstimatedDocumentCountOptions`` object to add a comment to
176+
the ``estimatedDocumentCount()`` operation:
177+
178+
.. code-block:: kotlin
179+
180+
val options = EstimatedDocumentCountOptions().comment("Retrieving count")
181+
collection.estimatedDocumentCount(options)
182+
183+
API Documentation
184+
-----------------
185+
186+
To learn more about any of the methods or types discussed in this
187+
guide, see the following API documentation:
188+
189+
- `countDocuments() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/count-documents.html>`__
190+
- `estimatedDocumentCount() <{+api+}/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-collection/estimated-document-count.html>`__

0 commit comments

Comments
 (0)