Skip to content

MongoDB Database Node

Overview

The MongoDB Database Node enables you to perform MongoDB operations—such as querying, inserting, updating, and deleting records—directly within your Martini workflow.

For general details on database nodes and a list of supported databases (both NoSQL and SQL), see Workflow Database Node.

What You Will Learn

  • How to add and configure a MongoDB Database Node in your workflow
  • How to use MongoDB filters and projections with dynamic placeholders
  • How to map workflow properties to MongoDB query inputs and from outputs

When to Use This

Use this node when you need to:

  • Execute MongoDB operations (read/write) using your workflow.
  • Automate data flows between your workflow and an external MongoDB database.
  • Integrate MongoDB logic directly into your workflow for seamless backend automation.

See more use cases in Workflow Database Node: When To Use This.

Prerequisites

Before you start

  1. Set up a MongoDB database: You need a running MongoDB database to store and retrieve data for your workflow.

    MongoDB Version Requirements

    Ensure you are using a MongoDB version supported by Martini. See MongoDB Version Compatibility for details.

  2. Install Martini Designer: Martini Designer is required to build and manage workflows.
    See: Installation guide

  3. Configure a MongoDB database connection in Martini: Martini needs to know how to connect to your database.
    See: Creating and Configuring a MongoDB Connection in Martini

While using this feature

  1. Create a Martini package: Packages organize your workflow and related resources.
    See: How to Create a Package

  2. Create a workflow: The workflow is where you'll add and configure the MongoDB Database Node.
    See: Workflow creation steps

Getting Started

The simplest way to understand using the MongoDB Database Node in Martini is to start with an Insert One operation. This covers the basics of mapping workflow properties to document fields and retrieving the generated document ID, which is a pattern you can apply to other operations.

Example: Insert One Guest Document

Suppose you want to add a guest to your guests collection with the fields firstname, lastname, and email. Here's how you do it:

  1. Ensure your MongoDB database has a guests collection (no need to predefine fields).
  2. Add workflow input properties: guestFirstName, guestLastName, guestEmail.
  3. Add a MongoDB Database Node to your workflow and connect it to your Start Trigger.

  4. In the Query Tab, set:

    • Connection Name: your configured MongoDB connection name
    • Type: Insert One
    • Database: your database name
    • Collection: guests
    • See Query Tab for details on each field.

    • In the Data Mapping Panel, map your workflow properties to the corresponding fields inside the input model:

    • guestFirstName → input.firstname

    • guestLastName → input.lastname
    • guestEmail → input.email
    • See Input Mapper Layout and Custom Input Properties for more on mapping.

  5. Map the output property:

    • _id → newGuestId (the generated document ID)
    • See Output Mapper Layout for details on output mapping.

  6. Run your workflow. The guest is inserted, and you can use newGuestId in subsequent steps.

This example demonstrates the core mapping concepts: workflow properties become document fields, and output properties (like _id) let you use results in your workflow. Once you grasp this, you can apply the same mapping logic to Find, Update, and Aggregate operations.

Adding a MongoDB Database Node

To add a MongoDB Database Node to your workflow:

  1. Add a new Database Node by following these steps.

  2. Click the expand icon on the node.
    What you'll see: A configuration panel appears with two tabs—Query and Data Mapping—where you configure your database interaction.

  3. Once your node is added, proceed to the Configuration Panel section to set up your MongoDB operations and data mappings.

Configuration Panel

The Configuration Panel is where you set up your MongoDB operation and map workflow properties to database fields. This panel lets you control how your workflow interacts with MongoDB.

Initial Setup Steps

  1. Go to the Query Tab.
    What you'll see: Fields for selecting your connection, operation type, database, collection, and MongoDB-specific configuration options.

  2. In the Connection Name field, select your configured MongoDB connection from the dropdown.
    Martini will recognize your connection type and prepare the node for MongoDB configuration.

  3. Once your connection is selected, you can configure the specific MongoDB database, collection, operation and data mappings as described in the following sections.

The Configuration Panel contains two tabs: Query Tab and Data Mapping Panel. For a full walkthrough, see Configuration Panel.

Query Tab

This panel allows you to set up your MongoDB operation and define any placeholders you need for dynamic values.

Fields and Configuration:

