Skip to content

Commit 49d8e35

Browse files
jmd-mongojmd-mongo
authored
DOCS-14235 documents validateDBMetadata (#284)
1 parent c311900 commit 49d8e35

File tree

4 files changed

+280
-2
lines changed

4 files changed

+280
-2
lines changed

‎source/reference/command/nav-diagnostic.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,11 @@ Diagnostic Commands
126126

127127
- Internal command that scans for a collection's data and indexes for correctness.
128128

129+
* - :dbcommand:`validateDBMetadata`
130+
131+
- Checks that the stored metadata of a database/collection is valid
132+
within a particular API version.
133+
129134
* - :dbcommand:`whatsmyuri`
130135

131136
- Internal command that returns information on the current client.
@@ -161,4 +166,5 @@ Diagnostic Commands
161166
/reference/command/shardConnPoolStats
162167
/reference/command/top
163168
/reference/command/validate
169+
/reference/command/validateDBMetadata
164170
/reference/command/whatsmyuri

‎source/reference/command/validateDBMetadata.txt

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
==================
2+
validateDBMetadata
3+
==================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. versionadded:: 5.0
17+
18+
.. dbcommand:: validateDBMetadata
19+
20+
The :dbcommand:`validateDBMetadata` command checks that the stored
21+
metadata of a database or a collection is valid within a particular
22+
API version.
23+
24+
:dbcommand:`validateDBMetadata` reports errors, but does not have the
25+
capability to fix errors.
26+
27+
Syntax
28+
------
29+
30+
The command has the following syntax:
31+
32+
.. code-block:: javascript
33+
34+
db.runCommand( {
35+
validateDBMetadata: 1,
36+
apiParameters: {
37+
version: <string>,
38+
strict: <boolean>,
39+
deprecationErrors: <boolean>
40+
},
41+
db: <string>,
42+
collection: <string>,
43+
} )
44+
45+
Command Fields
46+
~~~~~~~~~~~~~~
47+
48+
The command takes the following fields:
49+
50+
.. list-table::
51+
:header-rows: 1
52+
:widths: 10 10 50
53+
54+
* - Field
55+
- Type
56+
- Description
57+
58+
* - :ref:`apiParameters <api-params-document>`
59+
- document
60+
- .. _api-params-document:
61+
62+
*All Fields are Required*.
63+
64+
- ``version`` (*string*)
65+
66+
The API Version to validate against. For now, ``"1"`` is the
67+
only version.
68+
69+
- ``strict`` (*boolean*)
70+
71+
If ``true``, :ref:`APIStrictError <api-strict-resp>`
72+
responses will be included in the output.
73+
74+
- ``deprecationErrors`` (*boolean*)
75+
76+
If ``true``, :ref:`APIDeprecationError <api-deprecation-resp>`
77+
responses will be included in the output.
78+
79+
* - ``db``
80+
- string
81+
- *Optional*. The name of the database to validate. If no database
82+
is specified, all databases will be validated.
83+
84+
* - ``collection``
85+
- string
86+
- *Optional*. The name of the collection or view to validate. If no
87+
collection or view is specified, all collections in the database
88+
specified by ``db`` will be validated. If no database is
89+
specified, all collections in all databases will be validated.
90+
91+
Behavior
92+
--------
93+
94+
- Validate all collections in all databases, reporting
95+
:ref:`APIStrictError <api-strict-resp>`
96+
and :ref:`APIVersionError <api-vers-resp>` error responses.
97+
98+
.. code-block:: javascript
99+
100+
db.runCommand( {
101+
validateDBMetadata: 1,
102+
apiParameters: {
103+
version: "1",
104+
strict: true,
105+
deprecationErrors: true
106+
},
107+
})
108+
109+
- Validate all collections in ``inventory``:
110+
111+
.. code-block:: javascript
112+
113+
db.runCommand( {
114+
validateDBMetadata: 1,
115+
apiParameters: {
116+
version: "1",
117+
strict: true,
118+
deprecationErrors: true
119+
},
120+
db: "inventory",
121+
})
122+
123+
- Validate the ``sales`` collection in the ``inventory`` database:
124+
125+
.. code-block:: javascript
126+
127+
db.runCommand( {
128+
validateDBMetadata: 1,
129+
apiParameters: {
130+
version: "1",
131+
strict: true,
132+
deprecationErrors: true
133+
},
134+
db: "inventory",
135+
collection: "sales",
136+
})
137+
138+
- Validate any and all ``sales`` collections across all databases:
139+
140+
.. code-block:: javascript
141+
142+
db.runCommand( {
143+
validateDBMetadata: 1,
144+
apiParameters: {
145+
version: "1",
146+
strict: true,
147+
deprecationErrors: true
148+
},
149+
collection: "sales",
150+
})
151+
152+
.. note::
153+
154+
Your user must have the :authaction:`validate` privilege action on
155+
all collections you want to validate.
156+
157+
.. _validateDBMetadata-output:
158+
159+
Output
160+
------
161+
162+
.. code-block:: javascript
163+
164+
{
165+
apiVersionErrors: [
166+
{
167+
ns: <string>,
168+
code: <int>,
169+
codeName: <string>,
170+
errmsg: <string>
171+
}
172+
],
173+
ok: <int>,
174+
hasMoreErrors: <boolean>,
175+
}
176+
177+
178+
.. data:: validateDBMetadata.apiVersionErrors
179+
180+
Array of documents describing API Version errors.
181+
182+
.. data:: validateDBMetadata.apiVersionErrors[n].ns
183+
184+
Namespace of the collection or view with error.
185+
186+
.. data:: validateDBMetadata.apiVersionErrors[n].code
187+
188+
Numeric error code.
189+
190+
.. data:: validateDBMetadata.apiVersionErrors[n].codeName
191+
192+
Name of the error code.
193+
194+
.. data:: validateDBMetadata.apiVersionErrors[n].errmsg
195+
196+
String describing the error.
197+
198+
.. data:: validateDBMetadata.ok
199+
200+
If the command fails, ``ok`` is set to ``1``. Otherwise, ``ok`` is
201+
set to ``0``. :data:`validateDBMetadata.ok` may have a value of
202+
``0`` and still report validation errors.
203+
204+
.. data:: validateDBMetadata.hasMoreErrors
205+
206+
If ``true``, there are additional errors.
207+
208+
Example
209+
-------
210+
211+
Use the sample MQL (MongoDB Query Language) code to create a ``sales``
212+
collection in :binary:`~bin.mongosh`:
213+
214+
.. code-block:: javascript
215+
216+
db.sales.insertMany([
217+
{ "_id" : 1, "item" : "shoes", "price" : 10, "quantity" : 2, "date" : ISODate("2021-01-01T08:00:00Z") },
218+
{ "_id" : 2, "item" : "hat", "price" : 20, "quantity" : 1, "date" : ISODate("2021-02-03T09:00:00Z") },
219+
{ "_id" : 3, "item" : "gloves", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-03T09:05:00Z") },
220+
{ "_id" : 4, "item" : "pants", "price" : 10, "quantity" : 10, "date" : ISODate("2021-02-15T08:00:00Z") },
221+
{ "_id" : 5, "item" : "socks", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T09:05:00Z") },
222+
{ "_id" : 6, "item" : "shirt", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-15T12:05:10Z") },
223+
{ "_id" : 7, "item" : "belt", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T14:12:12Z") },
224+
{ "_id" : 8, "item" : "blouse", "price" : 10, "quantity" : 5, "date" : ISODate("2021-03-16T20:20:13Z") }
225+
])
226+
227+
Add a :ref:`text index <index-feature-text>` on the ``item`` field.
228+
229+
.. code-block:: javascript
230+
231+
db.sales.createIndex( { item: "text" } )
232+
233+
Validate the ``sales`` collection for strict compliance with API
234+
version 1 and include ``deprecationErrors`` in the output.
235+
236+
.. code-block:: javascript
237+
238+
db.runCommand( {
239+
validateDBMetadata: 1,
240+
apiParameters: {
241+
version: "1",
242+
strict: true,
243+
deprecationErrors: true
244+
},
245+
collection: "sales",
246+
})
247+
248+
:dbcommand:`validateDBMetadata` reports an ``APIStrictError`` on the
249+
``item_text`` index.
250+
251+
.. code-block:: javascript
252+
253+
{
254+
apiVersionErrors: [
255+
{
256+
ns: 'test.sales',
257+
code: 323,
258+
codeName: 'APIStrictError',
259+
errmsg: 'The index with name item_text is not allowed in API version 1.'
260+
}
261+
],
262+
ok: 1,
263+
hasMoreErrors: false,
264+
}

‎source/reference/privilege-actions.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -848,8 +848,9 @@ Diagnostic Actions
848848

849849
.. authaction:: validate
850850

851-
User can perform the :dbcommand:`validate` command. Apply this action
852-
to database or collection resources.
851+
User can perform the :dbcommand:`validate` and
852+
:dbcommand:`validateDBMetadata` commands. Apply this action to
853+
database or collection resources.
853854

854855
.. authaction:: top
855856

‎source/release-notes/5.0.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1062,6 +1062,13 @@ ends with the :dbcommand:`killSessions` command, if the session times
10621062
out, or if the client has exhausted the cursor.
10631063
See :ref:`read-operations-cursors`.
10641064

1065+
New ``validateDBMetadata`` Command
1066+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1067+
1068+
MongoDB 5.0 adds the :dbcommand:`validateDBMetadata` command. The
1069+
:dbcommand:`validateDBMetadata` command checks that the stored metadata
1070+
of a database or a collection is valid within a particular API version.
1071+
10651072
.. _5.0-rel-notes-platforms:
10661073

10671074
Platform Support

0 commit comments

Comments
 (0)