Skip to main content

​
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
​
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

PlaceholderDescription
{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.
​
DESTINATION_TOPIC
string
MQTT topic to publish operation status.

​
Writing Data

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}}}"
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 EquivalentMongoDB CLEAN Syntax
SELECT *{}
WHERE a = 1filter: "{\"a\": 1}"
WHERE a > 10filter: "{\"a\": {\"$gt\": 10}}"
ORDER BY a DESCsort: "a desc"
LIMIT 10limit: 10
SELECT a, bprojection: "a, b"

​
Connection String Examples

ScenarioConnection String
Localmongodb://localhost:27017/iot
Authenticatedmongodb://user:password@host:27017/iot?authSource=admin
Replica Setmongodb://host1:27017,host2:27017/iot?replicaSet=rs0
Atlasmongodb+srv://user:password@cluster.mongodb.net/iot

​
Troubleshooting

  • 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
  • Verify username and password in connection string
  • Check authSource parameter matches authentication database
  • Verify user has permissions on target database
  • 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.