run-command.txt

.. _golang-run-command:

=============
Run a Command
=============

.. meta::
   :description: Learn how to execute database commands using the MongoDB Go Driver, including methods for running commands and handling responses.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Overview
--------

In this guide, you can learn how to run a database command with the
{+driver-short+}. 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.

Execute a Command
-----------------

To run a database command, you must specify the command and any relevant
parameters in a command document, then pass the command document to a
wrapper method. The command document must be an order-preserving type
such as ``bson.D``. The {+driver-short+} provides the following methods
to run database commands:

- ``RunCommand()``, which returns the command response as a
  ``SingleResult`` type. You can use this method with any database command.
- ``RunCommandCursor()``, which returns the command response as a
  ``Cursor`` type. You can use this method if your database command
  returns multiple result documents.

The following code shows how you can use the ``RunCommand()``
method to run the ``hello`` command, which returns information about
the current member's role in the replica set, on a database:

.. code-block:: go

   command := bson.D{{"hello", 1}}

   var result bson.M
   err = db.RunCommand(context.TODO(), command).Decode(&result)

For a full list of database commands and corresponding parameters, see
the :ref:`Additional Information section <addl-info-runcommand>`.

.. note:: Read Preference

   ``RunCommand()`` and ``RunCommandCursor()`` do not obey the read
   preference you may have set on your ``Database`` object elsewhere in
   your code. You can set a read preference for command execution by
   passing a ``RunCmdOptions`` object to either method:
   
   .. code-block:: go

      opts := options.RunCmd().SetReadPreference(readpref.Primary())
      cursor, err := db.RunCommandCursor(context.TODO(), command, opts)
   
   For more information on
   read preference options, see the :ref:`golang-write-read-pref`
   fundamentals page.

Response
--------

Each method returns a ``SingleResult`` object or a cursor that contains
the response from the database after the command has been executed. Each
database command performs a different function, so the response content
can vary across commands. However, every response contains documents
with the following fields:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Field
     - Description

   * - <command result>
     - Provides fields specific to the database command. For example,
       ``count`` returns the ``n`` field and ``explain`` returns the
       ``queryPlanner`` field.

   * - ``ok``
     - Indicates whether the command has succeeded (``1``)
       or failed (``0``).

   * - ``operationTime``
     - Indicates the logical time of the operation. MongoDB uses the
       logical time to order operations. To learn more about logical time, see our :website:`blog post about
       the Global Logical Clock </blog/post/transactions-background-part-4-the-global-logical-clock>`.

   * - ``$clusterTime``
     - Provides a document that returns the signed cluster time. Cluster time is a
       logical time used for ordering of operations.

       The document contains the following fields:

       - ``clusterTime``, which is the timestamp of the highest known cluster time for the member.
       - ``signature``, which is a document that contains the hash of the cluster time and the ID
         of the key used to sign the cluster time.

Example
-------

The following code shows how you can use the ``RunCommand()`` method to
run the ``explain`` command for a ``count`` operation on the ``flowers`` collection of the
``db`` database. The ``explain`` command runs in the
``"queryPlanner"`` verbosity mode:

.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/runCommand.go
   :language: go
   :dedent:
   :start-after: start-runcommand
   :end-before: end-runcommand

Output
~~~~~~

In the output, you should see fields explaining the
execution of the ``count`` operation, such as the winning plan, which is
the plan selected by the query optimizer, and any rejected
plans. The output also contains information about the execution of the
``explain`` command:

.. code-block:: json
   :emphasize-lines: 9-13,19-29

   {
       "$clusterTime": {
           "clusterTime": {
               "T": 1673969525,
               "I": 24
           },
           "signature": {...}
       },
       "command": {
           "$db": "db",
           "count": "flowers"
       },
       "explainVersion": "1",
       "ok": 1,
       "operationTime": {
           "T": 1673969525,
           "I": 24
       },
       "queryPlanner": {
           "indexFilterSet": false,
           "maxIndexedAndSolutionsReached": false,
           "maxIndexedOrSolutionsReached": false,
           "maxScansToExplodeReached": false,
           "namespace": "db.flowers",
           "rejectedPlans": [],
           "winningPlan": {
               "stage": "RECORD_STORE_FAST_COUNT"
           }
       },
       "serverInfo": {...},
       "serverParameters": {
           "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
           ...
       }
   }

.. _addl-info-runcommand:

Additional Information
----------------------

For more information about the concepts in this guide, see the following documentation:

- :manual:`db.runCommand() </reference/method/db.runCommand/>`
- :manual:`Database Commands </reference/command/>`
- :manual:`hello Command </reference/command/hello/>`
- :manual:`explain Command </reference/command/explain/>`

To learn how to retrieve data from a cursor, see the
:ref:`golang-cursor` fundamentals page.

API Documentation
~~~~~~~~~~~~~~~~~

- `RunCommand() <{+api+}/mongo#Database.RunCommand>`__
- `RunCommandCursor() <{+api+}/mongo#Database.RunCommandCursor>`__
- `RunCmdOptions <{+api+}/mongo/options#RunCmdOptions>`__