Docs Menu
Docs Home
/
Languages
/
Scala
/
Scala
/
Databases & Collections

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 Scala 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 Scala 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 runCommand() 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 Scala application, create a MongoClient that connects to an Atlas cluster and assign the following value to your database variable:

val database: MongoDatabase = mongoClient.getDatabase("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, create a Document object that specifies the command and pass it as a parameter to the runCommand() method. This method returns a SingleObservable instance, and you can subscribe to this observable to execute the command and access the command result.

The following example calls the runCommand() method on a database to run the hello command, which returns information about the server:

database.runCommand(Document("hello" -> 1))
        .subscribe((doc: Document) => ())

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 runCommand() method does not inherit the read preference you might have set on your MongoDatabase instance. By default, runCommand() uses the primary read preference.

You can set a read preference for the command execution by passing a ReadPreference instance as a parameter to runCommand(), as shown in the following code:

database.runCommand(Document("hello" -> 1), ReadPreference.secondary())
        .subscribe((doc: Document) => ())

Tip

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

Response

The runCommand() method returns a SingleObservable that contains the response from the database for the given command. You can call the subscribe() method on the observable to run the command and access the response as a document.

The raw command response document contains the following fields:

Field
Description

<command result>

Fields specific to the database command. For example, the hello command returns the topologyVersion field.

ok

Indicates whether the command has succeeded (1.0) or failed (0.0). The driver raises a MongoCommandException if the ok value is 0.0.

$clusterTime

A document that contains the signed cluster time. 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.

operationTime

The logical time of the operation execution. This field only applies to commands run on replica sets or sharded cluster.

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:

database.runCommand(Document("dbStats" -> 1))
        .subscribe((doc: Document) => println(doc.toJson()),
                  (e: Throwable) => println(s"There was an error: $e"))

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:

Back

Databases & Collections

Next

Time Series