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:
-
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:
- Press if you're using Martini Desktop; if Martini Online.
- Start typing
mongodb
in the dialog's search box. - After a few key presses the MongoDB Service option will appear. When it does, press and the wizard will also appear.
-
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
-
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.
Here's a breakdown of its primary components:
-
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. -
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.
-
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. -
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. -
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.
-
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.
Depending on the issue that's detected Martini may also appear with suggestions to fix the errors:
If Martini detects an error with an operator, the popups will also make suggestions on what fields to add:
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 .
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 |
|
To allow for Gloop to use input properties for this document, change this to:
1 2 3 |
|
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 |
|
As you modify the BSON and add parameterized inputs, the Input/Output view will change as shown below:
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.