Skip to content

Commit 41cd85e

Browse files
norareidynorareidy
authored
DOCSP-45197: Count documents (#110)
* DOCSP-45197: Count documents * edits * code fix * JS feedback
1 parent 91b251a commit 41cd85e

File tree

3 files changed

+301
-0
lines changed

3 files changed

+301
-0
lines changed

‎source/includes/read/count.rb

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# start-db-coll
12+
database = client.use('sample_training')
13+
collection = database['companies']
14+
# end-db-coll
15+
16+
# Counts all documents in the collection
17+
# start-count-all
18+
result = collection.count_documents
19+
puts "Number of documents: #{result}"
20+
# end-count-all
21+
22+
# Counts documents that have a "founded_year" value of 2010
23+
# start-count-accurate
24+
result = collection.count_documents(founded_year: 2010)
25+
puts "Number of companies founded in 2010: #{result}"
26+
# end-count-accurate
27+
28+
# Counts a maximum of 100 documents that have a "number_of_employees" value of 50
29+
# start-modify-accurate
30+
result = collection.count_documents({ number_of_employees: 50 }, limit: 100)
31+
puts "Number of companies with 50 employees: #{result}"
32+
# end-modify-accurate
33+
34+
# Estimates the number of documents in the collection
35+
# start-count-estimate
36+
result = collection.estimated_document_count
37+
puts "Estimated number of documents: #{result}"
38+
# end-count-estimate
39+
40+
# Estimates the number of documents in the collection and sets a time limit on the operation
41+
# start-modify-estimate
42+
result = collection.estimated_document_count(max_time_ms: 1000)
43+
puts "Estimated number of documents: #{result}"
44+
# end-modify-estimate
45+
end

‎source/read.txt

+1
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,4 @@ Read Data from MongoDB
2626
Specify a Query </read/specify-a-query>
2727
Specify Documents to Return </read/specify-documents-to-return>
2828
Specify Fields to Return </read/project>
29+
Count Documents </read/count>

‎source/read/count.txt

+255
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
.. _ruby-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 use the {+driver-short+} to retrieve an accurate
24+
and estimated count of the number of documents in a collection. The following methods
25+
count documents in a collection:
26+
27+
- ``count_documents``: Returns the exact number of documents that
28+
match a query filter or that exist in a collection
29+
30+
- ``estimated_document_count``: Returns the estimated number of documents
31+
that exist in a collection
32+
33+
Sample Data
34+
~~~~~~~~~~~
35+
36+
The examples in this guide use the ``companies`` collection in the ``sample_training``
37+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
38+
from your {+language+} application, create a ``Mongo::Client`` object that connects to
39+
an Atlas cluster and assign the following values to your ``database`` and ``collection``
40+
variables:
41+
42+
.. literalinclude:: /includes/read/count.rb
43+
:language: ruby
44+
:dedent:
45+
:start-after: start-db-coll
46+
:end-before: end-db-coll
47+
48+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
49+
:atlas:`Get Started with Atlas </getting-started>` guide.
50+
51+
.. _ruby-accurate-count:
52+
53+
Retrieve an Accurate Count
54+
--------------------------
55+
56+
Use the ``count_documents`` method to count the number of documents
57+
in a collection. To count the number of documents that match specific search criteria,
58+
pass a query filter to the ``count_documents`` method.
59+
60+
.. TODO: To learn more about specifying a query, see the :ref:`ruby-specify-query` guide.
61+
62+
.. _ruby-count-all:
63+
64+
Count All Documents
65+
~~~~~~~~~~~~~~~~~~~
66+
67+
To return a count of all documents in the collection, call the
68+
``count_documents`` method without passing a query filter, as shown
69+
in the following example:
70+
71+
.. io-code-block::
72+
:copyable:
73+
74+
.. input:: /includes/read/count.rb
75+
:start-after: start-count-all
76+
:end-before: end-count-all
77+
:language: ruby
78+
:dedent:
79+
80+
.. output::
81+
:visible: false
82+
83+
Number of documents: 9500
84+
85+
.. _ruby-count-specific:
86+
87+
Count Specific Documents
88+
~~~~~~~~~~~~~~~~~~~~~~~~
89+
90+
To return a count of documents that match specific search criteria, pass a query
91+
filter to the ``count_documents`` method.
92+
93+
The following example counts the number of documents in which the value of the
94+
``founded_year`` field is ``2010``:
95+
96+
.. io-code-block::
97+
:copyable:
98+
99+
.. input:: /includes/read/count.rb
100+
:start-after: start-count-accurate
101+
:end-before: end-count-accurate
102+
:language: ruby
103+
:dedent:
104+
105+
.. output::
106+
:visible: false
107+
108+
Number of companies founded in 2010: 33
109+
110+
Customize Count Behavior
111+
~~~~~~~~~~~~~~~~~~~~~~~~
112+
113+
You can modify the behavior of the ``count_documents`` method by
114+
passing a second parameter that specifies option values. The following table
115+
describes the options you can set to customize the count operation:
116+
117+
.. list-table::
118+
:widths: 30 70
119+
:header-rows: 1
120+
121+
* - Option
122+
- Description
123+
124+
* - ``collation``
125+
- | The collation to use for the operation.
126+
| **Type**: ``Hash``
127+
128+
* - ``hint``
129+
- | The index to use for the operation.
130+
| **Type**: ``Hash``
131+
132+
* - ``comment``
133+
- | The comment to attach to the operation.
134+
| **Type**: ``Object``
135+
136+
* - ``limit``
137+
- | The maximum number of documents to count. This value must be a positive integer.
138+
| **Type**: ``Integer``
139+
140+
* - ``max_time_ms``
141+
- | The maximum amount of time in milliseconds that the operation can run.
142+
| **Type**: ``Integer``
143+
144+
* - ``skip``
145+
- | The number of documents to skip before counting documents.
146+
| **Type**: ``Integer``
147+
148+
* - ``read``
149+
- | The read preference to use for the operation. To learn more, see
150+
:manual:`Read Preference </core/read-preference/>` in the {+mdb-server+} manual.
151+
| **Type**: ``Hash``
152+
153+
The following example uses the ``count_documents`` method to count the number of
154+
documents in which the ``number_of_employees`` field has the value ``50`` and instructs the
155+
operation to count a maximum of ``100`` results:
156+
157+
.. io-code-block::
158+
:copyable:
159+
160+
.. input:: /includes/read/count.rb
161+
:start-after: start-modify-accurate
162+
:end-before: end-modify-accurate
163+
:language: ruby
164+
:dedent:
165+
166+
.. output::
167+
:visible: false
168+
169+
Number of companies with 50 employees: 100
170+
171+
.. important::
172+
173+
When you pass an options parameter to the ``count_documents`` method,
174+
you must enclose the query filter in brackets (``{}``).
175+
176+
.. _ruby-estimated-count:
177+
178+
Retrieve an Estimated Count
179+
---------------------------
180+
181+
You can retrieve an estimate of the number of documents in a collection by calling
182+
the ``estimated_document_count`` method. The method estimates the amount
183+
of documents based on collection metadata, which might be faster than
184+
performing an accurate count.
185+
186+
The following example estimates the number of documents in a collection:
187+
188+
.. io-code-block::
189+
:copyable:
190+
191+
.. input:: /includes/read/count.rb
192+
:start-after: start-count-estimate
193+
:end-before: end-count-estimate
194+
:language: ruby
195+
:dedent:
196+
197+
.. output::
198+
:visible: false
199+
200+
Estimated number of documents: 9500
201+
202+
Customize Estimated Count Behavior
203+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
204+
205+
You can modify the behavior of the ``estimated_document_count`` method
206+
by passing a parameter that specifies option values. The
207+
following table describes the options you can set to customize
208+
the operation:
209+
210+
.. list-table::
211+
:widths: 30 70
212+
:header-rows: 1
213+
214+
* - Option
215+
- Description
216+
217+
* - ``comment``
218+
- | The comment to attach to the operation.
219+
| **Type**: ``Object``
220+
221+
* - ``max_time_ms``
222+
- | The maximum amount of time in milliseconds that the operation can run.
223+
| **Type**: ``Integer``
224+
225+
* - ``read``
226+
- | The read concern to use for the operation. To learn more, see
227+
:manual:`Read Concern </reference/read-concern/>` in the {+mdb-server+} manual.
228+
| **Type**: ``Hash``
229+
230+
The following example uses the ``estimated_document_count`` method to return an
231+
estimate of the number of documents in the collection and sets a timeout of
232+
``1000`` milliseconds on the operation:
233+
234+
.. io-code-block::
235+
:copyable:
236+
237+
.. input:: /includes/read/count.rb
238+
:start-after: start-modify-estimate
239+
:end-before: end-modify-estimate
240+
:language: ruby
241+
:dedent:
242+
243+
.. output::
244+
:visible: false
245+
246+
Estimated number of documents: 9500
247+
248+
API Documentation
249+
-----------------
250+
251+
To learn more about any of the methods discussed in this
252+
guide, see the following API documentation:
253+
254+
- `count_documents <{+api-root+}/Mongo/Collection.html#count_documents-instance_method>`__
255+
- `estimated_document_count <{+api-root+}/Mongo/Collection.html#estimated_document_count-instance_method>`__

0 commit comments

Comments
 (0)