<!-- 
RSS generated by JIRA (9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66) at Thu Feb 08 08:21:59 UTC 2024

It is possible to restrict the fields that are returned in this document by specifying the 'field' parameter in your request.
For example, to request only the issue key and summary append 'field=key&field=summary' to the URL of your request.
-->
<rss version="0.92" >
<channel>
    <title>MongoDB Jira</title>
    <link>https://jira.mongodb.org</link>
    <description>This file is an XML representation of an issue</description>
    <language>en-us</language>    <build-info>
        <version>9.7.1</version>
        <build-number>970001</build-number>
        <build-date>13-04-2023</build-date>
    </build-info>


<item>
            <title>[DRIVERS-630] Documentation for countDocuments MUST mention estimatedDocumentCount</title>
                <link>https://jira.mongodb.org/browse/DRIVERS-630</link>
                <project id="10980" key="DRIVERS">Drivers</project>
                    <description>&lt;p&gt;The estimatedDocumentCount helper is not easily discoverable by developers migrating from the count helper. For example, estimatedDocumentCount doesn&apos;t autocomplete in IDEs when searching for helpers related to count. This is a problem since applications that only need an estimated count can take a large performance hit when using countDocuments for that purpose.&lt;/p&gt;

&lt;p&gt;Drivers MUST add text to the documentation for countDocuments directing these users to estimatedDocumentCount. Suggested text:&lt;/p&gt;

&lt;p&gt;&quot;For a fast count of the total documents in a collection see estimatedDocumentCount&quot; with a link to the documentation for that helper.&lt;/p&gt;


&lt;p&gt;Original report below&lt;br/&gt;
----------------------------&lt;/p&gt;

&lt;p&gt;It was suggested I file a DRIVERS with some feedback based on a pair of observations converting applications from mgo to mongo-go-driver, although what follows is perhaps general to &lt;a href=&quot;https://jira.mongodb.org/browse/DRIVERS-501&quot; title=&quot;Implement new count API&quot; class=&quot;issue-link&quot; data-issue-key=&quot;DRIVERS-501&quot;&gt;&lt;del&gt;DRIVERS-501&lt;/del&gt;&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;In two independent instances, application developers where looking to upgrade to drivers which included the new Count APIs from &lt;a href=&quot;https://jira.mongodb.org/browse/DRIVERS-501&quot; title=&quot;Implement new count API&quot; class=&quot;issue-link&quot; data-issue-key=&quot;DRIVERS-501&quot;&gt;&lt;del&gt;DRIVERS-501&lt;/del&gt;&lt;/a&gt;. Developers matched up existing &lt;tt&gt;Count()&lt;/tt&gt; with the new API and, probably via auto-complete on the driver API, intuitively selected &lt;tt&gt;CountDocuments()&lt;/tt&gt; in the case of mongo-go-driver and presumed was equivalent to what the past driver (mgo) was doing.&lt;/p&gt;

&lt;p&gt;I&apos;m guessing that the developer intuitively picking CountDocuments() is maybe viewed as a &quot;success&quot; from aim of &lt;a href=&quot;https://jira.mongodb.org/browse/DRIVERS-501&quot; title=&quot;Implement new count API&quot; class=&quot;issue-link&quot; data-issue-key=&quot;DRIVERS-501&quot;&gt;&lt;del&gt;DRIVERS-501&lt;/del&gt;&lt;/a&gt;. But, in both of these independent cases it had severe unexpected consequences. These were Count()&apos;s with no query predicates. So, internally to mongod, we were getting the &quot;fast path&quot; constant time document count from collection metadata (and were fine with the inaccuracy). When switched to &lt;tt&gt;CountDocuments()&lt;/tt&gt; and the agg, we were now getting a scan instead.&lt;/p&gt;

&lt;p&gt;In particular, one occurrence was against the oplog collection: the &lt;b&gt;worst case&lt;/b&gt;. While other user collections on modern mongod versions would at least complete the agg with only an _id index scan, on the oplog it&apos;s a full document scan. I understand the scan&apos;s count is accurate now.. but IMO don&apos;t think is ever what a user would want/expect coming from constant time performance before.&lt;/p&gt;

