|
179 | 179 | /** |
180 | 180 | * Gets an estimate of the count of documents in a collection using collection metadata. |
181 | 181 | * |
182 | | - * See "Count API Details" section below. |
| 182 | + * See "Count API Details" section below for implementation and documentation |
| 183 | + * requirements. |
183 | 184 | */ |
184 | 185 | estimatedDocumentCount(options: Optional<EstimatedDocumentCountOptions>): Int64; |
185 | 186 |
|
|
412 | 413 | * The comment can be any valid BSON type for server versions 4.4.14 and above. |
413 | 414 | * For server versions between 4.4.0 and 4.4.14 string comment is supported. |
414 | 415 | * Servers versions below 4.4.0 do not support comment for count command, |
415 | | - * which is used to implement estimatedDocumentCount for server versions |
416 | | - * versions less than 4.9.0. Therefore, providing a comment may result |
417 | | - * in a server-side error. |
| 416 | + * which is used to implement estimatedDocumentCount. Therefore, providing a |
| 417 | + * comment may result in a server-side error. |
418 | 418 | */ |
419 | 419 | comment: Optional<any>; |
420 | 420 | } |
@@ -754,30 +754,39 @@ older sharded clusters. |
754 | 754 | estimatedDocumentCount |
755 | 755 | ~~~~~~~~~~~~~~~~~~~~~~ |
756 | 756 |
|
757 | | -On server versions greater than or equal to 4.9.0 (wire version 12 or higher), |
758 | | -the estimatedDocumentCount function is implemented using the ``$collStats`` |
759 | | -aggregate pipeline stage with ``$group`` to gather results from multiple shards. |
760 | | -As documented above, the only supported option is maxTimeMS:: |
761 | | - |
762 | | - pipeline = [ |
763 | | - { '$collStats': { 'count': {} } }, |
764 | | - { '$group': { '_id': 1, 'n': { '$sum': '$count' } } } |
765 | | - ] |
766 | | - |
767 | | -Similar to the count command, the estimated count of documents is returned |
768 | | -in the ``n`` field. Implementations can assume that the document containing |
769 | | -the single result of the aggregation pipeline is contained in the first batch of |
770 | | -the server's reply to the aggregate command. It is not necessary to execute a getMore |
771 | | -operation to ensure that the result is available. |
772 | | - |
773 | | -In the event this aggregation is run against a non-existent namespace, a NamespaceNotFound(26) |
774 | | -error will be returned during execution. Drivers MUST interpret the server error code 26 as |
775 | | -a ``0`` count. |
776 | | - |
777 | | -For server versions less than 4.9.0 (wire version 11 or under), the estimatedDocumentCount |
778 | | -function is implemented using the ``count`` command with no query filter, skip, |
779 | | -limit, or other options that would alter the results. Once again, the only supported |
780 | | -option is maxTimeMS. |
| 757 | +The estimatedDocumentCount function is implemented using the ``count`` command |
| 758 | +with no query filter, skip, limit, or other options that would alter the |
| 759 | +results. The only supported options are listed in the |
| 760 | +``EstimatedDocumentCountOptions`` type defined above. |
| 761 | + |
| 762 | +Drivers MUST document that, due to an oversight in versions 5.0.0-5.0.7 of |
| 763 | +MongoDB, the ``count`` command, which estimatedDocumentCount uses in its |
| 764 | +implementation, was not included in v1 of the Stable API, and so users of the |
| 765 | +Stable API with estimatedDocumentCount are recommended to upgrade their server |
| 766 | +version to 5.0.8+ or set ``apiStrict: false`` to avoid encountering errors. |
| 767 | + |
| 768 | +Drivers MUST document that the ``count`` server command is used to implement |
| 769 | +estimatedDocumentCount and that users can find more information via |
| 770 | +`Count: Behavior <https://www.mongodb.com/docs/manual/reference/command/count/#behavior>`_. |
| 771 | + |
| 772 | +The 5.0-compat versions of many drivers updated their estimatedDocumentCount |
| 773 | +implementations to use the ``$collStats`` aggregation stage instead of the |
| 774 | +``count`` command. This had the unintended consequence of breaking |
| 775 | +estimatedDocumentCount on views, and so the change was seen as a |
| 776 | +backwards-incompatible regression and reverted. The release notes for the driver |
| 777 | +versions that include the reversion from ``$collStats`` back to ``count`` MUST |
| 778 | +document the following: |
| 779 | + |
| 780 | +- The 5.0-compat release accidentally broke estimatedDocumentCount on views by |
| 781 | + changing its implementation to use ``aggregate`` and a ``$collStats`` stage |
| 782 | + instead of the ``count`` command. |
| 783 | +- The new release is fixing estimatedDocumentCount on views by reverting back to |
| 784 | + using ``count`` in its implementation. |
| 785 | +- Due to an oversight, the ``count`` command was omitted from the Stable API in |
| 786 | + server versions 5.0.0 - 5.0.7 and 5.1.0 - 5.3.1, so users of the Stable API |
| 787 | + with estimatedDocumentCount are recommended to upgrade their MongoDB clusters |
| 788 | + to 5.0.8 or 5.3.2 (if on Atlas) or set ``apiStrict: false`` when constructing |
| 789 | + their MongoClients. |
781 | 790 |
|
782 | 791 | ~~~~~~~~~~~~~~ |
783 | 792 | countDocuments |
@@ -2354,9 +2363,13 @@ Q: Where is ``singleBatch`` in FindOptions? |
2354 | 2363 | Q: Why are client-side errors raised for some unsupported options? |
2355 | 2364 | Server versions before 3.4 were inconsistent about reporting errors for unrecognized command options and may simply ignore them, which means a client-side error is the only way to inform users that such options are unsupported. For unacknowledged writes using OP_MSG, a client-side error is necessary because the server has no chance to return a response (even though a 3.6+ server is otherwise capable of reporting errors for unrecognized options). For unacknowledged writes using legacy opcodes (i.e. OP_INSERT, OP_UPDATE, and OP_DELETE), the message body has no field with which to express these options so a client-side error is the only mechanism to inform the user that such options are unsupported. The spec does not explicitly refer to unacknowledged writes using OP_QUERY primarily because a response document is always returned and drivers generally would not consider using OP_QUERY precisely for that reason. |
2356 | 2365 |
|
| 2366 | +Q: Why does reverting to using ``count`` instead of ``aggregate`` with ``$collStats`` for estimatedDocumentCount not require a major version bump in the drivers, even though it might break users of the Stable API? |
| 2367 | + SemVer `allows <https://semver.org/#what-if-i-inadvertently-alter-the-public-api-in-a-way-that-is-not-compliant-with-the-version-number-change-ie-the-code-incorrectly-introduces-a-major-breaking-change-in-a-patch-release>`_ for a library to include a breaking change in a minor or patch version if the change is required to fix another accidental breaking change introduced in a prior version and is not expected to further break a large number of users. Given that the original switch to ``$collStats`` was a breaking change due to it not working on views, the number of users using estimatedDocumentCount with ``apiStrict: true`` is small, and the server is back-porting the addition of ``count`` to the Stable API, it was decided that this change was acceptable to make in minor version releases of the drivers per the aforementioned allowance in the SemVer spec. |
| 2368 | + |
2357 | 2369 | Changes |
2358 | 2370 | ======= |
2359 | 2371 |
|
| 2372 | +* 2022-04-21: Revert to using the ``count`` command for ``estimatedDocumentCount`` |
2360 | 2373 | * 2022-02-18: Add let to BulkWriteOptions. |
2361 | 2374 | * 2022-02-10: Specified that ``getMore`` command must explicitly send inherited comment. |
2362 | 2375 | * 2022-02-01: Add comment attribute to all helpers. |
|
0 commit comments