Property Required Example Value Description
Connection Name Yes mongodb-main Name of your MongoDB connection.
Martini will automatically detect the connection type.
Type Yes Insert One MongoDB operation type.
Supported types:
- Find One
- Find Many
- Insert One
- Insert Many
- Update One
- Update Many
- Delete One
- Delete Many
- Aggregate
- Replace One
Database Yes usersdb The name of your MongoDB database.
Collection Yes users The name of your MongoDB collection (similar to a table in SQL).
Filter No { company: "Acme Company" } Criteria to select documents.
Only available for read operations (e.g., Find, Aggregate).
Placeholders No {{property:string}}
Example: { company: {{company:string}} }		 Use placeholders to insert workflow values dynamically into filters, aggregate pipelines, update documents, or projections.
For example, {{company:string}} becomes the input property company in the Data Mapping Panel.
See Custom Input Properties for details.
Projection No { "name": 1, "email": 1 } Fields to include (1) or exclude (0) in results.
Only available for read operations.

Data Mapping Tab

The Data Mapping Tab allows you to access the MongoDB Database Node's Mapper Panel. It uses Martini's standard Data Mapper Panel with the Double Mapper Layout to connect and transform data between your workflow and your MongoDB database.

The Data Mapping Panel visually connects workflow properties to MongoDB database node inputs and outputs. You can map workflow inputs to the MongoDB database node inputs and route outputs from executed operations back into your workflow. You can also declare new properties and set expressions.

Getting Started: Data Mapping

  1. Click the expand icon on your Database Query Node.
  2. The panel appears in the lower half of the Workflow Designer.

Expected result: The Mapper Panel shows two main areas: Input (left) and Output (right).

Input Mapper Layout (Left)

1
2
3
4
5
6
7
8
9
| Workflow Properties      | Mapping Lines | MongoDB Database Node Input Properties |
|--------------------------|---------------|----------------------------------------|
|                          |               | input Model                            |
|                          |               | +--$martiniConnectionPool              |
|                          |               | +--$database                           |
|                          |               | +--$collection                         |
|                          |               | +--$clientSession                      |
|        [input1]          |   ------->    | +--[customInputProperty1]               |
|        [input2]          |   ------->    | +--[customInputProperty2]               |

For Insert Operations: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
| Workflow Properties      | Mapping Lines | MongoDB Database Node Input Properties |
|--------------------------|---------------|----------------------------------------|
|                          |               | input Model                            |
|                          |               | +--$martiniConnectionPool              |
|                          |               | +--$database                           |
|                          |               | +--$collection                         |
|                          |               | +--$clientSession                      |
|                          |               | +--insert                              |
|        [input1]          |   ------->    | +-----[customInputProperty1]            |
|        [input2]          |   ------->    | +-----[customInputProperty2]            |

For complete details on using the Data Mapper Panel, including creating map lines, set expressions, and property management, see the Data Mapping Guide.

MongoDB Database Node Input Properties: Key Terms

Property Purpose
$martiniConnectionPool Allows you to set the connection pool dynamically within the workflow. Defaults to the configured Martini connection pool if not set.
$database Allows you to set the database name dynamically within the workflow. Defaults to the configured database if not set.
$collection Allows you to set the collection name dynamically within the workflow. Defaults to the configured collection if not set.
$clientSession Optional. Allows you to explicitly define a client session if you already have one prior to using the database node. If not set, Martini will create a new session automatically.
insert Insert operations only. A model containing the document structure for Insert One and Insert Many operations. Custom input properties for document fields appear inside this model.
[customInputProperty] Custom input properties generated from placeholders used in filters, aggregate pipelines, updates, and projections. For Insert operations, these properties appear inside the insert model. For other operations, they appear directly under the input model. Workflow properties can be mapped to these to dynamically set values needed for MongoDB operations at runtime.
See Custom Input Properties for details.
Custom Input Properties

Custom input properties (represented as [customInputProperty] in this documentation) are generated from placeholders you define in various parts of your MongoDB node configuration. These placeholders allow you to dynamically inject workflow values into your MongoDB operations at runtime.

Placeholders can be used in:

  • Filters (for read and write operations)
  • Aggregate pipelines (for aggregate operations)
  • Update documents (for update operations)
  • Projections (for read operations)

Placeholder syntax: {{propertyName:dataType}}

Examples of placeholder usage:

In Filters: 

1
{ "company": {{company:string}}, "active": {{isActive:boolean}} }
Generates input properties: company (string), isActive (boolean)

In Aggregate Pipelines: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
[
    {
        "$match": {"userId": {{userId:string}}}
    },
    {
        "$group": {
            "_id": "$department",
            "minSalary": {"$min": {{minThreshold:number}}}
        }
    }
]
Generates input properties: userId (string), minThreshold (number)

In Update Documents: 

1
2
3
4
5
6
{
    "$set": {
        "status": {{status:string}},
        "lastModified": {{timestamp:date}}
    }
}
Generates input properties: status (string), timestamp (date)

