DOCS-14235 documents validateDBMetadata

source/reference/command/nav-diagnostic.txt

@@ -126,6 +126,11 @@ Diagnostic Commands
 
      - Internal command that scans for a collection's data and indexes for correctness.
 
+   * - :dbcommand:`validateDBMetadata`
+
+     - Checks that the stored metadata of a database/collection is valid 
+       within a particular API version.
+
    * - :dbcommand:`whatsmyuri`
 
      - Internal command that returns information on the current client.
@@ -161,4 +166,5 @@ Diagnostic Commands
    /reference/command/shardConnPoolStats
    /reference/command/top
    /reference/command/validate
+   /reference/command/validateDBMetadata
    /reference/command/whatsmyuri

source/reference/command/validateDBMetadata.txt

@@ -0,0 +1,264 @@
+==================
+validateDBMetadata
+==================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. versionadded:: 5.0
+
+.. dbcommand:: validateDBMetadata
+
+   The :dbcommand:`validateDBMetadata` command checks that the stored 
+   metadata of a database or a collection is valid within a particular 
+   API version.
+
+   :dbcommand:`validateDBMetadata` reports errors, but does not have the
+   capability to fix errors.
+
+Syntax
+------
+
+The command has the following syntax:
+
+.. code-block:: javascript
+
+   db.runCommand( { 
+      validateDBMetadata: 1,
+      apiParameters: {
+         version: <string>,
+         strict: <boolean>,
+         deprecationErrors: <boolean>
+      },
+      db: <string>,
+      collection: <string>,
+   } )
+
+Command Fields
+~~~~~~~~~~~~~~
+
+The command takes the following fields:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 10 50
+
+   * - Field
+     - Type
+     - Description
+
+   * - :ref:`apiParameters <api-params-document>` 
+     - document
+     - .. _api-params-document:
+
+       *All Fields are Required*.
+
+       - ``version`` (*string*)
+
+         The API Version to validate against. For now, ``"1"`` is the 
+         only version.
+
+       - ``strict`` (*boolean*)
+
+         If ``true``, :ref:`APIStrictError <api-strict-resp>` 
+         responses will be included in the output.
+
+       - ``deprecationErrors`` (*boolean*)
+
+         If ``true``, :ref:`APIDeprecationError <api-deprecation-resp>` 
+         responses will be included in the output.
+
+   * - ``db``
+     - string
+     - *Optional*. The name of the database to validate. If no database
+       is specified, all databases will be validated.
+
+   * - ``collection``
+     - string
+     - *Optional*. The name of the collection or view to validate. If no 
+       collection or view is specified, all collections in the database  
+       specified by ``db`` will be validated. If no database is 
+       specified, all collections in all databases will be validated.
+
+Behavior
+--------
+
+- Validate all collections in all databases, reporting 
+  :ref:`APIStrictError <api-strict-resp>` 
+  and :ref:`APIVersionError <api-vers-resp>` error responses.
+
+  .. code-block:: javascript
+
+     db.runCommand( { 
+       validateDBMetadata: 1, 
+       apiParameters: { 
+         version: "1", 
+         strict: true, 
+         deprecationErrors: true 
+       }, 
+     })
+
+- Validate all collections in ``inventory``: 
+
+  .. code-block:: javascript
+
+     db.runCommand( { 
+       validateDBMetadata: 1, 
+       apiParameters: { 
+         version: "1", 
+         strict: true, 
+         deprecationErrors: true 
+       }, 
+       db: "inventory",
+     })
+
+- Validate the ``sales`` collection in the ``inventory`` database:
+
+  .. code-block:: javascript
+
+     db.runCommand( { 
+       validateDBMetadata: 1, 
+       apiParameters: { 
+         version: "1", 
+         strict: true, 
+         deprecationErrors: true 
+       }, 
+       db: "inventory",
+       collection: "sales",
+     })
+
+- Validate any and all ``sales`` collections across all databases:
+
+  .. code-block:: javascript
+
+     db.runCommand( { 
+       validateDBMetadata: 1, 
+       apiParameters: { 
+         version: "1", 
+         strict: true, 
+         deprecationErrors: true 
+       }, 
+       collection: "sales",
+     })
+
+.. note:: 
+
+   Your user must have the :authaction:`validate` privilege action on 
+   all collections you want to validate.
+
+.. _validateDBMetadata-output:
+
+Output
+------
+
+.. code-block:: javascript
+
+   {
+      apiVersionErrors: [
+        {
+          ns: <string>,
+          code: <int>,
+          codeName: <string>,
+          errmsg: <string>
+        }
+      ],
+      ok: <int>,
+      hasMoreErrors: <boolean>,
+   }
+
+
+.. data:: validateDBMetadata.apiVersionErrors
+
+   Array of documents describing API Version errors.
+
+.. data:: validateDBMetadata.apiVersionErrors[n].ns
+
+   Namespace of the collection or view with error.
+
+.. data:: validateDBMetadata.apiVersionErrors[n].code
+
+   Numeric error code.
+
+.. data:: validateDBMetadata.apiVersionErrors[n].codeName
+
+   Name of the error code.
+
+.. data:: validateDBMetadata.apiVersionErrors[n].errmsg
+
+   String describing the error.
+
+.. data:: validateDBMetadata.ok
+
+   If the command fails, ``ok`` is set to ``1``. Otherwise, ``ok`` is 
+   set to ``0``. :data:`validateDBMetadata.ok` may have a value of 
+   ``0`` and still report validation errors.
+
+.. data:: validateDBMetadata.hasMoreErrors
+
+   If ``true``, there are additional errors.
+
+Example
+-------
+
+Use the sample MQL (MongoDB Query Language) code to create a ``sales``
+collection in :binary:`~bin.mongosh`: 
+
+.. code-block:: javascript
+
+   db.sales.insertMany([
+       { "_id" : 1, "item" : "shoes", "price" : 10, "quantity" : 2, "date" : ISODate("2021-01-01T08:00:00Z") },
+       { "_id" : 2, "item" : "hat", "price" : 20, "quantity" : 1, "date" : ISODate("2021-02-03T09:00:00Z") },
+       { "_id" : 3, "item" : "gloves", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-03T09:05:00Z") },
+       { "_id" : 4, "item" : "pants", "price" : 10, "quantity" : 10, "date" : ISODate("2021-02-15T08:00:00Z") },
+       { "_id" : 5, "item" : "socks", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T09:05:00Z") },
+       { "_id" : 6, "item" : "shirt", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-15T12:05:10Z") },
+       { "_id" : 7, "item" : "belt", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T14:12:12Z") },
+       { "_id" : 8, "item" : "blouse", "price" : 10, "quantity" : 5, "date" : ISODate("2021-03-16T20:20:13Z") }
+   ])
+
+Add a :ref:`text index <index-feature-text>` on the ``item`` field.   
+
+.. code-block:: javascript
+
+   db.sales.createIndex( { item: "text" } )
+
+Validate the ``sales`` collection for strict compliance with API 
+version 1 and include ``deprecationErrors`` in the output.
+
+.. code-block:: javascript
+
+     db.runCommand( { 
+       validateDBMetadata: 1, 
+       apiParameters: { 
+         version: "1", 
+         strict: true, 
+         deprecationErrors: true 
+       }, 
+       collection: "sales",
+     })
+
+:dbcommand:`validateDBMetadata` reports an ``APIStrictError`` on the 
+``item_text`` index. 
+
+.. code-block:: javascript
+
+   {
+      apiVersionErrors: [
+        {
+          ns: 'test.sales',
+          code: 323,
+          codeName: 'APIStrictError',
+          errmsg: 'The index with name item_text is not allowed in API version 1.'
+        }
+      ],
+      ok: 1,
+      hasMoreErrors: false,
+   }

source/reference/privilege-actions.txt

@@ -836,8 +836,9 @@ Diagnostic Actions
 
 .. authaction:: validate
 
-   User can perform the :dbcommand:`validate` command. Apply this action
-   to database or collection resources.
+   User can perform the :dbcommand:`validate` and 
+   :dbcommand:`validateDBMetadata` commands. Apply this action to 
+   database or collection resources.
 
 .. authaction:: top
 

source/release-notes/5.0.txt

@@ -923,6 +923,13 @@ ends with the :dbcommand:`killSessions` command, if the session times
 out, or if the client has exhausted the cursor. 
 See :ref:`read-operations-cursors`.
 
+New ``validateDBMetadata`` Command
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MongoDB 5.0 adds the :dbcommand:`validateDBMetadata` command. The 
+:dbcommand:`validateDBMetadata` command checks that the stored metadata 
+of a database or a collection is valid within a particular API version.
+
 .. _5.0-rel-notes-platforms:
 
 Platform Support