Skip to content

Commit f4cccad

Browse files
sarah-olson-mongodbsarah-olson-mongodb
authored
DOCS-14522: Updates to the listIndexes page (#771) (#875)
* DOCS-14522: Update listIndexes based on jira request. * DOCS-14522: Fixing my markup errors. * DOCS-14522: Very minor additional edits * DOCS-14522: Incorporating edits * DOCS-14522: Typo * DOCS-14522: Update codeblock formatting * DOCS-14522: External review feedback * DOCS-14522: Change output section to table. * DOCS-14522: Update Output section * DOCS-14522: Minor format edits * DOCS-14522: Minor format edit * DOCS-14522: Edit to table. * DOCS-14522: Incorporate edits, add examples section. * Review edits : * DOCS-14522: minor edits * DOCS-14522: Incorporate additional feedback. * DOCS-14522: Understanding markup options * DOCS-14522: Minor feedback edits * DOCS-14522: Remove some line breaks * DOCS-14522: Minor edits and format improvements * DOCS-14522: Fix spacing issue in table * DOCS-14522: Fix table spacing markup * DOCS-14522: Fix io-code-block spacing * DOCS-14522: Troubleshooting some issue * DOCS-14522: Troubleshooting some issue * DOCS-14522: Troubleshooting some issue * DOCS-14522: Troubleshooting some issue * DOCS:14522: Troubleshooting some issue * DOCS-14522: Troubleshooting some issue * DOCS-14522: Troubleshooting some issue * DOCS-14522: Add review feedback * DOCS-14522: Testing table markup * DOCS-14522: Review feedback * DOCS-14522: Fix example format Co-authored-by: Sarah Olson <[email protected]> Co-authored-by: Sarah Olson <[email protected]> "DOCS-14522:Fix merge conflicts for v4.4"
1 parent 3051523 commit f4cccad

File tree

3 files changed

+179
-53
lines changed

3 files changed

+179
-53
lines changed

‎source/includes/extracts-4.2-changes.yaml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -515,10 +515,9 @@ content: |
515515
ref: 4.2-changes-disconnect
516516
content: |
517517
518-
Starting in MongoDB 4.2, if the client that issued the |operation|
519-
disconnects before the operation completes, MongoDB marks
520-
the |operation| for termination (i.e. :dbcommand:`killOp` on the
521-
operation).
518+
Starting in MongoDB 4.2, if the client that issued |operation|
519+
disconnects before the operation completes, MongoDB marks |operation|
520+
for termination using :dbcommand:`killOp`.
522521
---
523522
ref: 4.2-changes-map-reduce-deprecation
524523
content: |

‎source/includes/extracts-4.4-changes.yaml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -493,9 +493,9 @@ content: |
493493
is in another state, such as :replstate:`STARTUP2`, the
494494
operation errors.
495495
496-
In previous versions, the operations can also be run when the member
497-
is in :replstate:`STARTUP2`. However, the operations wait
498-
until the member transitions to :replstate:`RECOVERING`.
496+
In previous versions, the operations also run when the member
497+
is in :replstate:`STARTUP2`. The operations wait until the member
498+
transitioned to :replstate:`RECOVERING`.
499499
500500
---
501501
ref: 4.4-changes-mapreduce-ignore-verbose

‎source/reference/command/listIndexes.txt‎

Lines changed: 173 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -15,54 +15,60 @@ Definition
1515

1616
.. dbcommand:: listIndexes
1717

18-
Returns information about the indexes on the specified collection,
19-
including :doc:`hidden indexes </core/index-hidden>`. Specifically,
20-
the command returns a document that contains information with which
21-
to create a cursor to the index information. Index information
22-
includes the keys and options used to create the index. The
18+
Returns information about the indexes on the specified collection. Returned
19+
index information includes the keys and options used to create the index, as
20+
well as :doc:`hidden indexes </core/index-hidden>`. You can optionally set
21+
the batch size for the first batch of results. The
2322
:binary:`~bin.mongo` shell provides the
2423
:method:`db.collection.getIndexes()` helper.
2524

26-
The command has the following form:
25+
Syntax
26+
------
2727

28-
.. code-block:: javascript
28+
The command has the following form:
2929

30-
{ "listIndexes": "<collection-name>" }
30+
.. code-block:: javascript
31+
32+
db.runCommand (
33+
{
34+
listIndexes: "<collection-name>",
35+
cursor: { batchSize: <int> },
36+
comment: <any>
37+
}
38+
)
3139

40+
Command Fields
41+
~~~~~~~~~~~~~~
3242

33-
.. list-table::
34-
:header-rows: 1
35-
:widths: 20 20 80
36-
37-
* - Field
38-
39-
- Type
40-
41-
- Description
42-
43-
* - ``listIndexes``
43+
``listIndexes`` takes the following fields:
44+
45+
.. list-table::
46+
:header-rows: 1
47+
:widths: 20 20 80
4448

45-
- string
49+
* - Field
50+
- Type
51+
- Description
4652

47-
- The name of the collection.
48-
49-
* - ``comment``
50-
51-
- any
52-
53-
- .. include:: /includes/extracts/comment-content.rst
54-
55-
.. versionadded:: 4.4
56-
57-
53+
* - ``listIndexes``
54+
- string
55+
- The name of the collection.
56+
57+
* - ``cursor.batchSize``
58+
- integer
59+
- Optional. Specifies the cursor batch size.
60+
61+
* - ``comment``
62+
- any
63+
- .. include:: /includes/extracts/comment-content.rst
64+
.. versionadded:: 4.4
5865

5966
Required Access
6067
---------------
6168

62-
To run :dbcommand:`listIndexes` when access control is enforced, users
63-
must have privileges to :authaction:`listIndexes`. The built-in role
64-
:authrole:`read` provides the required privileges to run
65-
:dbcommand:`listIndexes` for the collections in a database.
69+
If access control is enforced, the built-in :authrole:`read` role provides the
70+
required privileges to run :dbcommand:`listIndexes` for the collections in a
71+
database.
6672

6773
Behavior
6874
--------
@@ -86,17 +92,138 @@ Output
8692

8793
.. data:: listIndexes.cursor
8894

89-
A document that contains information with which to create a cursor
90-
to index information. The cursor information includes the cursor id,
91-
the full namespace for the command, as well as the first batch of
92-
results. Index information includes the keys and options used to
93-
create the index. The index option ``hidden``, available starting in
94-
MongoDB 4.4, is only present if the value is ``true``.
95-
96-
For information on the keys and index options, see
97-
:method:`db.collection.createIndex()`.
95+
A result set returned in the batch size specified by your cursor.
96+
Each document in the batch output contains the following fields:
97+
98+
.. list-table::
99+
:header-rows: 1
100+
:widths: 15 15 30
101+
102+
* - Field
103+
- Type
104+
- Description
105+
106+
* - id
107+
- integer
108+
- A 64-bit integer. If zero, there are no more batches of information.
109+
If non-zero, a cursor ID, usable in a ``getMore`` command to get the
110+
next batch of index information.
111+
112+
* - ns
113+
- string
114+
- The database and collection name in the following format:
115+
``<database-name>.<collection-name>``
116+
117+
* - firstBatch
118+
- document
119+
- Index information includes the keys and options used to create the
120+
index. The index option hidden, available starting in MongoDB 4.4,
121+
is only present if the value is true.
122+
123+
Use :dbcommand:`getMore` to retrieve additional results as needed.
124+
98125

99126
.. data:: listIndexes.ok
100127

101-
The return value for the command. A value of ``1`` indicates
102-
success.
128+
The return value for the command. A value of ``1`` indicates success.
129+
130+
Examples
131+
--------
132+
133+
List Database Indexes
134+
~~~~~~~~~~~~~~~~~~~~~
135+
136+
This example lists indexes for the ``contacts`` collection without specifying the
137+
cursor batch size.
138+
139+
.. io-code-block::
140+
:copyable: true
141+
142+
.. input::
143+
:language: json
144+
:linenos:
145+
146+
db.runCommand (
147+
{
148+
listIndexes: "contacts"
149+
}
150+
)
151+
152+
.. output::
153+
:linenos:
154+
155+
{
156+
cursor: {
157+
id: Long("0"),
158+
ns: 'test.contacts',
159+
firstBatch: [
160+
{ v: 2, key: { _id: 1 }, name: '_id_', ns: 'test.contacts' },
161+
{ v: 2, key: { a: 1 }, name: 'a_1', ns: 'test.contacts' }
162+
]
163+
},
164+
ok: 1
165+
}
166+
167+
Specify Result Batch Size
168+
~~~~~~~~~~~~~~~~~~~~~~~~~
169+
170+
This example lists indexes for the ``contacts`` collection, and specifies a cursor
171+
batch size of 1.
172+
173+
.. io-code-block::
174+
:copyable: true
175+
176+
.. input::
177+
:language: json
178+
:linenos:
179+
180+
db.runCommand (
181+
{
182+
listIndexes: "contacts", cursor: { batchSize: 1 }
183+
}
184+
)
185+
186+
.. output::
187+
:linenos:
188+
189+
{
190+
cursor: {
191+
id: Long("4809221676960028307"),
192+
ns: 'test.contacts',
193+
firstBatch: [ { v: 2, key: { _id: 1 }, name: '_id_', ns: 'test.contacts' } ]
194+
},
195+
ok: 1
196+
}
197+
198+
Retrieve Additional Results
199+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
200+
201+
This example uses ``getMore`` to retrieve additional result batches from the
202+
``contacts`` collection.
203+
204+
.. io-code-block::
205+
:copyable: true
206+
207+
.. input::
208+
:language: json
209+
:linenos:
210+
211+
db.runCommand(
212+
{
213+
getMore: Long("4809221676960028307"), collection: "contacts"
214+
}
215+
)
216+
217+
.. output::
218+
:linenos:
219+
220+
{
221+
cursor: {
222+
nextBatch: [ { v: 2, key: { a: 1 }, name: 'a_1', ns: 'test.contacts' } ],
223+
id: Long("0"),
224+
ns: 'test.contacts'
225+
},
226+
ok: 1
227+
}
228+
229+

0 commit comments

Comments
 (0)