&lt;p&gt;I&apos;m unclear exactly how best to head off future cases. Maybe some API documentation on CountDocuments() that prominently calls out that it&apos;s not constant time like EstimatedCount()? Unclear if this would&apos;ve helped or not. But the two occurrences of falling into the same trap makes me wonder if it could be a common mishap for users.&lt;/p&gt;</description>
                <environment></environment>
        <key id="735650">DRIVERS-630</key>
            <summary>Documentation for countDocuments MUST mention estimatedDocumentCount</summary>
                <type id="3" iconUrl="https://jira.mongodb.org/secure/viewavatar?size=xsmall&amp;avatarId=14718&amp;avatarType=issuetype">Task</type>
                                            <priority id="3" iconUrl="https://jira.mongodb.org/images/icons/priorities/major.svg">Major - P3</priority>
                        <status id="6" iconUrl="https://jira.mongodb.org/images/icons/statuses/closed.png" description="The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.">Closed</status>
                    <statusCategory id="3" key="done" colorName="success"/>
                                    <resolution id="9">Done</resolution>
                                        <assignee username="-1">Unassigned</assignee>
                                    <reporter username="john.morales@mongodb.com">John Morales</reporter>
                        <labels>
                    </labels>
                <created>Wed, 10 Apr 2019 19:49:45 +0000</created>
                <updated>Wed, 22 Feb 2023 03:01:24 +0000</updated>
                            <resolved>Wed, 22 Feb 2023 03:01:24 +0000</resolved>
                                                                            <votes>0</votes>
                                    <watches>5</watches>
                                                                                                                <comments>
                            <comment id="2221971" author="jtjeferreira" created="Tue, 23 Apr 2019 15:55:04 +0000"  >&lt;p&gt;My experience was also similar, I migrated the old `count(filter)` to `countDocuments(filter)` without noticing the note to migrate some query operators. Changing all the filters was not so easy to keep using the old deprecated count, but I wouldnt mind if there was a non deprecated way to call `estimateDocumentCount(filter)` (i.e with an old filter argument...)&lt;/p&gt;</comment>
                            <comment id="2210887" author="john.morales@10gen.com" created="Fri, 12 Apr 2019 13:23:27 +0000"  >&lt;p&gt;Fantastic, yep I agree and think referencing estimatedDocumentCount from documentCount is best option, too. Thank you!&lt;/p&gt;</comment>
                            <comment id="2208904" author="behackett" created="Wed, 10 Apr 2019 22:15:54 +0000"  >&lt;p&gt;Oh, another important tidbit, the count command doesn&apos;t work in a transaction (that&apos;s what caused all this in the first place). If you want to do a count in a transaction you have no choice but to use countDocuments. &lt;/p&gt;</comment>
                            <comment id="2208902" author="behackett" created="Wed, 10 Apr 2019 22:11:32 +0000"  >&lt;p&gt;How about we add text to the docstring in each driver, something like:&lt;/p&gt;

&lt;p&gt;&quot;For a fast count of the total documents in a collection see estimatedDocumentCount&quot; with a link to the docs for that method / function.&lt;/p&gt;</comment>
                            <comment id="2208898" author="behackett" created="Wed, 10 Apr 2019 22:07:45 +0000"  >&lt;p&gt;That&apos;s a great insight about auto-completion. We debated the names a lot. countAccurate and countEstimate were considered and rejected because using the word &quot;accurate&quot; could be misleading on older versions of the server drivers are still required to support. The &quot;Client Side Count Improvements&quot; scope document has a lot more context in it (especially the comment chains). The naming decision was finalized in a review meeting with the entire management chain.&lt;/p&gt;

&lt;p&gt;&lt;b&gt;edit&lt;/b&gt; - I recall that we picked the name estimatedDocumentCount because that&apos;s what it &lt;em&gt;is&lt;/em&gt; (no work is done on the server side to calculate the number, it just returns the number from pre-calculated metadata), as opposed to countDocuments which is what that &lt;em&gt;does&lt;/em&gt; on the server side. &lt;/p&gt;

&lt;p&gt;At a minimum better docs are in order, especially in Go. Compare &lt;a href=&quot;https://godoc.org/go.mongodb.org/mongo-driver/mongo#Collection.CountDocuments&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;Go&lt;/a&gt; to &lt;a href=&quot;https://api.mongodb.com/python/current/api/pymongo/collection.html#pymongo.collection.Collection.count_documents&quot; class=&quot;external-link&quot; target=&quot;_blank&quot; rel=&quot;nofollow noopener&quot;&gt;Python&lt;/a&gt; for example. I don&apos;t think any driver calls out using estimatedDocumentCount in the docstring for countDocuments. Doing that would probably help a lot.&lt;/p&gt;</comment>
                            <comment id="2208734" author="john.morales@10gen.com" created="Wed, 10 Apr 2019 20:14:41 +0000"  >&lt;p&gt;Yeah I figured that &amp;#8211; I mentioned the auto-complete as I think in our cases anyway, developers didn&apos;t know the EstimatedCount variant was even a thing.&lt;/p&gt;

