MongoDB Route

MongoDB Overview

The MONGODB route stores MQTT messages as documents in MongoDB collections. It uses the CLEAN query format for simplified JSON syntax and supports flexible schemas for IoT data.

MongoDB is ideal for IoT data with varying schemas. Store sensor readings, events, and logs without defining rigid table structures upfront.

Basic Syntax

DEFINE ROUTE SensorDB WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "CLEAN:{collection: readings, document: {sensor_id: {sensor_id}, value: {value.json}, timestamp: {timestamp}}}"

Connection Configuration

MONGODB_CONFIG Parameters

CONNECTION_STRING

string

required

MongoDB connection URI. Format: mongodb://user:password@host:port/database?options

Optional Settings

DATABASE

string

Target database name (can also be specified in connection string).

Never hardcode credentials in production. Use environment variables and encrypted secrets to keep sensitive values out of your route definitions:

WITH CONNECTION_STRING GET SECRET "MONGO_CONNECTION_STRING"

See Environment Variables & Secrets for setup and usage.

CLEAN Query Format

MongoDB routes use the CLEAN format for simplified document insertion:

WITH QUERY "CLEAN:{collection: <name>, document: {<field>: <value>, ...}}"

CLEAN Placeholders

Placeholder	Description
`{value.json}`	Full JSON payload as embedded document
`{value.json.field}`	Specific field from JSON payload
`{timestamp}`	Message timestamp
`{source_topic}`	Original MQTT topic
`{field}`	Field extracted from topic path

Event Configuration

EVENT Parameters

SOURCE_TOPIC

string

required

MQTT topic pattern that triggers the INSERT. Supports wildcards.

QUERY

string

required

CLEAN format query for document insertion.

Optional Settings

DESTINATION_TOPIC

string

MQTT topic to publish operation status.

Writing Data

Basic Document Storage
Structured Documents
Multiple Collections
Replica Set

Store sensor readings as documents:

DEFINE ROUTE SensorStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://iot_user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "db/mongo/status"
        WITH QUERY "CLEAN:{collection: readings, document: {timestamp: {timestamp}, topic: {source_topic}, data: {value.json}}}"

Create structured documents with specific fields:

DEFINE ROUTE StructuredStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongodb.example.com:27017/iot"
        WITH DATABASE "iot"
    ADD EVENT StoreSensor
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "CLEAN:{collection: sensor_data, document: {sensor_id: {sensor_id}, temperature: {value.json.temperature}, humidity: {value.json.humidity}, recorded_at: {timestamp}}}"

Input at sensors/temp001/data:

{"temperature": 23.5, "humidity": 65}

Stored document:

{
  "sensor_id": "temp001",
  "temperature": 23.5,
  "humidity": 65,
  "recorded_at": "2025-01-15T10:30:00Z"
}

Route to different collections based on topic:

DEFINE ROUTE MultiCollection WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongodb.example.com:27017/iot"
        WITH DATABASE "iot"
    
    ADD EVENT StoreSensors
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "CLEAN:{collection: sensors, document: {topic: {source_topic}, data: {value.json}, ts: {timestamp}}}"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/#"
        WITH QUERY "CLEAN:{collection: alerts, document: {topic: {source_topic}, alert: {value.json}, ts: {timestamp}}}"
    
    ADD EVENT StoreEvents
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "CLEAN:{collection: events, document: {topic: {source_topic}, event: {value.json}, ts: {timestamp}}}"

Connect to a MongoDB replica set:

DEFINE ROUTE ReplicaSetStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongo1.example.com:27017,mongo2.example.com:27017,mongo3.example.com:27017/iot?replicaSet=rs0&authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreData
        WITH SOURCE_TOPIC "data/#"
        WITH QUERY "CLEAN:{collection: data, document: {topic: {source_topic}, payload: {value.json}, timestamp: {timestamp}}}"

Alternative: STORE IN with Models — Instead of writing EVENT queries, you can bind a model directly to this route. Every PUBLISH MODEL call automatically inserts a row — no query needed:

DEFINE MODEL SensorReading
    ADD STRING "sensor_id"
    ADD DOUBLE "value"
    STORE IN "SensorStorage"
        WITH TABLE "readings"

See Data Storage Overview for the full STORE IN workflow.

Reading Data

EVENTs also support read queries to retrieve data from the database. Publish a message to the event’s SOURCE_TOPIC, and the query result is published to DESTINATION_TOPIC. MongoDB read queries use the CLEAN format with filter, sort, and limit instead of SQL:

DEFINE ROUTE SensorDB WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "CLEAN:{collection: readings, filter: \"{\"sensor_id\": \"{payload}\"}\", sort: \"timestamp desc\", limit: 1}"

To trigger this query, publish the sensor ID to the source topic:

Topic:   db/query/latest
Payload: temp001

The matching document is published to db/result/latest, where your actions or external clients can consume it.

CLEAN Read Operators

SQL Equivalent	MongoDB CLEAN Syntax
`SELECT *`	`{}`
`WHERE a = 1`	`filter: "{\"a\": 1}"`
`WHERE a > 10`	`filter: "{\"a\": {\"$gt\": 10}}"`
`ORDER BY a DESC`	`sort: "a desc"`
`LIMIT 10`	`limit: 10`
`SELECT a, b`	`projection: "a, b"`

Connection String Examples

Scenario	Connection String
Local	`mongodb://localhost:27017/iot`
Authenticated	`mongodb://user:password@host:27017/iot?authSource=admin`
Replica Set	`mongodb://host1:27017,host2:27017/iot?replicaSet=rs0`
Atlas	`mongodb+srv://user:password@cluster.mongodb.net/iot`

Troubleshooting

Connection Failed

Verify CONNECTION_STRING is correct
Check MongoDB is running and accessible
Verify firewall allows connections on port 27017
For Atlas, ensure IP whitelist includes your server

Authentication Failed

Verify username and password in connection string
Check authSource parameter matches authentication database
Verify user has permissions on target database

CLEAN Query Errors

Verify collection name is valid
Check placeholder names match topic structure
Ensure document structure is valid JSON

Next Steps

Data Storage Routes Overview

Compare all storage options.

OpenSearch Route

Configure OpenSearch for search and analytics.

Quick Start

Developing and Managing Coreflux

Coreflux MQTT Broker

LoT Language

Product Updates

MongoDB Overview

Basic Syntax

Connection Configuration

MONGODB_CONFIG Parameters

CLEAN Query Format

CLEAN Placeholders

Event Configuration

EVENT Parameters

Writing Data

Reading Data

CLEAN Read Operators

Connection String Examples

Troubleshooting

Next Steps

Data Storage Routes Overview

OpenSearch Route

​MongoDB Overview

​Basic Syntax

​Connection Configuration

​MONGODB_CONFIG Parameters

​CLEAN Query Format

​CLEAN Placeholders

​Event Configuration

​EVENT Parameters

​Writing Data

​Reading Data

​CLEAN Read Operators

​Connection String Examples

​Troubleshooting

​Next Steps

Data Storage Routes Overview

OpenSearch Route

MongoDB Overview

Basic Syntax

Connection Configuration

MONGODB_CONFIG Parameters

CLEAN Query Format

CLEAN Placeholders

Event Configuration

EVENT Parameters

Writing Data

Reading Data

CLEAN Read Operators

Connection String Examples

Troubleshooting

Next Steps