Skip to content

Commit 3f77fc2

Browse files
mcmorisimcmorisi
committed
DOCSP-45004: Run Command (#320)
(cherry picked from commit e4bcadc)
1 parent 3e27bfc commit 3f77fc2

File tree

4 files changed

+294
-0
lines changed

4 files changed

+294
-0
lines changed

‎snooty.toml

+1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ toc_landing_pages = [
77
"/fundamentals",
88
"/fundamentals/serialization",
99
"/upgrade",
10+
"/fundamentals/database-collection"
1011
]
1112

1213
intersphinx = [

‎source/fundamentals/database-collection.txt

+3
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ Databases and Collections
1717
:depth: 2
1818
:class: singlecol
1919

20+
.. toctree::
21+
/fundamentals/databases-collections/run-command
22+
2023
Overview
2124
--------
2225

‎source/fundamentals/databases-collections/run-command.txt

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
.. _csharp-run-command:
2+
3+
======================
4+
Run a Database Command
5+
======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: administration, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to
24+
run a database command. You can use database commands to perform a
25+
variety of administrative and diagnostic tasks, such as fetching server
26+
statistics, initializing a replica set, or running an aggregation pipeline.
27+
28+
.. important:: Prefer Driver Methods to Database Commands
29+
30+
The driver provides wrapper methods for many database commands.
31+
If possible, we recommend using these methods instead of executing
32+
database commands.
33+
34+
To perform administrative tasks, use the :mongosh:`MongoDB Shell </>`
35+
instead of the {+driver-short+}. The shell provides helper methods
36+
that might not be available in the driver.
37+
38+
If there are no available helpers in the driver or the shell, you
39+
can use the ``db.runCommand()`` shell method or the driver's
40+
``RunCommand()`` and ``RunCommandAsync()`` methods, which are described in this
41+
guide.
42+
43+
Sample Data
44+
~~~~~~~~~~~
45+
46+
The examples in this guide use the ``sample_restaurants.restaurants`` collection
47+
from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
48+
free MongoDB Atlas cluster and load the sample datasets, see the :ref:`<csharp-quickstart>`.
49+
50+
51+
Execute a Command
52+
-----------------
53+
54+
To run a database command, create a ``BsonDocument`` object that specifies
55+
the command and pass it as a parameter to the ``RunCommand()`` or ``RunCommandAsync()``
56+
method. You can specify the type returned by these methods by specifying the type parameter.
57+
You can use the ``BsonDocument`` type to return the command response, or you can specify your
58+
own strongly typed class to deserialize the command response.
59+
60+
The following example runs the ``hello`` command on a database, which returns information
61+
about the server. Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous`
62+
tab to see the corresponding code.
63+
64+
.. tabs::
65+
66+
.. tab:: Asynchronous
67+
:tabid: run-command-async
68+
69+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
70+
:language: csharp
71+
:dedent:
72+
:start-after: start-hello-async
73+
:end-before: end-hello-async
74+
75+
.. tab:: Synchronous
76+
:tabid: distinct-sync
77+
78+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
79+
:language: csharp
80+
:dedent:
81+
:start-after: start-hello
82+
:end-before: end-hello
83+
84+
.. tip::
85+
86+
To view a full list of database commands and their corresponding
87+
parameters, see :manual:`Database Commands </reference/command/>` in
88+
the {+mdb-server+} manual.
89+
90+
.. _csharp-command-read-pref:
91+
92+
Set a Read Preference
93+
----------------------
94+
95+
The ``RunCommand()`` method does not inherit the read preference you might
96+
have set on your ``MongoDatabase`` instance. By default, ``RunCommand()``
97+
uses the ``primary`` read preference.
98+
99+
You can set a read preference for the command execution by passing a
100+
``ReadPreference`` instance as a parameter to ``RunCommand()``, as
101+
shown in the following example. Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous`
102+
tab to see the corresponding code.
103+
104+
.. tabs::
105+
106+
.. tab:: Asynchronous
107+
:tabid: run-command-async
108+
109+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
110+
:language: csharp
111+
:dedent:
112+
:start-after: start-read-pref-async
113+
:end-before: end-read-pref-async
114+
115+
.. tab:: Synchronous
116+
:tabid: distinct-sync
117+
118+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
119+
:language: csharp
120+
:dedent:
121+
:start-after: start-read-pref
122+
:end-before: end-read-pref
123+
124+
.. tip::
125+
126+
To learn more about read preference options, see :manual:`Read
127+
Preference </core/read-preference/>` in the {+mdb-server+} manual.
128+
129+
.. _csharp-command-response:
130+
131+
Response
132+
--------
133+
134+
The raw command response document returned by the ``RunCommand()`` method contains the
135+
following fields:
136+
137+
.. list-table::
138+
:header-rows: 1
139+
:widths: 30 70
140+
141+
* - Field
142+
- Description
143+
144+
* - ``<command result>``
145+
- Fields specific to the database command. For example,
146+
the ``hello`` command returns the ``topologyVersion`` field.
147+
148+
* - ``ok``
149+
- Indicates whether the command has succeeded (``1.0``) or failed (``0.0``). The
150+
driver raises a ``MongoCommandException`` if the ``ok``
151+
value is ``0.0``.
152+
153+
* - ``$clusterTime``
154+
- A document that contains the signed cluster time. Cluster time is a
155+
logical time used for the ordering of operations. This field only
156+
applies to commands run on replica sets or sharded clusters.
157+
158+
* - ``operationTime``
159+
- The logical time of the operation execution. This field only
160+
applies to commands run on replica sets or sharded clusters.
161+
162+
.. tip::
163+
164+
To learn more about logical time, see the Wikipedia entry on
165+
the :wikipedia:`logical clock <w/index.php?title=Logical_clock&oldid=1072010149>`.
166+
167+
Example
168+
~~~~~~~
169+
170+
The following example runs the ``dbStats`` command to retrieve
171+
storage statistics for the ``sample_restaurants`` database, then prints the
172+
command results by using the ``ToJson()`` method on the returned ``BsonDocument`` object.
173+
Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to see the corresponding
174+
code.
175+
176+
.. tabs::
177+
178+
.. tab:: Asynchronous
179+
:tabid: run-command-async
180+
181+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
182+
:language: csharp
183+
:dedent:
184+
:start-after: start-print-command-async
185+
:end-before: end-print-command-async
186+
187+
.. tab:: Synchronous
188+
:tabid: distinct-sync
189+
190+
.. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs
191+
:language: csharp
192+
:dedent:
193+
:start-after: start-print-command
194+
:end-before: end-print-command
195+
196+
The output of this command includes information about the data stored in
197+
the database, as shown in the result returned by the previous example:
198+
199+
.. code-block:: none
200+
:copyable: false
201+
202+
{ "db" : "sample_restaurants", "collections" : 2, "views" : 0, "objects" :
203+
NumberLong(25438), "avgObjSize" : 548.95172576460413, "dataSize" : NumberLong(13964234),
204+
"storageSize" : NumberLong(8056832), "totalFreeStorageSize" : NumberLong(0),
205+
"numExtents" : NumberLong(0), "indexes" : 2, "indexSize" : NumberLong(1044480),
206+
"indexFreeStorageSize" : NumberLong(0), "fileSize" : NumberLong(0), "nsSizeMB" : 0, "ok" : 1 }
207+
208+
209+
Additional Information
210+
----------------------
211+
212+
For more information about the concepts in this guide, see the following
213+
documentation in the {+mdb-server+} manual:
214+
215+
- :manual:`db.runCommand() </reference/method/db.runCommand/>`
216+
- :manual:`Database Commands </reference/command/>`
217+
- :manual:`hello Command </reference/command/hello/>`
218+
- :manual:`dbStats Command </reference/command/dbStats/>`
219+
220+
API Documentation
221+
~~~~~~~~~~~~~~~~~
222+
223+
To learn more about any of the methods or types discussed in this
224+
guide, see the following API documentation:
225+
226+
- `RunCommand() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.RunCommand.html>`_
227+
- `RunCommandAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.RunCommandAsync.html>`_
228+
- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`_

‎source/includes/fundamentals/code-examples/databases-collections/RunCommand.cs

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
using MongoDB.Bson;
2+
using MongoDB.Driver;
3+
4+
public class RunCommand
5+
{
6+
// Replace with your connection string
7+
private const string MongoConnectionString = "<connection string URI>";
8+
9+
public static void Main(string[] args)
10+
{
11+
var mongoClient = new MongoClient(MongoConnectionString);
12+
var database = mongoClient.GetDatabase("sample_restaurants");
13+
var collection = database.GetCollection<BsonDocument>("restaurants");
14+
15+
{
16+
// start-hello
17+
var command = new BsonDocument("hello", 1);
18+
var result = database.RunCommand<BsonDocument>(command);
19+
// end-hello
20+
}
21+
22+
{
23+
// start-read-pref
24+
var command = new BsonDocument("hello", 1);
25+
var result = database.RunCommand<BsonDocument>(command, ReadPreference.Secondary);
26+
// end-read-pref
27+
}
28+
29+
{
30+
// start-print-command
31+
var command = new BsonDocument("dbStats", 1);
32+
var result = database.RunCommand<BsonDocument>(command);
33+
Console.WriteLine(result.ToJson());
34+
// end-print-command
35+
}
36+
}
37+
38+
private static async void RunCommandAsync(IMongoDatabase database)
39+
{
40+
// start-hello-async
41+
var command = new BsonDocument("hello", 1);
42+
var result = await database.RunCommandAsync<BsonDocument>(command);
43+
// end-hello-async
44+
}
45+
46+
private static async void RunCommandReadPrefAsync(IMongoDatabase database)
47+
{
48+
// start-read-pref-async
49+
var command = new BsonDocument("hello", 1);
50+
var result = await database.RunCommandAsync<BsonDocument>(command, ReadPreference.Secondary);
51+
// end-read-pref-async
52+
}
53+
54+
private static async void RunCommandPrintAsync(IMongoDatabase database)
55+
{
56+
// start-print-command-async
57+
var command = new BsonDocument("dbStats", 1);
58+
var result = await database.RunCommandAsync<BsonDocument>(command);
59+
Console.WriteLine(result.ToJson());
60+
// end-print-command-async
61+
}
62+
}

0 commit comments

Comments
 (0)