Run a Command

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.

Execute a Command

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.

Command Options

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 more options in the document that you pass to the command() method. To learn more about a command and the 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);

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

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:

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:

// 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);
}

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

Additional Information

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

• db.runCommand()

• Database Commands

• hello Command

• find Command

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