Skip to content

MongoDB Route

Feature Since Version Notes
MongoDB Route >v1.6.3 Stores MQTT payloads in MongoDB.

1. Overview

The MongoDB Route in the Coreflux MQTT broker enables the direct storage of MQTT message payloads into a MongoDB database.

For practical examples of LOT Routes, check out the Routes examples in the LOT Samples Repository. This route is ideal for applications that require a flexible, schema-less data storage model, allowing for rich JSON documents to be stored efficiently. It's perfectly suited for IoT platforms, content management systems, and any application leveraging a document-oriented database.

2. Key Features

  • Native Document Storage: Stores JSON payloads directly as BSON documents in MongoDB.
  • Connection String Based: Uses the standard MongoDB connection string format for maximum flexibility and compatibility.
  • High Performance: Leverages the official MongoDB driver for efficient and asynchronous database operations.
  • Simple Configuration: Requires only a connection string and a target database name.

3. Route Configuration

A route is configured using the addRoute command with TYPE MONGODB. The target collection for storage is specified in the PUBLISH or STORE action that utilizes the route.

Currently, the MongoDB route is configured using a connection string.

Example MongoDB Route Configuration

DEFINE ROUTE mongo_route WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb+srv://<username>:<password>@<cluster-uri>/<database>?tls=true&authSource=admin&replicaSet=<replica-set>"
        WITH DATABASE "admin"

Adding the Route via MQTT Command

To deploy this route to the broker, use the -addRoute command by publishing to the $SYS/Coreflux/Command topic:

-addRoute DEFINE ROUTE mongo_route WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb+srv://<username>:<password>@<cluster-uri>/<database>?tls=true&authSource=admin&replicaSet=<replica-set>"
        WITH DATABASE "admin"

For more information about broker commands, see the MQTT Broker Commands documentation.

Deploying Routes with LOT Notebooks

Routes can also be created and deployed interactively using LOT Notebooks in Visual Studio Code. This provides a convenient way to develop, test, and document your routes.

To get started with LOT Notebooks:

  1. Install the LOT Notebooks extension in VS Code

  2. Create a new .lotnb file

  3. Add code cells with your route definitions

  4. Execute the cells to deploy directly to your broker

For detailed instructions, see the LOT Notebooks Getting Started Guide.

Explanation of Configuration Options

The configuration is provided within a MONGODB_CONFIG block.

  • CONNECTION_STRING: The standard MongoDB connection string used to connect to the database instance or cluster. This includes authentication, host information, and other connection options.

  • DATABASE: The name of the MongoDB database where the data will be stored.

4. Using Models for Structured Document Storage

To ensure data is stored in a consistent and predictable format, the MongoDB Route integrates seamlessly with LOT Models. Models serve as a schema and transformation layer, allowing you to convert raw MQTT messages into a structured JSON document before storage.

A Model defines the desired structure of your data. By using the STORE IN command within the model, you direct the broker to use a specific MongoDB route to save the resulting document into a collection. This approach effectively enforces a schema at the broker level for your schema-less database.

Automatic Collection Creation

When a Model stores a document via the MongoDB route, the broker will automatically create the target collection if it doesn't already exist.

Example: Storing Structured Sensor Events

1. The Model Definition

This model defines a schema for a sensor event. It captures the raw data, adds a timestamp, and prepares a structured document for storage. 

DEFINE MODEL MyModel COLLAPSED WITH TOPIC "MyModel"
    ADD "f_event_time" WITH TIMESTAMP "UNIX"
    ADD BOOL"bool" WITH TRUE
    ADD "data" WITH TOPIC "mapping/mydata" AS TRIGGER
    STORE IN "mongo_route"
        WITH TABLE "MyModelCollection"
How it works: - DEFINE MODEL MyModel...: Defines the model. - ADD "data" WITH TOPIC "mapping/mydata" AS TRIGGER: The model executes when a message arrives on this topic. - ADD ...: These lines add new fields to create a structured document. - STORE IN "mongo_route" ...: This command sends the final JSON document to the mongo_route to be inserted into the MyModelCollection collection. Note that WITH TABLE here specifies the collection name for MongoDB.

2. The Resulting MongoDB Document

When triggered, the model processes the data and sends a document to MongoDB that looks like this: 

{
  "_id": "63a5e3b4d8e9f2a1b3e4c5d6",
  "f_event_time": 1678886400,
  "bool": true,
  "data": {
    "sensor_id": "temp-01",
    "value": 25.5
  }
}
(Note: The _id is automatically generated by MongoDB. The content of data reflects the payload from the trigger topic.)