Skip to content

Toro Cloud Dev Center


MongoDB services

A MongoDB service is a type of service that can be used to perform read and write operations against a MongoDB database.

Creating a MongoDB service

To create a MongoDB service, follow the steps below:

Creating a MongoDB service

Creating a MongoDB service

  1. Launch the MongoDB service wizard by right-clicking on the target package's code directory (or any of the directories underneath it) where you'd like to store the MongoDB service, and then select New > MongoDB Service.

    Launch the wizard using keyboard shortcuts only

    You can open the MongoDB service wizard using the wizard launcher. To do this:

    1. Press if you're using Martini Desktop; if Martini Online.
    2. Start typing mongodb in the dialog's search box.
    3. After a few key presses the MongoDB Service option will appear. When it does, press and the wizard will also appear.

    Launching the MongoDB service using the wizard launcher

    Launching Gloop MongoDB service using the wizard launcher

  2. In the wizard, specify the following details:

    • Location - where the MongoDB service will reside; its default value will be the directory where you started the wizard from
    • Name - the name of the MongoDB service
    • Connection Name - the name of the database connection that the service will connect to while developing the service, and by default when executing it
    • Database - the name of the MongoDB database that the service will connect to while developing the service, and by default when executing it
    • Collection - the name of the MongoDB collection that the service will connect to while developing the service, and by default when executing it
    • Query Type - the type of MongoDB operation the service will perform
  3. Click Finish.

Editing MongoDB services

After creating the MongoDB service, Martini will automatically open the service for you, and you will be shown the MongoDB service editor.

MongoDB service editor

MongoDB service editor

Here's a breakdown of its primary components:

  1. Connection drop-down

    The name of the database connection the MongoDB service will connect to when being executed. By clicking on the drop-down list, you will be able to choose the database connection you want to execute operations against. Only registered and started MongoDB databases will be selectable. You can change the target database at runtime by setting the input.$martiniConnectionPool input property to the name of another database connection.

  2. Type drop-down

    The specific type of operation that the service will execute. Currently, these are the supported types:

    Type Description
    Find One Used to get a single document from MongoDB based on the filter. When this is chosen, the editor will also show an extra text area which is used to enter an optional projection document.
    Find Many Used to get multiple documents from MongoDB based on the filter. When this is chosen, the editor will also show an extra text area which is used to enter an optional projection document. These types of services return an input cursor.
    Delete One Used to delete a single document from a collection based on the filter.
    Delete Many Used to delete multiple documents from a collection based on the filter.
    Replace One Used to replace a single document within a collection based on the filter.
    Update One Used to update a single document within a collection based on the filter. When this is chosen, the editor will also show an extra text area which is used to enter an update document.
    Update Many Used to update all documents that match the specified filter in a collection. When this is chosen, the editor will also show an extra text area which is used to enter an update document.
    Insert One Used to insert a single document to a collection.
    Insert Many Used to insert multiple documents that to a collection. These types of services return an output cursor.
    Aggregation Used to perform aggregation pipelines against a collection.

    More information on MongoDB queries

    You can learn more about MongoDB BSON by clicking on any of the links in the table above or by reading about the MongoDB query types here.

  3. Database drop-down

    This drop-down list lets you choose the database to perform the operation against. This will be used by default at runtime and while developing. This can be overridden at runtime by setting the input.$database input property.

  4. Collection drop-down

    This drop-down list lets you choose the collection to perform the operation against. This will be used by default at runtime and while developing. This can be overridden at runtime by setting the input.$collection input property.

  5. Database tree

    Displays the target database connection's databases (including their size on disk), collections (including the total number of documents it has), and a pre-determined Data model that represents the collection. This data model also shows the corresponding data type in the collection. The analysis which is performed to determine the properties within the model is very similar to how MongoDB's Compass app performs its Schema Analysis.

  6. Operation editor area

    This area will display different editors, depending on the MongoDB Service Type. These editors are used to enter BSON documents, which are very similar to JSON documents.

Testing and previewing BSON queries

