diff --git a/snooty.toml b/snooty.toml index 18142a98..fb628169 100644 --- a/snooty.toml +++ b/snooty.toml @@ -5,6 +5,7 @@ toc_landing_pages = [ "/connect", "/write", "/indexes", + "/databases-collection", "/security/authentication" ] diff --git a/source/databases-collection.txt b/source/databases-collection.txt index 184f3771..43d18ad5 100644 --- a/source/databases-collection.txt +++ b/source/databases-collection.txt @@ -17,6 +17,12 @@ Databases and Collections .. meta:: :keywords: table, row, organize, storage +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Run a Command + Overview -------- @@ -122,8 +128,6 @@ To query for only the names of the collections in the database, call the (i.e. each collection object can be further queried for metadata), while ``database.collection_names`` simply lists the collection names. - - Delete a Collection ------------------- diff --git a/source/databases-collections/run-command.txt b/source/databases-collections/run-command.txt new file mode 100644 index 00000000..7f8fc4c0 --- /dev/null +++ b/source/databases-collections/run-command.txt @@ -0,0 +1,184 @@ +.. _ruby-run-command: + +====================== +Run a Database Command +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: administration, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} 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 :mongosh:`MongoDB Shell ` + instead of the {+driver-short+}. 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:`Atlas sample datasets `. To access this database +from your {+language+} application, create a ``Mongo::Client`` object that connects to an Atlas cluster +and assign the following value to your ``database`` variable: + +.. literalinclude:: /includes/databases-collections/run-command.rb + :language: scala + :dedent: + :start-after: start-db + :end-before: end-db + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`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: + +.. literalinclude:: /includes/databases-collections/run-command.rb + :language: scala + :dedent: + :start-after: start-hello + :end-before: end-hello + +.. tip:: + + To view a full list of database commands and their corresponding + parameters, see :manual:`Database Commands ` in + the {+mdb-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: + +.. literalinclude:: /includes/databases-collections/run-command.rb + :language: scala + :dedent: + :start-after: start-readpref + :end-before: end-readpref + +.. tip:: + + To learn more about read preference options, see :manual:`Read + Preference ` in the {+mdb-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: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 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 <{+api-root+}/Mongo/Operation/Result.html>`__. + +.. tip:: + + To learn more about logical time, see the Wikipedia entry on + the :wikipedia:`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: + +.. literalinclude:: /includes/databases-collections/run-command.rb + :language: ruby + :dedent: + :start-after: start-print-command + :end-before: end-print-command + +The output of this command includes information about the data stored in +the database, as shown in the following code: + +.. code-block:: none + :copyable: false + + {"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 {+mdb-server+} manual: + +- :manual:`db.runCommand() ` +- :manual:`Database Commands ` +- :manual:`hello Command ` +- :manual:`dbStats Command ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `command <{+api-root+}/Mongo/Database.html#command-instance_method>`_ \ No newline at end of file diff --git a/source/includes/databases-collections/run-command.rb b/source/includes/databases-collections/run-command.rb new file mode 100644 index 00000000..ffb71988 --- /dev/null +++ b/source/includes/databases-collections/run-command.rb @@ -0,0 +1,25 @@ +require 'bundler/inline' +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = "" + +Mongo::Client.new(uri) do |client| + # start-db + database = client.use('sample_restaurants') + # end-db + + # start-hello + client.database.command(hello: 1) + # end-hello + + # start-readpref + client.database.command({hello: 1}, read: {mode: :secondary}) + # end-readpref + + # start-print-command + puts client.database.command({dbStats: 1}).first + # end-print-command +end \ No newline at end of file diff --git a/source/write/delete.txt b/source/write/delete.txt index 88943e0b..6d8329c7 100644 --- a/source/write/delete.txt +++ b/source/write/delete.txt @@ -32,7 +32,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection -from your {+language+} application, create a ``MongoClient`` that connects to an Atlas cluster +from your {+language+} application, create a ``Mongo::Client`` object that connects to an Atlas cluster and assign the following values to your ``database`` and ``collection`` variables: .. literalinclude:: /includes/write/delete.rb diff --git a/source/write/replace.txt b/source/write/replace.txt index 1119e154..5f45e105 100644 --- a/source/write/replace.txt +++ b/source/write/replace.txt @@ -35,7 +35,7 @@ Sample Data The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database from the :atlas:`Atlas sample datasets `. To access this collection -from your {+language+} application, create a ``MongoClient`` object that connects to an Atlas cluster +from your {+language+} application, create a ``Mongo::Client`` object that connects to an Atlas cluster and assign the following values to your ``database`` and ``collection`` variables: .. literalinclude:: /includes/write/replace.rb