Docs Menu
Docs Home
/
Languages
/
Javascript
/
Node.js
/
Fundamentals

Run a Command

On this page

  • Overview
  • Execute a Command
  • Response
  • Example
  • Output
  • Additional Information

Overview

In this guide, you can learn how to run a database command with the Node.js driver. 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. We recommend using driver methods instead of executing database commands when possible.

To perform administrative tasks, use the MongoDB Shell instead of the Node.js driver. Calling the db.runCommand() method inside the shell is the preferred method to issue database commands, as it provides a consistent interface between the shell and drivers.

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 command execution method. The Node.js driver provides the following methods to run database commands:

  • command(), which returns the command response as a Document type. You can use this method with any database command.

  • runCursorCommand(), which returns the command response as an iterable RunCommandCursor type. You can use this method only if your database command returns multiple result documents.

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

const result = await myDB.command({ hello: 1 });

For a full list of database commands and corresponding parameters, see the Additional Information section.

Note

Read Preference

command() and runCursorCommand() do not obey the read preference you may have set on your Db object elsewhere in your code. By default, these methods use the primary read preference.

You can set a read preference for command execution by passing an options object to either method. The command() method takes a RunCommandOptions object, and the runCursorCommand() method takes a RunCursorCommandOptions object.

The following code shows how to specify a read preference and pass it as an option to the command() method:

const commandOptions = { readPreference: "nearest" };
const result = await myDB.command(commandDoc, commandOptions);

For more information on read preference options, see Read Preference in the Server manual.

Response

Each method returns a Document 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:

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.

Tip

See also:

To learn more about logical time, see our blog post about 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 runCursorCommand() method to run the checkMetadataConsistency command on the testDB database and iterate through the results:

const db = client.db("testDB");
const cursor = await db.runCursorCommand({
    checkMetadataConsistency: 1,
});
for await (const doc of cursor) {
  console.log(doc);
}

Output

The output contains the contents of the cursor object. The documents describe any metadata inconsistencies in the database:

{
  type: ...,
  description: ...,
  details: {
    namespace: ...,
    info: ...
  }
}
{
  type: ...,
  description: ...,
  details: {
    namespace: ...,
    collectionUUID: ...,
    maxKeyObj: ...,
    ...
  }
}

Note

If you store the command response in a cursor, you see only the command result documents when you access the contents of the cursor. You won't see the ok, operationTime, and $clusterTime fields.

Additional Information

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

To learn how to retrieve data from a cursor, see the Access Data From a Cursor fundamentals page.

Back

Transactions