Run a Database Command

On this page

Overview

Sample Data
Execute a Command
Set a Read Preference
Response
Example
Additional Information
API Documentation

Overview

In this guide, you can learn how to use the Ruby driver 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 MongoDB Shell instead of the Ruby driver. 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 command method, which is described in this guide.

Sample Data

The examples in this guide use the sample_restaurants database from the Atlas sample datasets. To access this database from your Ruby application, create a Mongo::Client object that connects to an Atlas cluster and assign the following value to your database variable:

database = client.use('sample_restaurants')

To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Execute a Command

To run a database command, run the command instance method of a Mongo::Database instance and pass the name of the operation to run as a parameter.

The following example calls the command method to run the hello command, which returns information about the server:

client.database.command(hello: 1)

Tip

To view a full list of database commands and their corresponding parameters, see Database Commands in the MongoDB Server manual.

Set a Read Preference

The command method does not inherit the read preference you might have set on your Database instance. By default, command uses the primary read preference.

You can set a read preference for the command execution by passing the :read opotion to the command method, as shown in the following code:

client.database.command({hello: 1}, read: {mode: :secondary})

Tip

To learn more about read preference options, see Read Preference in the MongoDB Server manual.

Response

The command method returns a Mongo::Operation::Result that contains the response from the database for the given command.

You can access the fields of the raw command response document by using the following methods:

Method	Description
`acknowledged?`	Returns `true` if the server acknowledged the command, and `false` otherwise.
`inspect`	Returns a formatted string representation of the command response.
`ok?`	Returns `true` if the command succeeded, and `false` otherwise. If the `ok?` method returns `false`, the driver raises a `Mongo::Error::OperationFailure` .
`cluster_time`	Returns the cluster time reported in the server response. 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.
`operation_time`	Returns the logical time of the operation execution.

For a full list of methods available on the Result object, see the API documentation.

Tip

To learn more about logical time, see the Wikipedia entry on the 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 inspect method:

puts client.database.command({dbStats: 1}).first

The output of this command includes information about the data stored in the database, as shown in the following code:

{"db"=>"sample_restaurants", "collections"=>4, "views"=>0, "objects"=>18767, "avgObjSize"=>596.1911866574306,
"dataSize"=>11188720, "storageSize"=>7528448, "totalFreeStorageSize"=>0, "numExtents"=>0, "indexes"=>6,
"indexSize"=>1519616, "indexFreeStorageSize"=>0, "fileSize"=>0, "nsSizeMB"=>0, "ok"=>1}

Additional Information

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

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

command

Back

Databases & Collections