Connectors / Service / MongoDB Shell

The MongoDB Shell, mongosh, is a fully functional JavaScript and Node.js 14.x REPL environment for interacting with MongoDB deployments. You can use the MongoDB Shell to test queries and operations directly with your database. (updated: 1643126702841)

MongoDB Shell

MongoDB Shell is the quickest way to connect to (and work with) MongoDB. Easily query data, configure settings, and execute other actions with this modern, extensible command-line interface — replete with syntax highlighting, intelligent autocomplete, contextual help, and error messages.

Overview

MongoDB Shell is the quickest way to connect to (and work with) MongoDB. Easily query data, configure settings, and execute other actions with this modern, extensible command-line interface — replete with syntax highlighting, intelligent autocomplete, contextual help, and error messages.

SHELL VERSION: The version of the Linux MongoDB Shell (mongosh) currently used by the connector is v1.1.2

IMPORTANT: The MongoDB Shell connector only supports connections to MongoDB databases v4.0 and above.

Authentication

Within the builder, click on the MongoDB Shell connector to display the connector properties panel. Select the 'Authentication' tab and click on the 'New authentication' button.

mongodb-shell-auth

In the Tray.io authentication pop-up modal name the authentication in a way that will easily identify it within a potentially large list. For example whether it is a Sandbox or Production auth, etc.

Consider who/ how many people will need access to this authentication when choosing where to create this authentication ('Personal' or 'Organisational').

The second page asks you for your MongoDB 'Connection string', 'Username' and 'Password' credentials.

mongodb-shell-popup

CONNECTION STRINGS: There are many ways to connect to a MongoDB database. Please see Connection strings for variations and examples.

IMPORTANT: Please do not include the 'Username' or 'Password' in the connection string. They are provided separately in the authentication inputs and are automatically applied to the connection.

e.g. To connect to an Atlas Cloud MongoDB the connection string would be similar to:

mongodb+srv://cluster0.example.mongodb.net/myFirstDatabase

Once you have added these fields to your Tray.io authentication pop-up window, click the 'Create authentication' button.

Your connector authentication setup should now be complete.

Notes on using MongoDB Shell

The connector only has one operation, 'Run script'. This operation accepts JavaScript code that is to be run against the authenticated MongoDB database.

The script can contain one or more commands. It is possible to create very simple or very complex scripts. For guidance on the acceptable commands that can be issued please consult the MongoDB Manual for all of the mongosh methods that can be invoked.

USER TIP: For guidance on writing scripts for the MongoDB Shell please consult the MongoDB Manual

Output

The output of the 'Run script' operation is structured like this:

{
"output": [
"String values",
[
{
"key": "value"
}
],
{
"key": "value"
}
],
"errors": [
"Error: Description of error."
],
"warnings": [
"Warning: Description of warning."
]
}

The 'output' key is a representation of the output that the shell displays when the script's commands were run against it. It can consist of strings, arrays of objects, objects, or a mixture of the above. If the shell string output can be converted to a JSON object then it will be so that it is easier to process in subsequent workflow steps.

In order to assist the conversion of the shell output to JSON please wrap your method calls with EJSON.stringify();. Tray will convert any valid JSON strings into objects.

e.g. db.stats() will output the stats as individual strings:

{
"output": [
"{",
"db: \"name\",",
"collections: 1,",
"views: 0,",
"}"
],
"errors": [],
"warnings": []
}

but, if we convert the output to JSON,

e.g. EJSON.stringify(db.stats()); will output the stats as a JSON object, which is far more accessible:

{
"output": [
{
"db": "name",
"collections": 1,
"views": 0
}
],
"errors": [],
"warnings": []
}

Warnings

The 'warnings' key contains a list of warnings that have been issued by the MongoDB Shell.

Errors

The 'error' key contains a list of errors that have been issued by the MongoDB Shell. Note that these 'errors' are not necessarily serious issues. For instance, the shell may report Error: Could not open history file. This will not effect the running of the shell methods, so can be ignored.

If there is a problem running the shell script or connecting to the database then the workflow will error and retry the workflow step.

Available Operations

The examples below show one or two of the available connector operations in use.

Please see the Full Operations Reference at the end of this page for details on all available operations for this connector.

Example Usage

TRAY POTENTIAL: Tray.io is extremely flexible. By design there is no fixed way of working with it - you can pull whatever data you need from other services and work with it using our core and helper connectors. This demo which follows shows only one possible way of working with Tray.io and the mongodb-shell connector. Once you've finished working through this example please see our Introduction to working with data and jsonpaths page and Data Guide for more details.

Below is an example of a way in which you could potentially use the MongoDB Shell connector, to iterate over a dataset and output records that match certain criteria. In this case, we will be finding accommodation listings with 18 beds available and listing them in the connector's output as JSON objects.

The steps will be as follows:

  1. Setup using a manual trigger and run the MongoDB Shell script.

Your completed workflow should look similar to this:

mongodb-shell-complete-workflow

1 - Setup Trigger & run the MongoDB Shell script

With your trigger in place (be it Manual, Scheduled, Callable etc) add a MongoDB Shell connector. Set the operation to 'Run script'.

Set the 'Script' value to be:

myCursor = db.listingsAndReviews.find( { "beds": 18 } );
while (myCursor.hasNext()) {
EJSON.stringify(myCursor.next());
}
mongodb-shell-step-1

USER TIP: When working on a workflow, it is useful to set the 'Options' to 'Verbose' to see more feedback in the workflow step output. Once you are happy that the step is functioning as intended, set the 'Options' to be 'Quiet' so that only the mongosh command output appears in the workflow step output. That also makes it easier to programmatically access the required output because it will appear in a consistent location.

Feel free to re-name your steps as you go along to make things clearer for yourself and other users. The operation names themselves often suffice.

This step has successfully found and listed accommodations with 18 beds available.

mongodb-shell-step-1

BEST PRACTICES: Whenever you do decide to create your own workflow, please make sure you take a look at our managing data best practices guide.

All Operations

Latest version:

1.0

Run script

Run one or more MongoDB JavaScript commands against the authenticated database.