From 2b6099f5df73be7e69bbf68c0fe48771c41c002e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 20 Nov 2024 11:33:47 -0500 Subject: [PATCH 1/3] DOCSP-45005: Run Command --- snooty.toml | 1 + source/fundamentals/database-collection.txt | 3 + .../databases-collections/run-command.txt | 230 ++++++++++++++++++ .../databases-collections/RunCommand.cs | 62 +++++ 4 files changed, 296 insertions(+) create mode 100644 source/fundamentals/databases-collections/run-command.txt create mode 100644 source/includes/fundamentals/code-examples/databases-collections/RunCommand.cs diff --git a/snooty.toml b/snooty.toml index 203bbe4b..cd140314 100644 --- a/snooty.toml +++ b/snooty.toml @@ -7,6 +7,7 @@ toc_landing_pages = [ "/fundamentals", "/fundamentals/serialization", "/upgrade", + "/fundamentals/database-collection" ] intersphinx = [ diff --git a/source/fundamentals/database-collection.txt b/source/fundamentals/database-collection.txt index 783d026d..919d9e03 100644 --- a/source/fundamentals/database-collection.txt +++ b/source/fundamentals/database-collection.txt @@ -17,6 +17,9 @@ Databases and Collections :depth: 2 :class: singlecol +.. toctree:: + /fundamentals/databases-collections/run-command + Overview -------- diff --git a/source/fundamentals/databases-collections/run-command.txt b/source/fundamentals/databases-collections/run-command.txt new file mode 100644 index 00000000..42da908a --- /dev/null +++ b/source/fundamentals/databases-collections/run-command.txt @@ -0,0 +1,230 @@ +.. _csharp-run-command: + +====================== +Run a Database Command +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: administration, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to +run a database command. You can use database commands to perform a +variety of administrative and diagnostic tasks, such as fetching server +statistics, initializing a replica set, or running an aggregation pipeline. + +.. important:: Prefer Driver Methods to Database Commands + + The driver provides wrapper methods for many database commands. + If possible, we recommend using these methods instead of executing + database commands. + + To perform administrative tasks, use the :mongosh:`MongoDB Shell ` + instead of the {+driver-short+}. The shell provides helper methods + that might not be available in the driver. + + If there are no available helpers in the driver or the shell, you + can use the ``db.runCommand()`` shell method or the driver's + ``RunCommand()`` method, which is described in this + guide. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``sample_restaurants.restaurants`` collection +from the :atlas:`Atlas sample datasets `. To learn how to create a +free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. + + +Execute a Command +----------------- + +To run a database command, create a ``BsonDocument`` object that specifies +the command and pass it as a parameter to the ``RunCommand()`` or ``RunCommandAsync()`` +method. This method returns a ``SingleObservable`` instance, and you can subscribe +to this observable to execute the command and access the command result. + +The following example calls the ``RunCommand()`` method on a database +to run the ``hello`` command, which returns information about the server. +Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` +tab to see the corresponding code. + +.. tabs:: + + .. tab:: Asynchronous + :tabid: run-command-async + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-hello-async + :end-before: end-hello-async + + .. tab:: Synchronous + :tabid: distinct-sync + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-hello + :end-before: end-hello + +.. tip:: + + To view a full list of database commands and their corresponding + parameters, see :manual:`Database Commands ` in + the {+mdb-server+} manual. + +.. _csharp-command-read-pref: + +Set a Read Preference +---------------------- + +The ``RunCommand()`` method does not inherit the read preference you might +have set on your ``MongoDatabase`` instance. By default, ``RunCommand()`` +uses the ``primary`` read preference. + +You can set a read preference for the command execution by passing a +``ReadPreference`` instance as a parameter to ``RunCommand()``, as +shown in the following example. Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` +tab to see the corresponding code. + +.. tabs:: + + .. tab:: Asynchronous + :tabid: run-command-async + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-read-pref-async + :end-before: end-read-pref-async + + .. tab:: Synchronous + :tabid: distinct-sync + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-read-pref + :end-before: end-read-pref + +.. tip:: + + To learn more about read preference options, see :manual:`Read + Preference ` in the {+mdb-server+} manual. + +.. _csharp-command-response: + +Response +-------- + +You can specify the type returned by the ``RunCommand()`` method by specifying +the type parameter. + +The raw command response document contains the following fields: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Field + - Description + + * - ```` + - Fields specific to the database command. For example, + the ``hello`` command returns the ``topologyVersion`` field. + + * - ``ok`` + - Indicates whether the command has succeeded (``1.0``) or failed (``0.0``). The + driver raises a ``MongoCommandException`` if the ``ok`` + value is ``0.0``. + + * - ``$clusterTime`` + - A document that contains the signed cluster time. Cluster time is a + logical time used for the ordering of operations. This field only + applies to commands run on replica sets or sharded cluster. + + * - ``operationTime`` + - The logical time of the operation execution. This field only + applies to commands run on replica sets or sharded cluster. + +.. tip:: + + To learn more about logical time, see the Wikipedia entry on + the :wikipedia:`logical clock `. + +Example +~~~~~~~ + +The following example runs the ``dbStats`` command to retrieve +storage statistics for the ``sample_restaurants`` database, then prints the +command results by using the ``ToJson()`` method on the returned ``BsonDocument`` object. +Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to see the corresponding +code. + +.. tabs:: + + .. tab:: Asynchronous + :tabid: run-command-async + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-print-command-async + :end-before: end-print-command-async + + .. tab:: Synchronous + :tabid: distinct-sync + + .. literalinclude:: /includes/fundamentals/code-examples/databases-collections/RunCommand.cs + :language: csharp + :dedent: + :start-after: start-print-command + :end-before: end-print-command + +The output of this command includes information about the data stored in +the database, as shown in the following code: + +.. code-block:: none + :copyable: false + + { "db" : "sample_restaurants", "collections" : 2, "views" : 0, "objects" : + NumberLong(25438), "avgObjSize" : 548.95172576460413, "dataSize" : NumberLong(13964234), + "storageSize" : NumberLong(8056832), "totalFreeStorageSize" : NumberLong(0), + "numExtents" : NumberLong(0), "indexes" : 2, "indexSize" : NumberLong(1044480), + "indexFreeStorageSize" : NumberLong(0), "fileSize" : NumberLong(0), "nsSizeMB" : 0, "ok" : 1 } + + +Additional Information +---------------------- + +For more information about the concepts in this guide, see the following +documentation in the {+mdb-server+} manual: + +- :manual:`db.runCommand() ` +- :manual:`Database Commands ` +- :manual:`hello Command ` +- :manual:`dbStats Command ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `RunCommand() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.RunCommand.html>`_ +- `RunCommandAsync() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoDatabase.RunCommandAsync.html>`_ +- `ReadPreference <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ReadPreference.html>`_ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/databases-collections/RunCommand.cs b/source/includes/fundamentals/code-examples/databases-collections/RunCommand.cs new file mode 100644 index 00000000..3b34859c --- /dev/null +++ b/source/includes/fundamentals/code-examples/databases-collections/RunCommand.cs @@ -0,0 +1,62 @@ +using MongoDB.Bson; +using MongoDB.Driver; + +public class RunCommand +{ + // Replace with your connection string + private const string MongoConnectionString = ""; + + public static void Main(string[] args) + { + var mongoClient = new MongoClient(MongoConnectionString); + var database = mongoClient.GetDatabase("sample_restaurants"); + var collection = database.GetCollection("restaurants"); + + { + // start-hello + var command = new BsonDocument("hello", 1); + var result = database.RunCommand(command); + // end-hello + } + + { + // start-read-pref + var command = new BsonDocument("hello", 1); + var result = database.RunCommand(command, ReadPreference.Secondary); + // end-read-pref + } + + { + // start-print-command + var command = new BsonDocument("dbStats", 1); + var result = database.RunCommand(command); + Console.WriteLine(result.ToJson()); + // end-print-command + } + } + + private static async void RunCommandAsync(IMongoDatabase database) + { + // start-hello-async + var command = new BsonDocument("hello", 1); + var result = await database.RunCommandAsync(command); + // end-hello-async + } + + private static async void RunCommandReadPrefAsync(IMongoDatabase database) + { + // start-read-pref-async + var command = new BsonDocument("hello", 1); + var result = await database.RunCommandAsync(command, ReadPreference.Secondary); + // end-read-pref-async + } + + private static async void RunCommandPrintAsync(IMongoDatabase database) + { + // start-print-command-async + var command = new BsonDocument("dbStats", 1); + var result = await database.RunCommandAsync(command); + Console.WriteLine(result.ToJson()); + // end-print-command-async + } +} \ No newline at end of file From 80e02fb1054471db4b5027f73cae337226424fe5 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 20 Nov 2024 11:44:26 -0500 Subject: [PATCH 2/3] Fixes --- .../databases-collections/run-command.txt | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/source/fundamentals/databases-collections/run-command.txt b/source/fundamentals/databases-collections/run-command.txt index 42da908a..b0c45c46 100644 --- a/source/fundamentals/databases-collections/run-command.txt +++ b/source/fundamentals/databases-collections/run-command.txt @@ -37,7 +37,7 @@ statistics, initializing a replica set, or running an aggregation pipeline. If there are no available helpers in the driver or the shell, you can use the ``db.runCommand()`` shell method or the driver's - ``RunCommand()`` method, which is described in this + ``RunCommand()`` and ``RunCommandAsync()`` methods, which are described in this guide. Sample Data @@ -53,12 +53,13 @@ Execute a Command To run a database command, create a ``BsonDocument`` object that specifies the command and pass it as a parameter to the ``RunCommand()`` or ``RunCommandAsync()`` -method. This method returns a ``SingleObservable`` instance, and you can subscribe -to this observable to execute the command and access the command result. +method. You can specify the type returned by the ``RunCommand()`` and ``RunCommandAsync()`` +methods by specifying the type parameter. You can use the ``BsonDocument`` type to return +the command response, or you can specify your own strongly typed class to deserialize +the command response. -The following example calls the ``RunCommand()`` method on a database -to run the ``hello`` command, which returns information about the server. -Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` +The following example runs the ``hello`` command on a database, which returns information +about the server. Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` tab to see the corresponding code. .. tabs:: @@ -131,10 +132,8 @@ tab to see the corresponding code. Response -------- -You can specify the type returned by the ``RunCommand()`` method by specifying -the type parameter. - -The raw command response document contains the following fields: +The raw command response document returned by the ``RunCommand()`` method contains the +following fields: .. list-table:: :header-rows: 1 @@ -196,7 +195,7 @@ code. :end-before: end-print-command The output of this command includes information about the data stored in -the database, as shown in the following code: +the database, as shown in the result returned by the previous example: .. code-block:: none :copyable: false From 209c82110bb0e5695732e271759fa359f6241669 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 20 Nov 2024 16:33:24 -0500 Subject: [PATCH 3/3] SA feedback --- .../databases-collections/run-command.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/source/fundamentals/databases-collections/run-command.txt b/source/fundamentals/databases-collections/run-command.txt index b0c45c46..fbf020a8 100644 --- a/source/fundamentals/databases-collections/run-command.txt +++ b/source/fundamentals/databases-collections/run-command.txt @@ -53,10 +53,9 @@ Execute a Command To run a database command, create a ``BsonDocument`` object that specifies the command and pass it as a parameter to the ``RunCommand()`` or ``RunCommandAsync()`` -method. You can specify the type returned by the ``RunCommand()`` and ``RunCommandAsync()`` -methods by specifying the type parameter. You can use the ``BsonDocument`` type to return -the command response, or you can specify your own strongly typed class to deserialize -the command response. +method. You can specify the type returned by these methods by specifying the type parameter. +You can use the ``BsonDocument`` type to return the command response, or you can specify your +own strongly typed class to deserialize the command response. The following example runs the ``hello`` command on a database, which returns information about the server. Select the :guilabel:`Asynchronous` or :guilabel:`Synchronous` @@ -154,11 +153,11 @@ following fields: * - ``$clusterTime`` - A document that contains the signed cluster time. Cluster time is a logical time used for the ordering of operations. This field only - applies to commands run on replica sets or sharded cluster. + applies to commands run on replica sets or sharded clusters. * - ``operationTime`` - The logical time of the operation execution. This field only - applies to commands run on replica sets or sharded cluster. + applies to commands run on replica sets or sharded clusters. .. tip::