From 689fb8a5b526b492fcd5ba516d4f4d6f0058aa89 Mon Sep 17 00:00:00 2001 From: Joseph Dougherty Date: Thu, 5 Aug 2021 14:52:20 -0400 Subject: [PATCH] DOCS-14235 documents validateDBMetadata --- source/reference/command/nav-diagnostic.txt | 6 + .../reference/command/validateDBMetadata.txt | 264 ++++++++++++++++++ source/reference/privilege-actions.txt | 5 +- source/release-notes/5.0.txt | 7 + 4 files changed, 280 insertions(+), 2 deletions(-) create mode 100644 source/reference/command/validateDBMetadata.txt diff --git a/source/reference/command/nav-diagnostic.txt b/source/reference/command/nav-diagnostic.txt index a9605ee70b1..d35ac1f9dae 100644 --- a/source/reference/command/nav-diagnostic.txt +++ b/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 diff --git a/source/reference/command/validateDBMetadata.txt b/source/reference/command/validateDBMetadata.txt new file mode 100644 index 00000000000..e31f5189289 --- /dev/null +++ b/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: , + strict: , + deprecationErrors: + }, + db: , + collection: , + } ) + +Command Fields +~~~~~~~~~~~~~~ + +The command takes the following fields: + +.. list-table:: + :header-rows: 1 + :widths: 10 10 50 + + * - Field + - Type + - Description + + * - :ref:`apiParameters ` + - 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 ` + responses will be included in the output. + + - ``deprecationErrors`` (*boolean*) + + If ``true``, :ref:`APIDeprecationError ` + 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 ` + and :ref:`APIVersionError ` 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: , + code: , + codeName: , + errmsg: + } + ], + ok: , + hasMoreErrors: , + } + + +.. 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 ` 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, + } \ No newline at end of file diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt index 6f0f3c867ff..b735337f45d 100644 --- a/source/reference/privilege-actions.txt +++ b/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 diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 68cdb068953..1d5dfb20cae 100644 --- a/source/release-notes/5.0.txt +++ b/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