Skip to content

Commit 46392bc

Browse files
jeff-allen-mongojeff-allen-mongo
authored
(DOCS-14883): Omit custom data from user response (#145)
* (DOCS-14883): Omit custom data from user response * fix syntax highlighting * updates per copy review * updates per copy review * adjust table width * word change * add 'copyable false' * quick copy edit * update example copy and move to include
1 parent defca05 commit 46392bc

File tree

5 files changed

+222
-102
lines changed

5 files changed

+222
-102
lines changed

‎source/includes/fact-omit-custom-data-example-setup.rst

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Use the :dbcommand:`createUser` command to create a user named
2+
``accountAdmin01`` on the ``products`` database:
3+
4+
.. code-block:: javascript
5+
6+
db.getSiblingDB("products").runCommand( {
7+
createUser: "accountAdmin01",
8+
pwd: passwordPrompt(),
9+
customData: { employeeId: 12345 },
10+
roles: [ { role: 'readWrite', db: 'products' } ]
11+
} )
12+
13+
The user contains a ``customData`` field of ``{ employeeId: 12345 }``.

‎source/reference/command/usersInfo.txt

Lines changed: 74 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,12 @@ Definition
1919

2020
The :dbcommand:`usersInfo` command has the following form:
2121

22-
.. code-block:: javascript
22+
.. code-block:: none
2323

2424
{
2525
usersInfo: <various>,
2626
showCredentials: <Boolean>,
27+
showCustomData: <Boolean>,
2728
showPrivileges: <Boolean>,
2829
showAuthenticationRestrictions: <Boolean>,
2930
filter: <document>,
@@ -35,73 +36,68 @@ Definition
3536

3637
.. list-table::
3738
:header-rows: 1
38-
:widths: 20 20 80
39+
:widths: 20 25 80
3940

4041
* - Field
41-
4242
- Type
43-
4443
- Description
4544

4645
* - ``usersInfo``
47-
4846
- various
49-
5047
- The user(s) about whom to return information.
51-
48+
5249
The argument to ``usersInfo`` has multiple forms depending on the
5350
requested information. See :ref:`usersInfo-field-specification`.
54-
55-
56-
51+
5752
* - ``showCredentials``
58-
5953
- boolean
60-
61-
- Optional. Set the field to true to display the user's password hash. By default, this
62-
field is ``false``.
54+
- Optional. Set to ``true`` to display the user's password
55+
hash.
6356

57+
By default, this field is ``false``.
58+
59+
* - ``showCustomData``
60+
- boolean
61+
- Optional. Set to ``false`` to omit the user's ``customData``
62+
from the output.
6463

65-
64+
By default, this field is ``true``.
65+
66+
.. versionadded:: 5.2
67+
6668
* - ``showPrivileges``
67-
6869
- boolean
69-
70-
- Optional. Set the field to true to show the user's full set of privileges, including
71-
expanded information for the inherited roles. By default, this field
72-
is ``false``. If viewing all users, you cannot specify this field.
70+
- Optional. Set to ``true`` to show the user's full set
71+
of privileges, including expanded information for the
72+
inherited roles.
7373

74+
By default, this field is ``false``.
7475

75-
76+
If viewing all users, you cannot specify this field.
77+
7678
* - ``showAuthenticationRestrictions``
77-
7879
- boolean
79-
80-
- Optional. Set the field to true to show the user's authentication restrictions. By
81-
default, this field is ``false``. If viewing all users, you cannot specify
82-
this field.
80+
- Optional. Set to ``true`` to show the user's authentication
81+
restrictions.
8382

83+
By default, this field is ``false``.
8484

85-
86-
* - ``filter``
87-
85+
If viewing all users, you cannot specify this field.
86+
87+
* - ``filter``
8888
- document
89-
90-
- Optional. A document that specifies :pipeline:`$match` stage conditions to
91-
return information for users that match the filter conditions.
89+
- Optional. A document that specifies :pipeline:`$match` stage
90+
conditions to return information for users that match the
91+
filter conditions.
9292

9393
.. versionadded:: 4.0
94-
95-
96-
* - ``comment``
9794

95+
* - ``comment``
9896
- any
99-
10097
- .. include:: /includes/extracts/comment-content.rst
10198

10299
.. versionadded:: 4.4
103100

104-
105101
.. _usersInfo-field-specification:
106102

107103
``usersInfo: <various>``
@@ -294,3 +290,44 @@ When viewing all users, you can specify the ``showCredentials`` option
294290
but not the ``showPrivileges`` or the
295291
``showAuthenticationRestrictions`` options.
296292

293+
Omit Custom Data from Output
294+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
295+
296+
.. versionadded:: 5.2
297+
298+
To omit users' custom data from the :dbcommand:`usersInfo` output,
299+
set the ``showCustomData`` option to ``false``.
300+
301+
.. include:: /includes/fact-omit-custom-data-example-setup.rst
302+
303+
To retrieve the user but omit the custom data from the output, run
304+
:dbcommand:`usersInfo` with ``showCustomData`` set to ``false``:
305+
306+
.. code-block:: javascript
307+
:emphasize-lines: 3
308+
309+
db.getSiblingDB("products").runCommand ( {
310+
usersInfo: "accountAdmin01",
311+
showCustomData: false
312+
} )
313+
314+
Example output:
315+
316+
.. code-block:: javascript
317+
:copyable: false
318+
319+
{
320+
users: [
321+
{
322+
_id: 'products.accountAdmin01',
323+
userId: UUID("0955afc1-303c-4683-a029-8e17dd5501f4"),
324+
user: 'accountAdmin01',
325+
db: 'products',
326+
roles: [ { role: 'readWrite', db: 'products' } ],
327+
mechanisms: [ 'SCRAM-SHA-1', 'SCRAM-SHA-256' ]
328+
}
329+
],
330+
ok: 1
331+
}
332+
333+

‎source/reference/method/db.getUser.txt

Lines changed: 66 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,11 @@ Definition
2121

2222
The :method:`db.getUser()` method has the following parameters:
2323

24-
.. code-block:: javascript
24+
.. code-block:: none
2525

2626
db.getUser( "<username>", {
2727
showCredentials: <Boolean>,
28+
showCustomData: <Boolean>,
2829
showPrivileges: <Boolean>,
2930
showAuthenticationRestrictions: <Boolean>,
3031
filter: <document>
@@ -37,83 +38,69 @@ Definition
3738
:widths: 20 20 80
3839

3940
* - Parameter
40-
4141
- Type
42-
4342
- Description
4443

4544
* - ``username``
46-
4745
- string
48-
4946
- The name of the user for which to retrieve information.
50-
51-
52-
47+
5348
* - ``args``
54-
5549
- document
56-
5750
- Optional. A document specifying additional arguments.
58-
59-
60-
61-
6251

6352
The ``args`` document supports the following fields:
6453

65-
6654
.. list-table::
6755
:header-rows: 1
6856
:widths: 20 20 80
6957

7058
* - Field
71-
7259
- Type
73-
7460
- Description
7561

7662
* - ``showCredentials``
77-
7863
- boolean
79-
80-
- Optional. Set the field to true to display the user's password hash. By default, this
81-
field is ``false``.
64+
- Optional. Set to ``true`` to display the user's password
65+
hash.
8266

67+
By default, this field is ``false``.
68+
69+
* - ``showCustomData``
70+
- boolean
71+
- Optional. Set to ``false`` to omit the user's ``customData``
72+
from the output.
8373

84-
74+
By default, this field is ``true``.
75+
76+
.. versionadded:: 5.2
77+
8578
* - ``showPrivileges``
86-
8779
- boolean
88-
89-
- Optional. Set the field to true to show the user's full set of privileges, including
90-
expanded information for the inherited roles. By default, this field
91-
is ``false``. If viewing all users, you cannot specify this field.
80+
- Optional. Set to ``true`` to show the user's full set
81+
of privileges, including expanded information for the
82+
inherited roles.
9283

84+
By default, this field is ``false``.
9385

94-
86+
If viewing all users, you cannot specify this field.
87+
9588
* - ``showAuthenticationRestrictions``
96-
9789
- boolean
98-
99-
- Optional. Set the field to true to show the user's authentication restrictions. By
100-
default, this field is ``false``. If viewing all users, you cannot specify
101-
this field.
90+
- Optional. Set to ``true`` to show the user's
91+
authentication restrictions.
10292

103-
104-
93+
By default, this field is ``false``.
94+
95+
If viewing all users, you cannot specify this field.
96+
10597
* - ``filter``
106-
10798
- document
108-
109-
- Optional. A document that specifies :pipeline:`$match` stage conditions to
110-
return information for users that match the filter conditions.
99+
- Optional. A document that specifies :pipeline:`$match` stage
100+
conditions to return information for users that match the
101+
filter conditions.
111102

112103
.. versionadded:: 4.0
113-
114-
115-
116-
117104

118105
:method:`db.getUser()` wraps the :dbcommand:`usersInfo: \<username\> <usersInfo>` command.
119106

@@ -124,8 +111,8 @@ Required Access
124111

125112
.. include:: /includes/access-user-info.rst
126113

127-
Example
128-
-------
114+
Examples
115+
--------
129116

130117
The following operations return information about an example
131118
``appClient`` user in an ``accounts`` database:
@@ -148,3 +135,37 @@ Example output:
148135
roles: [],
149136
mechanisms: [ 'SCRAM-SHA-1', 'SCRAM-SHA-256' ]
150137
}
138+
139+
Omit Custom Data from Output
140+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141+
142+
.. versionadded:: 5.2
143+
144+
To omit a user's custom data from the :method:`db.getUser()` output,
145+
set the ``showCustomData`` option to ``false``.
146+
147+
.. include:: /includes/fact-omit-custom-data-example-setup.rst
148+
149+
To retrieve the user but omit the custom data from the output, run
150+
:method:`db.getUser()` with ``showCustomData`` set to ``false``:
151+
152+
.. code-block:: javascript
153+
154+
db.getSiblingDB("products").getUser(
155+
"accountAdmin01",
156+
{ showCustomData: false }
157+
)
158+
159+
Example output:
160+
161+
.. code-block:: javascript
162+
:copyable: false
163+
164+
{
165+
_id: 'products.accountAdmin01',
166+
userId: UUID("0955afc1-303c-4683-a029-8e17dd5501f4"),
167+
user: 'accountAdmin01',
168+
db: 'products',
169+
roles: [ { role: 'readWrite', db: 'products' } ],
170+
mechanisms: [ 'SCRAM-SHA-1', 'SCRAM-SHA-256' ]
171+
}

0 commit comments

Comments
 (0)