In Projections: 

1
2
3
4
5
{
    "name": 1,
    "userId": {{includeUserId:integer}},
    "email": {{showEmail:integer}}
}
Generates input properties: includeUserId (integer), showEmail (integer)

In the Data Mapping Panel, these generated properties appear as custom input properties that you can map workflow values to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
| Workflow Properties      | Mapping Lines | MongoDB Database Node Input Properties |
|--------------------------|---------------|----------------------------------------|
|                          |               | input Model                            |
|                          |               | +--$martiniConnectionPool              |
|                          |               | +--$database                           |
|                          |               | +--$collection                         |
|                          |               | +--$clientSession                      |
|        [companyName]     |   ------->    | +--company                             |
|        [activeStatus]    |   ------->    | +--isActive                            |
|        [userIdValue]     |   ------->    | +--userId                              |

For write operations, you'll also see structured input properties for the document body. For Insert operations, these properties appear inside an insert model:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
| Workflow Properties      | Mapping Lines | MongoDB Database Node Input Properties |
|--------------------------|---------------|----------------------------------------|
|                          |               | input Model                            |
|                          |               | +--$martiniConnectionPool              |
|                          |               | +--$database                           |
|                          |               | +--$collection                         |
|                          |               | +--$clientSession                      |
|                          |               | +--insert                              |
|        [companyName]     |   ------->    | +-----name                             |
|        [industry]        |   ------->    | +-----industryCategory                 |

This flexible placeholder system enables powerful data-driven MongoDB operations where your workflow can dynamically control query criteria, update values, projection fields, and aggregate pipeline parameters based on runtime data.

Output Mapper Layout (Right)

The output mapper shows the data returned from your MongoDB operations. Different MongoDB operation types produce different outputs that you can map to workflow properties for further processing.

For complete details on using the Data Mapper Panel, including creating map lines, set expressions, and property management, see the Data Mapping Guide.

Below are examples of how output properties appear for different MongoDB operations. You can map these properties to workflow outputs for further processing.

Insert Operations

Insert One: 

1
2
3
4
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      output                     |               |                           |
|      +--_id                     |   ------->    |      [newDocumentId]      |

Insert Many: 

1
2
3
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      outputCursor               |   ------->    |      [workflowOutput]     |

