Docs Menu

Docs HomeNode.js Driver

Run a Command

On this page

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

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.

To run a database command, you must specify the command and any relevant parameters in a document, then pass this 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.

You can specify optional command behavior for the command() and runCursorCommand() methods.

The command() method accepts a RunCommandOptions object. To learn more about the RunCommandOptions type, see the API documentation.

The runCursorCommand() method accepts a RunCursorCommandOptions object. To learn more about the RunCursorCommandOptions type, see the API documentation.

Starting in version 6.0 of the Node.js driver, you can pass only the following options to the command() method:

  • comment

  • enableUtf8Validation

  • raw

  • readPreference

  • session

You can set additional options in the document that you pass to the command() method. To learn more about a command and the additional options that it accepts, locate the command and follow the link on the Database Commands section of the Server manual.

The following code shows how to specify a grantRolesToUser command that executes with a majority write concern:

const commandDoc = {
grantRolesToUser: "user011",
roles: [ "readWrite" ],
writeConcern: { w: "majority" }
};
const result = await myDB.command(commandDoc);

Note

Read Preference

The command() and runCursorCommand() methods ignore the read preference setting you may have set on your Db object. By default, these methods use the primary read preference.

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.

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.

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:

// Connect to the "testDB" database
const db = client.db("testDB");
// Run a cursor command to check metadata consistency within the database
const cursor = await db.runCursorCommand({
checkMetadataConsistency: 1,
});
// Iterate through the cursor's results and print the contents
for await (const doc of cursor) {
console.log(doc);
}

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.

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.

←  TransactionsIndexes →