feat: _useEstimate parameter in count requests

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- Includes query paramater `_useEstimate` on `GET \count` requests to execute the MongoDB `estimatedDocumentCount`   
+
 ### Fixed
 
 - [#237](https://github.com/mia-platform/crud-service/issues/237): casting values in `_q` queries are now even if case of nested fields

docs/10_Overview_and_Usage.md

@@ -763,6 +763,14 @@ This will return:
 Filters can be applied to the count. By default, only PUBLIC documents are counted.
 :::
 
+You can add the parameter `_useEstimate`, to be set to true, to execute the count request using the collection metadata instead of scanning the entire collection. This method drastically improves speed of the request, but it does not allow to use any filter (any other parameter included will be ignored).
+
+```shell
+curl -X GET https://your-url/v2/plates/count?_useEstimate=true -H  "accept: application/json" -H  "content-type: application/json" -H  "client-key: client-key"
+```
+
+The result will be the total of every document in the collection, regarding the `__STATE__`.
+
 #### Geospatial Queries
 
 On CRUD service, it is possible to filter data also for proximity, using MongoDB Geospatial Queries.

lib/CrudService.js

@@ -421,6 +421,11 @@ class CrudService {
     return this._mongoCollection.countDocuments(searchQuery, options)
   }
 
+  async estimatedDocumentCount(context) {
+    context.log.debug({}, 'estimatedDocumentCount operation requested')
+    return this._mongoCollection.estimatedDocumentCount()
+  }
+
   async deleteAll(context, query, _states) {
     const stateQuery = getStateQuery(_states)
     const isQueryValid = query && Object.keys(query).length > 0

lib/JSONSchemaGenerator.js

@@ -51,6 +51,7 @@ const {
   UPDATEDAT,
   CREATORID,
   CREATEDAT,
+  USE_ESTIMATE,
 } = require('./consts')
 const {
   stateCreateValidationSchema,
@@ -118,7 +119,7 @@ module.exports = class JSONSchemaGenerator {
       pathFieldsRawSchema
     )
     const deleteProperties = propertiesDeleteValidation(structuredClone(validationGetProperties))
-    const countAndQueryValidation = {
+    const mongoIdAndDeleteProperties = {
       [MONGOID]: { ...mongoIdTypeValidator[idType]() },
       ...structuredClone(deleteProperties),
     }
@@ -156,8 +157,16 @@ module.exports = class JSONSchemaGenerator {
     }
     this._propertiesPatchQueryValidation = deleteProperties
     this._propertiesFilterChangeStateMany = changeStateProperties
-    this._propertiesCountValidation = { ...countAndQueryValidation }
-    this._propertiesPatchManyQueryValidation = { ...countAndQueryValidation }
+    this._propertiesCountValidation = {
+      ...mongoIdAndDeleteProperties,
+      [USE_ESTIMATE]: {
+        type: 'boolean',
+        enum: [true, false],
+        description: 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        default: false,
+      },
+    }
+    this._propertiesPatchManyQueryValidation = { ...mongoIdAndDeleteProperties }
   }
 
   getSchemaDetail(operationName) {

lib/consts.js

@@ -60,6 +60,7 @@ module.exports = Object.freeze({
   STATE: '_st',
   MONGOID: '_id',
   RAW_PROJECTION: '_rawp',
+  USE_ESTIMATE: '_useEstimate',
 
   // Patch commands
   SETCMD: '$set',

lib/httpInterface.js

@@ -44,6 +44,7 @@ const {
   __STATE__,
   SCHEMA_CUSTOM_KEYWORDS,
   rawProjectionDictionary,
+  USE_ESTIMATE,
 } = require('./consts')
 
 const getAccept = require('./acceptHeaderParser')
@@ -692,10 +693,16 @@ async function handleCount(request) {
   const {
     [QUERY]: clientQueryString,
     [STATE]: state,
+    [USE_ESTIMATE]: useEstimate,
     ...otherParams
   } = query
+
   const { acl_rows } = headers
 
+  if (useEstimate) {
+    return this.crudService.estimatedDocumentCount(crudContext)
+  }
+
   const mongoQuery = resolveMongoQuery(this.queryParser, clientQueryString, acl_rows, otherParams, false)
 
   const stateArr = state.split(',')

tests/expectedSchemas/booksCountSchema.js

@@ -282,6 +282,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
       'signature.name': {
         'type': 'string',
       },

tests/expectedSchemas/booksNewCountSchema.js

@@ -312,6 +312,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
       'signature.name': {
         'type': 'string',
       },

tests/expectedSchemas/carsCountSchema.js

@@ -71,6 +71,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
     },
     'additionalProperties': false,
   },

tests/expectedSchemas/carsNewCountSchema.js

@@ -91,6 +91,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
     },
     'additionalProperties': false,
   },

tests/expectedSchemas/stationsCountSchema.js

@@ -112,6 +112,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
     },
     'additionalProperties': false,
   },

tests/expectedSchemas/stationsNewCountSchema.js

@@ -142,6 +142,15 @@ module.exports = {
         'type': 'string',
         'description': 'Additional raw stringified projection for MongoDB',
       },
+      '_useEstimate': {
+        'type': 'boolean',
+        'enum': [
+          true,
+          false,
+        ],
+        'description': 'If "true", returns the count of all documents in the collection based on the metadata of the collection. It works only there are no other query parameters.',
+        'default': false,
+      },
     },
     'additionalProperties': false,
   },

tests/httpInterface.countList.test.js

@@ -123,6 +123,20 @@ tap.test('HTTP GET /count', async t => {
       acl_rows: undefined,
       count: 0,
     },
+    {
+      name: 'query with _useEstimate parameter',
+      method: 'GET',
+      url: `${prefix}/count?_useEstimate=true`,
+      count: fixtures.length,
+      acl_rows: undefined,
+    },
+    {
+      name: 'query with _useEstimate parameter should ignore other query parameters',
+      method: 'GET',
+      url: `${prefix}/count?_useEstimate=true&_q=${JSON.stringify({ price: { $gt: Infinity } })}`,
+      count: fixtures.length,
+      acl_rows: undefined,
+    },
   ]
 
   t.plan(tests.length)