From 1d1f1a6c2abdebf45c56d738c89348381dfac60c Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Fri, 24 Jan 2025 11:23:31 -0500 Subject: [PATCH 01/11] add page --- source/index.txt | 1 + source/run-command.txt | 182 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 source/run-command.txt diff --git a/source/index.txt b/source/index.txt index 908c1c06..dabaf42b 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,7 @@ Aggregation Operations Specialized Data Formats Builders + Run a Command Security In-Use Encryption Compatibility diff --git a/source/run-command.txt b/source/run-command.txt new file mode 100644 index 00000000..85f0cdd5 --- /dev/null +++ b/source/run-command.txt @@ -0,0 +1,182 @@ +.. _kotlin-run-command: + +============= +Run a Command +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to run a database command with the +{+driver-short+}. 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 :mongosh:`MongoDB Shell ` + instead of the {+driver-short+}. 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. + +Execute a Command +----------------- + +To run a database command, specify the command and any relevant +parameters in a document, then pass the document to the ``runCommand()`` method. + +The following code shows how you can use the ``runCommand()`` +method to run the ``find`` command, which returns information about +the current member's role in the replica set, on a database: + +.. code-block:: javascript + + val command = { + find: "restaurants", + filter: { rating: { $gte: 9 }, cuisine: "italian" }, + projection: { name: 1, rating: 1, address: 1 }, + sort: { name: 1 }, + limit: 5 + } + val commandResult = database.runCommand(command) + +For a full list of database commands and corresponding parameters, see +the :manual:`Database Commands ` guide. + +.. _kotlin-command-options: + +Command Options +--------------- + +You can specify optional command behavior for the ``runCommand()`` method by +including a ``readPreference`` parameter. The following example shows how to +specify a read preference and pass it as an option to the ``runCommand()`` +method: + +.. code-block:: javascript + + val command = { "hello": 1 } + val commandReadPreference = { readPreference: "secondary" } + + val commandResult = database.runCommand(command, readPreference) + +For more information on read preference options, see :manual:`Read Preference +` in the Server manual. + +.. note:: + + The ``command()`` method ignores the read preference setting you may have set + on your ``database`` object. If no read preference is specified, this method + uses the ``primary`` read preference. + +Response +-------- + +The ``runCommand()`` method returns a ``Document`` object 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: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Field + - Description + + * - + - 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. + To learn more about logical time, see our + :website:`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. + +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: + +.. literalinclude:: /code-snippets/crud/runCommand.js + :language: javascript + :dedent: + :start-after: start-runcommand + :end-before: end-runcommand + +Output +~~~~~~ + +The output contains the contents of the cursor object. The documents +describe any metadata inconsistencies in the database: + +.. code-block:: javascript + + { + 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. + +.. _addl-info-runcommand: + +Additional Information +---------------------- + +For more information about the concepts in this guide, see the following documentation: + +- Kotlin API + - :driver:`runCommand() <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/run-command.html>` +- Database + - :manual:`Database Commands ` + - :manual:`hello Command ` + - :manual:`find Command ` From 6bf63b1ed15d85c91350259c1c2d9e07c023699e Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 11:03:04 -0500 Subject: [PATCH 02/11] add output --- source/includes/run-command.kt | 22 ++++++++ source/run-command.txt | 93 ++++++++++++++-------------------- 2 files changed, 59 insertions(+), 56 deletions(-) create mode 100644 source/includes/run-command.kt diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt new file mode 100644 index 00000000..3a633570 --- /dev/null +++ b/source/includes/run-command.kt @@ -0,0 +1,22 @@ +import com.mongodb.kotlin.client.MongoClient +import org.bson.Document + +fun main() { + //start-execute + val command = { + find: "restaurants", + filter: { cuisine: "Italian" }, + projection: { name: 1, rating: 1, address: 1 }, + sort: { name: 1 }, + limit: 5 + } + val commandResult = database.runCommand(command) + //end-execute + + //start-read-preference + val command = { "hello": 1 } + val commandReadPreference = { readPreference: "secondary" } + + val commandResult = database.runCommand(command, readPreference) + //end-read-preference +} \ No newline at end of file diff --git a/source/run-command.txt b/source/run-command.txt index 85f0cdd5..bde74344 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -40,16 +40,12 @@ The following code shows how you can use the ``runCommand()`` method to run the ``find`` command, which returns information about the current member's role in the replica set, on a database: -.. code-block:: javascript - - val command = { - find: "restaurants", - filter: { rating: { $gte: 9 }, cuisine: "italian" }, - projection: { name: 1, rating: 1, address: 1 }, - sort: { name: 1 }, - limit: 5 - } - val commandResult = database.runCommand(command) +.. literalinclude:: /includes/run-command.kt + :start-after: start-execute + :end-before: end-execute + :language: kotlin + :copyable: + :dedent: For a full list of database commands and corresponding parameters, see the :manual:`Database Commands ` guide. @@ -64,12 +60,12 @@ including a ``readPreference`` parameter. The following example shows how to specify a read preference and pass it as an option to the ``runCommand()`` method: -.. code-block:: javascript - - val command = { "hello": 1 } - val commandReadPreference = { readPreference: "secondary" } - - val commandResult = database.runCommand(command, readPreference) +.. literalinclude:: /includes/run-command.kt + :start-after: start-read-preference + :end-before: end-read-preference + :language: kotlin + :copyable: + :dedent: For more information on read preference options, see :manual:`Read Preference ` in the Server manual. @@ -124,48 +120,33 @@ 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: +The following code shows the general output format of the ``buildInfo`` command: -.. literalinclude:: /code-snippets/crud/runCommand.js - :language: javascript - :dedent: - :start-after: start-runcommand - :end-before: end-runcommand - -Output -~~~~~~ - -The output contains the contents of the cursor object. The documents -describe any metadata inconsistencies in the database: - -.. code-block:: javascript - - { - type: ..., - description: ..., - details: { - namespace: ..., - info: ... - } - } - { - type: ..., - description: ..., - details: { - namespace: ..., - collectionUUID: ..., - maxKeyObj: ..., - ... - } - } +.. io-code-block:: + + .. input:: /includes/aggregation/aggregation.kt + :language: kotlin + + db.runCommand( { buildInfo: 1 } ); + + .. output:: + :visible: false + + { + version: '8.0.4', + + storageEngines: [ ... ], + ok: 1, + '$clusterTime': { + clusterTime: Timestamp({ t: 1737993450, i: 32 }), + signature: { + ... + } + }, + operationTime: Timestamp({ ... }) + } -.. 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. .. _addl-info-runcommand: @@ -175,7 +156,7 @@ Additional Information For more information about the concepts in this guide, see the following documentation: - Kotlin API - - :driver:`runCommand() <{+api+}/apidocs/mongodb-driver-kotlin-sync/mongodb-driver-kotlin-sync/com.mongodb.kotlin.client/-mongo-database/run-command.html>` + - `runCommand() <{+api+}/com.mongodb.kotlin.client/-mongo-database/run-command.html>`__ - Database - :manual:`Database Commands ` - :manual:`hello Command ` From 8771d58095922d97d9e65138373c9f19f12e02bf Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 11:12:34 -0500 Subject: [PATCH 03/11] fix code block --- source/run-command.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/run-command.txt b/source/run-command.txt index bde74344..9cbf7271 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -124,7 +124,7 @@ The following code shows the general output format of the ``buildInfo`` command: .. io-code-block:: - .. input:: /includes/aggregation/aggregation.kt + .. input:: :language: kotlin db.runCommand( { buildInfo: 1 } ); From 2a498b501b6b5b57decd38d1e817f05ab012bf4c Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 11:46:56 -0500 Subject: [PATCH 04/11] update examples --- source/includes/run-command.kt | 13 +++++-------- source/run-command.txt | 9 +++++---- 2 files changed, 10 insertions(+), 12 deletions(-) diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt index 3a633570..5708e693 100644 --- a/source/includes/run-command.kt +++ b/source/includes/run-command.kt @@ -3,14 +3,11 @@ import org.bson.Document fun main() { //start-execute - val command = { - find: "restaurants", - filter: { cuisine: "Italian" }, - projection: { name: 1, rating: 1, address: 1 }, - sort: { name: 1 }, - limit: 5 - } - val commandResult = database.runCommand(command) + val explanation = database.runCommand({ + explain: { + find: 'restaurants' + } + }) //end-execute //start-read-preference diff --git a/source/run-command.txt b/source/run-command.txt index 9cbf7271..9f8a0fee 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -37,8 +37,8 @@ To run a database command, specify the command and any relevant parameters in a document, then pass the document to the ``runCommand()`` method. The following code shows how you can use the ``runCommand()`` -method to run the ``find`` command, which returns information about -the current member's role in the replica set, on a database: +method to run the ``explain`` command, which returns information about +how the specified CRUD command would be executed: .. literalinclude:: /includes/run-command.kt :start-after: start-execute @@ -155,9 +155,10 @@ Additional Information For more information about the concepts in this guide, see the following documentation: -- Kotlin API +- Kotlin Sync API - `runCommand() <{+api+}/com.mongodb.kotlin.client/-mongo-database/run-command.html>`__ - Database - :manual:`Database Commands ` + - :manual:`explain Command ` - :manual:`hello Command ` - - :manual:`find Command ` + - :manual:`buildInfo Command ` From 615cee463dc52c8dfa4818d4b18d77c609ea89bf Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 11:53:49 -0500 Subject: [PATCH 05/11] code egs --- source/includes/run-command.kt | 4 ++++ source/run-command.txt | 9 +++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt index 5708e693..080d93e9 100644 --- a/source/includes/run-command.kt +++ b/source/includes/run-command.kt @@ -16,4 +16,8 @@ fun main() { val commandResult = database.runCommand(command, readPreference) //end-read-preference + + //start-build-info + println( db.runCommand( { buildInfo: 1 } ) ); + //end-build-info } \ No newline at end of file diff --git a/source/run-command.txt b/source/run-command.txt index 9f8a0fee..2b20e0d6 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -72,7 +72,7 @@ For more information on read preference options, see :manual:`Read Preference .. note:: - The ``command()`` method ignores the read preference setting you may have set + The ``runCommand()`` method ignores the read preference setting you may have set on your ``database`` object. If no read preference is specified, this method uses the ``primary`` read preference. @@ -124,10 +124,11 @@ The following code shows the general output format of the ``buildInfo`` command: .. io-code-block:: - .. input:: + .. input:: /includes/run-command.kt + :start-after: start-build-info + :end-before: end-build-info :language: kotlin - - db.runCommand( { buildInfo: 1 } ); + :dedent: .. output:: :visible: false From 5cacd32a48c72e51a51b6287f1f078417e5f6e61 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 11:54:51 -0500 Subject: [PATCH 06/11] link bullets format --- source/run-command.txt | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/run-command.txt b/source/run-command.txt index 2b20e0d6..e791e9fa 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -156,10 +156,8 @@ Additional Information For more information about the concepts in this guide, see the following documentation: -- Kotlin Sync API - - `runCommand() <{+api+}/com.mongodb.kotlin.client/-mongo-database/run-command.html>`__ -- Database - - :manual:`Database Commands ` - - :manual:`explain Command ` - - :manual:`hello Command ` - - :manual:`buildInfo Command ` +- `Kotlin Sync API runCommand() <{+api+}/com.mongodb.kotlin.client/-mongo-database/run-command.html>`__ +- :manual:`Database Commands ` +- :manual:`explain Command ` +- :manual:`hello Command ` +- :manual:`buildInfo Command ` From 116ebad5c485123c67c94c155c7f31840ea870e0 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 12:57:18 -0500 Subject: [PATCH 07/11] vale --- source/run-command.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/run-command.txt b/source/run-command.txt index e791e9fa..0e484673 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -37,8 +37,8 @@ To run a database command, specify the command and any relevant parameters in a document, then pass the document to the ``runCommand()`` method. The following code shows how you can use the ``runCommand()`` -method to run the ``explain`` command, which returns information about -how the specified CRUD command would be executed: +method to run the ``explain`` command, which returns a description of how the +``find`` command will be executed if you call it: .. literalinclude:: /includes/run-command.kt :start-after: start-execute From 59d5577ae533f8ea2c2337c6216b24cd6920fb90 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 13:08:26 -0500 Subject: [PATCH 08/11] correct variable --- source/includes/run-command.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt index 080d93e9..6dc25386 100644 --- a/source/includes/run-command.kt +++ b/source/includes/run-command.kt @@ -18,6 +18,6 @@ fun main() { //end-read-preference //start-build-info - println( db.runCommand( { buildInfo: 1 } ) ); + println( database.runCommand( { buildInfo: 1 } ) ); //end-build-info } \ No newline at end of file From cdd710f223f83a2df2da6afd4868928605e5c9dc Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Mon, 27 Jan 2025 15:59:24 -0500 Subject: [PATCH 09/11] MM feedback --- source/includes/run-command.kt | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt index 6dc25386..982463b0 100644 --- a/source/includes/run-command.kt +++ b/source/includes/run-command.kt @@ -3,21 +3,18 @@ import org.bson.Document fun main() { //start-execute - val explanation = database.runCommand({ - explain: { - find: 'restaurants' - } - }) + val commandToExplain = Document( "find", "restaurants") + val explanation = database.runCommand(Document("explain", commandToExplain)) //end-execute //start-read-preference - val command = { "hello": 1 } - val commandReadPreference = { readPreference: "secondary" } + val command = Document("hello", 1) + val commandReadPreference = Document( "readPreference", "secondary" ) - val commandResult = database.runCommand(command, readPreference) + val commandResult = database.runCommand(command, commandReadPreference) //end-read-preference //start-build-info - println( database.runCommand( { buildInfo: 1 } ) ); + println( database.runCommand( Document( "buildInfo", 1 ) ); //end-build-info } \ No newline at end of file From 1b8fd276c6ddf55a1a996c79ff34afc0f703adbf Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 28 Jan 2025 13:58:43 -0500 Subject: [PATCH 10/11] NH feedback --- source/includes/run-command.kt | 28 +++++++++++++++++++++++++--- source/run-command.txt | 11 +++++------ 2 files changed, 30 insertions(+), 9 deletions(-) diff --git a/source/includes/run-command.kt b/source/includes/run-command.kt index 982463b0..c878b139 100644 --- a/source/includes/run-command.kt +++ b/source/includes/run-command.kt @@ -1,20 +1,42 @@ +//start-full-example +import com.mongodb.MongoException import com.mongodb.kotlin.client.MongoClient import org.bson.Document +import org.bson.BsonInt64 +import org.bson.json.JsonWriterSettings + fun main() { + // Replace the placeholder with your MongoDB deployment's connection string + val uri = "" + + val mongoClient = MongoClient.create(uri) + val database = mongoClient.getDatabase("sample_mflix") + try { + val command = Document("buildInfo", BsonInt64(1)) + val commandResult = database.runCommand(command) + println(commandResult.toJson(JsonWriterSettings.builder().indent(true).build())) + } catch (me: MongoException) { + System.err.println("An error occurred: $me") + } + mongoClient.close() +} +//end-full-example + +fun command_examples() { //start-execute - val commandToExplain = Document( "find", "restaurants") + val commandToExplain = Document("find", "restaurants") val explanation = database.runCommand(Document("explain", commandToExplain)) //end-execute //start-read-preference val command = Document("hello", 1) - val commandReadPreference = Document( "readPreference", "secondary" ) + val commandReadPreference = Document("readPreference", "secondary") val commandResult = database.runCommand(command, commandReadPreference) //end-read-preference //start-build-info - println( database.runCommand( Document( "buildInfo", 1 ) ); + println(database.runCommand(Document("buildInfo", 1)); //end-build-info } \ No newline at end of file diff --git a/source/run-command.txt b/source/run-command.txt index 0e484673..46ad142f 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -13,7 +13,7 @@ Run a Command Overview -------- -In this guide, you can learn how to run a database command with the +In this guide, you can learn how to run a database command by using the {+driver-short+}. 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. @@ -125,8 +125,8 @@ The following code shows the general output format of the ``buildInfo`` command: .. io-code-block:: .. input:: /includes/run-command.kt - :start-after: start-build-info - :end-before: end-build-info + :start-after: start-full-example + :end-before: end-full-example :language: kotlin :dedent: @@ -135,11 +135,10 @@ The following code shows the general output format of the ``buildInfo`` command: { version: '8.0.4', - - storageEngines: [ ... ], + ...... ok: 1, '$clusterTime': { - clusterTime: Timestamp({ t: 1737993450, i: 32 }), + clusterTime: Timestamp({ ... }), signature: { ... } From d3dafcf95b43779a1ffbeea37dfd45ff8ca87092 Mon Sep 17 00:00:00 2001 From: Rachel Mackintosh Date: Tue, 28 Jan 2025 14:28:50 -0500 Subject: [PATCH 11/11] reword --- source/run-command.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/run-command.txt b/source/run-command.txt index 46ad142f..8a8beae5 100644 --- a/source/run-command.txt +++ b/source/run-command.txt @@ -120,7 +120,7 @@ with the following fields: Example ------- -The following code shows the general output format of the ``buildInfo`` command: +The following example shows how to run the ``buildInfo`` command, and the output it produces: .. io-code-block::