If you aren't sure exactly what BSON you need, you can use the Database perspective in Martini Desktop to test your queries. Alternatively, you can right click on a MongoDB service in the Navigator, and choose Export > MongoDB Query.

MongoDB BSON editors

The BSON editors used by Martini offer a lot of features to make writing your BSON filters, projections, and updates easy.

BSON errors and warnings

If any of the BSON syntax is incorrect in Martini, then an icon will appear in the gutter of the editor where errors and warnings are detected, and the source of the issue will appear with yellow or red underlines. When you hover your mouse pointer over the icon (or the syntax issue itself), a tooltip will appear which will provide you with more information on what is wrong with the syntax.

Martini Desktop MongoDB editor with warnings and errors

Depending on the issue that's detected Martini may also appear with suggestions to fix the errors:

Martini Desktop MongoDB BSON editor with suggestions

If Martini detects an error with an operator, the popups will also make suggestions on what fields to add:

Martini Desktop MongoDB BSON editor with operator suggestion

Content-assist

As with most other editors within Martini, the MongoDB BSON editors contain a content-assist feature that will prompt you with suggestions. These suggestions include creating new and complete existing operators, and auto-completing field names. The content-assist popup also has comments that briefly describe the options. To launch the content-assist popup, press .

Martini Desktop MongoDB BSON editor with Content-Assist

Inputs and outputs

Like regular services, MongoDB services have inputs and outputs, too. As the type and filter changes (as well as the text in the optional Update and Projection text areas), the MongoDB service's inputs and outputs will change as well.

MongoDB services also have special input and output properties you can set and fetch at runtime. A table of the built-in input properties is below:

Property Type Applicable Operations Description
$martiniConnectionPool Input All The database connection name.
$database Input All The MongoDB database to use.
$collection Input All The MongoDB collection to use.
$clientSession Input All The MongoDB ClientSession to use against the service.
$upsert Input Replace One and Update Used to tell MongoDB whether the replacement is to be upserted to the collection or not.
replacement Input Replace One and Update The Gloop model that will replace the existing document in the collection.
deleteCount Output Delete The number of documents that were deleted by MongoDB after the operation was performed.
acknowledged Output Delete Determines whether the delete was acknowledged or not.
matchedCount Output Replace One and Update The number of documents in the collection that were matched by the filter.
modifiedCount Output Replace One and Update The number of documents modified by the replace operation (can be null).
upsertedId Output Replace One and Update If the replace resulted in an inserted document, this will be the _id of the inserted document, otherwise null.
insert Input Insert One The document to insert to MongoDB.
_id Output Insert One The _id of the inserted document, otherwise null.
batchSize Input Insert Many The size a batch must reach before inserting the documents to MongoDB (default 10,000).

Input properties

All of the input properties in the table above are within the input Gloop model input property.

Parameterized queries

Parameterized BSON is also supported in the MongoDB service editor. Parameters allow for flexible documents - arguments don't need to be hard-coded in the BSON document, you can specify their values by setting the parameters.

To add a parameterized input to the BSON document, simply replace the substitutable value in the command with a placeholder in this format {{<name-of-parameter>}}. After you have successfully re-structured the BSON document, the Gloop MongoDB service will have additional input properties that have the same name as the parameterized parameters. Below is an example:

1
2
3
{
    CategoryID : "Gloop"
}

To allow for Gloop to use input properties for this document, change this to:

1
2
3
{
    CategoryID : {{myInputProperty}}
}

By default, the input properties added will be of type Object. If you want your properties to be more specific, then you can add the type within the parameterized parameter by changing it to the format {{<name-of-parameter>:<data-type>}}. Below is an example:

1
2
3
{
    CategoryID : {{myInputProperty:string}}
}

As you modify the BSON and add parameterized inputs, the Input/Output view will change as shown below:

Input/Output view changing with BSON document

Input/Output view changing with BSON document

Create models from a collection

If you want to have a Gloop model that represents a MongoDB collection, you can right click on a collection in the Database tree, then select Export to Gloop Model.