> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Route

> Store MQTT data in MongoDB with flexible document schemas and CLEAN query format

## 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.

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

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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).

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your route definitions:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> WITH CONNECTION_STRING GET SECRET "MONGO_CONNECTION_STRING"
> ```
>
> See [Environment Variables & Secrets](/v2.14/mqtt-broker/secrets-and-env) for setup and usage.

***

## CLEAN Query Format

MongoDB routes use the CLEAN format for simplified document insertion:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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**

Store sensor readings as documents:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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}}}"
```

**Structured Documents**

Create structured documents with specific fields:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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`:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{"temperature": 23.5, "humidity": 65}
```

**Stored document:**

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "temp001",
  "temperature": 23.5,
  "humidity": 65,
  "recorded_at": "2025-01-15T10:30:00Z"
}
```

**Multiple Collections**

Route to different collections based on topic:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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}}}"
```

**Replica Set**

Connect to a MongoDB replica set:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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}}}"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/v2.14/lot-language/models/overview) directly to this route. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorStorage"
>         WITH TABLE "readings"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) 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:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
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](./overview)**
>
> Compare all storage options.

> **[OpenSearch Route](./opensearch)**
>
> Configure OpenSearch for search and analytics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.