&lt;p&gt;Regarding a performance warning in all drivers, I&apos;m honestly not sure! Maybe? I don&apos;t mean to really prescribe anything.. figured I&apos;d start by sharing and starting a conversation. Perhaps other/better options than an API doc change might come out, too. I think awareness of the &lt;em&gt;difference&lt;/em&gt; for users already familiar with the past APIs, and awareness of EstimatedCount, are probably the main goals of any ideas.&lt;/p&gt;</comment>
                            <comment id="2208726" author="behackett" created="Wed, 10 Apr 2019 20:05:52 +0000"  >&lt;p&gt;The names were chosen in an attempt to make this clear. countDocuments literally counts the documents. Would you prefer that we add a warning about performance to the docs in all drivers?&lt;/p&gt;</comment>
                    </comments>
                <issuelinks>
                            <issuelinktype id="10011">
                    <name>Depends</name>
                                            <outwardlinks description="depends on">
                                        <issuelink>
            <issuekey id="774444">CDRIVER-3146</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774451">CSHARP-2619</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774440">CXX-1774</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774441">JAVA-3299</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774448">JAVA-3538</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774442">MOTOR-347</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774446">NODE-1981</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774443">PHPLIB-434</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774450">PYTHON-1847</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774439">GODRIVER-1083</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="1431708">MONGOID-4958</issuekey>
        </issuelink>
            <issuelink>
            <issuekey id="774449">RUBY-1817</issuekey>
        </issuelink>
                            </outwardlinks>
                                                        </issuelinktype>
                    </issuelinks>
                <attachments>
                    </attachments>
                <subtasks>
                    </subtasks>
                <customfields>
                                                                                                                                                                                                                                                                                                            <customfield id="customfield_15850" key="com.atlassian.jira.plugins.jira-development-integration-plugin:devsummary">
                        <customfieldname>Development</customfieldname>
                        <customfieldvalues>
                            
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                <customfield id="customfield_23952" key="com.onresolve.jira.groovy.groovyrunner:scripted-field">
                        <customfieldname>Driver Compliance</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue><![CDATA[<style type='text/css'>
         #scriptField, #scriptField *{
                border: 1px solid black;
            }

            #scriptField{
                border-collapse: collapse;
            }

            #scriptField td {
                text-align: center; /* Center-align text in table cells */
            }

            #scriptField td.key {
                text-align: left; /* Left-align text in the Key column */
            }

            #scriptField a {
                text-decoration: none; /* Remove underlines from links */
                border: none; /* Remove border from links */
            }
            
            /* Add green background color to cells with FixVersion */
            #scriptField td.hasFixVersion {
                background-color: #00FF00; /* Green color code */
            }

            /* Center-align the first row headers */
            #scriptField th {
                text-align: center;
            }
        </style>
<table id='scriptField'>
  <tr>
    <th>Key</th>
    <th>Status/Resolution</th>
    <th>FixVersion</th>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/PERL-1101'>PERL-1101</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>2.1.1</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/GODRIVER-1083'>GODRIVER-1083</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>1.1.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/CXX-1774'>CXX-1774</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>3.7.0, 3.7.0-beta1</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/JAVA-3299'>JAVA-3299</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>3.11.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/MOTOR-347'>MOTOR-347</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>2.1</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/PHPLIB-434'>PHPLIB-434</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>1.7.0-beta1, 1.7.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/CDRIVER-3146'>CDRIVER-3146</a>
    </td>
    <td>Works as Designed</td>
    <td class=''></td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/NODE-1981'>NODE-1981</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>next</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/SCALA-529'>SCALA-529</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>2.7.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/JAVA-3538'>JAVA-3538</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>4.0.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/RUBY-1817'>RUBY-1817</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>2.13.1</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/PYTHON-1847'>PYTHON-1847</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>3.9</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/CSHARP-2619'>CSHARP-2619</a>
    </td>
    <td>Fixed</td>
    <td class='hasFixVersion'>2.10.0</td>
  </tr>
  <tr>
    <td class='key'>
      <a href='https://jira.mongodb.org/browse/MONGOID-4958'>MONGOID-4958</a>
    </td>
    <td>Duplicate</td>
    <td class=''></td>
  </tr>
</table>]]></customfieldvalue>


                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        <customfield id="customfield_12550" key="com.pyxis.greenhopper.jira:gh-lexo-rank">
                        <customfieldname>Rank</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>2|hujiwv:</customfieldvalue>

                        </customfieldvalues>
                    </customfield>
                                                                <customfield id="customfield_10558" key="com.pyxis.greenhopper.jira:gh-global-rank">
                        <customfieldname>Rank (Obsolete)</customfieldname>
                        <customfieldvalues>
                            <customfieldvalue>9223372036854775807</customfieldvalue>
                        </customfieldvalues>
                    </customfield>
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        </customfields>
    </item>
</channel>
</rss>