Output Properties for Insert {#output-properties-insert}

Property Description
_id Insert One The generated ID from the inserted document. Map this to a workflow property to use the new document's ID in later steps.
outputCursor Insert Many A cursor object containing the results of the batch insert operation, including the IDs of all inserted documents. You can iterate through these using a Repeat Node for batch processing of insert results. See Batch Write Operations for detailed examples.

Find Operations

Find One: 

1
2
3
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      output                     |   ------->    |      [workflowOutput]     |

Find Many: 

1
2
3
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      inputCursor                |   ------->    |      [workflowOutput]     |

Output Properties for Find

Property Description
output Find One only. A model containing the single document returned by your MongoDB operation. You can access the document fields directly in subsequent workflow nodes.
inputCursor Find Many only. A cursor object containing multiple documents returned by your MongoDB operation. You can iterate through these using a Repeat Node. See Batch Read Operations for detailed examples.

Update Operations

1
2
3
4
5
6
7
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      output                     |               |                           |
|      +--matchedCount            |   ------->    |      [workflowOutput]     |
|      +--modifiedCount           |   ------->    |      [workflowOutput]     |
|      +--acknowledged            |   ------->    |      [workflowOutput]     |
|      +--upsertedId              |   ------->    |      [workflowOutput]     |

Output Properties for Update

Property Description
matchedCount Number of documents matched by the update query.
modifiedCount Number of documents actually modified.
acknowledged Boolean indicating if the update was acknowledged by MongoDB.
upsertedId The ID of the upserted document, if an upsert occurred.

Aggregate Operations

1
2
3
| Database Node Output Properties | Mapping Lines | Workflow Output Properties |
|---------------------------------|---------------|---------------------------|
|      inputCursor                |   ------->    |      [workflowOutput]     |

Output Properties for Aggregate

Property Description
inputCursor A cursor object you can iterate through using the Repeat Node for batch processing of aggregate results. See Batch Read Operations for detailed examples.

Working with Batch Operations and Cursors

MongoDB Database Nodes support batch operations for efficient processing of large datasets. You can use cursors with Repeat Nodes to iterate through results or perform bulk operations.

Other Batch Operations

For batch read and write operations with MongoDB and other database types, see:

Batch Delete Operations

Batch delete operations allow you to efficiently remove multiple documents from MongoDB collections based on specified criteria. This is particularly useful for data maintenance tasks like removing discontinued products.

Other Database Types

For batch delete operations with SQL databases and Cassandra, see Batch Delete Operations in the general Database Node guide.

Real-World Example: Bulk Product Status Cleanup

Business scenario: Your e-commerce system needs to periodically clean up products with a specific status. When a product status becomes invalid (like "discontinued"), all products with that status need to be removed from the active inventory database to maintain data quality and system performance.

Sample input data: 

1
"discontinued"

Sample existing data in MongoDB collection: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// Products collection
[
  {
    "_id": { "$oid": "507f1f77bcf86cd799439011" },
    "name": "Laptop Pro 2019",
    "price": 899.99,
    "category": "Electronics",
    "status": "discontinued"
  },
  {
    "_id": { "$oid": "507f1f77bcf86cd799439012" },
    "name": "Coffee Mug",
    "price": 12.5,
    "category": "Kitchen",
    "status": "active"
  },
  {
    "_id": { "$oid": "507f1f77bcf86cd799439013" },
    "name": "Vitamins",
    "price": 29.99,
    "category": "Health",
    "status": "discontinued"
  },
  {
    "_id": { "$oid": "507f1f77bcf86cd799439014" },
    "name": "Toy Robot",
    "price": 19.99,
    "category": "Toys",
    "status": "discontinued"
  }
]

Expected result: Products with status "discontinued" are removed from the collection, with confirmation of deletion counts.

Setting Up Batch Delete

Step 1: Prepare Your Data Source

  1. Create your input and output data in one of these ways:

    • Workflow Input and Output: Create a String Property named statusToDelete for input and specific output properties for the deletion results:

      • Open the Workflow Input/Output panel by clicking the Configure Input/Output Properties icon in the toolbar
      • For Input: In the Input Properties section, click Add , select String from the dropdown and name it statusToDelete

      • For Output: In the Output Properties section, create the following properties:

      • Click Add , select Long from the dropdown and name it totalDeleted

      • Click Add , select Boolean from the dropdown and name it deletionAcknowledged

    • A String property from a previous node containing the product status to delete, and Long/Boolean properties to capture the deletion results

Step 2: Configure Your MongoDB Delete Operation

  1. Add a Database Node and configure the connection:

    • Add a Database Node to your workflow
    • Click the expand icon on your Database Query Node to open the configuration panel
    • Ensure you are in the Query Tab (should be selected by default)
    • Select your MongoDB connection from the Connection Name dropdown

  2. Configure the delete operation in the Query Tab:

    • Type: Select "Delete Many"
    • Database: Enter your database name (e.g., inventory)
    • Collection: Enter your collection name (e.g., products)
    • Filter: { "status": {{status:string}} }

  3. Configure Filter Placeholders:

The placeholder {{status:string}} creates an input property named status that will appear in the Data Mapping Panel, allowing you to dynamically set which status to delete.

Step 3: Handle Results

  1. Open the Data Mapper Panel on your Database Node (if not already open)

    • Click the expand icon on your Database Query Node
    • Click the Data Mapping Tab

  2. Map the input and output properties:

    • Input mapping: In the Input Mapper Layout, drag statusToDelete to status (the input property generated from your filter placeholder. You will have to expand the input model on the Database Node Input Properties to see this.)

    • Output mapping: In the Output Mapper Layout:

      • Drag output.deletedCount to totalDeleted
      • Drag output.acknowledged to deletionAcknowledged

Step 4: Save and Run Your Workflow

  1. Save your workflow:

    • Press Ctrl+S (Windows/Linux) or Cmd+S (Mac)
    • Or click the Save button in the toolbar

  2. Run your workflow:

    • Click the Run button in the toolbar
    • In the Input/Output dialog that appears, provide a value for statusToDelete (e.g., "discontinued")
    • Click Run to execute the workflow

Expected Workflow Output: 

1
2
3
4
{
  "totalDeleted": 3,
  "deletionAcknowledged": true
}

Result: Your workflow efficiently removes all products with the specified status from your MongoDB collection, providing feedback on the number of documents deleted and confirmation that the operation was acknowledged by MongoDB.

Troubleshooting

Problem Detection Cause Fix
Connection error Node fails with connection error Invalid or missing MongoDB connection Verify connection settings in Martini
Placeholder not mapped Workflow fails or returns null Required input property not mapped Map all placeholders in Data Mapping Panel
Query returns no results Output is empty Filter does not match any documents Check filter criteria and mapped properties

See Workflow Database Node: Troubleshooting for more.

Helpful Resources