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

## Basic Syntax

```lot theme={null}
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

<ParamField path="CONNECTION_STRING" type="string" required>
  MongoDB connection URI. Format: `mongodb://user:password@host:port/database?options`
</ParamField>

<AccordionGroup>
  <Accordion title="Optional Settings">
    <ParamField path="DATABASE" type="string">
      Target database name (can also be specified in connection string).
    </ParamField>
  </Accordion>
</AccordionGroup>

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

  ```lot theme={null}
  WITH CONNECTION_STRING GET SECRET "MONGO_CONNECTION_STRING"
  ```

  See [Environment Variables & Secrets](/mqtt-broker/secrets-and-env) for setup and usage.
</Warning>

***

## CLEAN Query Format

MongoDB routes use the CLEAN format for simplified document insertion:

```lot theme={null}
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

<ParamField path="SOURCE_TOPIC" type="string" required>
  MQTT topic pattern that triggers the INSERT. Supports wildcards.
</ParamField>

<ParamField path="QUERY" type="string" required>
  CLEAN format query for document insertion.
</ParamField>

<AccordionGroup>
  <Accordion title="Optional Settings">
    <ParamField path="DESTINATION_TOPIC" type="string">
      MQTT topic to publish operation status.
    </ParamField>
  </Accordion>
</AccordionGroup>

***

## Writing Data

<Tabs>
  <Tab title="Basic Document Storage">
    Store sensor readings as documents:

    ```lot theme={null}
    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}}}"
    ```
  </Tab>

  <Tab title="Structured Documents">
    Create structured documents with specific fields:

    ```lot theme={null}
    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 theme={null}
    {"temperature": 23.5, "humidity": 65}
    ```

    **Stored document:**

    ```json theme={null}
    {
      "sensor_id": "temp001",
      "temperature": 23.5,
      "humidity": 65,
      "recorded_at": "2025-01-15T10:30:00Z"
    }
    ```
  </Tab>

  <Tab title="Multiple Collections">
    Route to different collections based on topic:

    ```lot theme={null}
    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}}}"
    ```
  </Tab>

  <Tab title="Replica Set">
    Connect to a MongoDB replica set:

    ```lot theme={null}
    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}}}"
    ```
  </Tab>
</Tabs>

<Info>
  **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/lot-language/models/overview) directly to this route. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:

  ```lot theme={null}
  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.
</Info>

***

## 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 theme={null}
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Authentication Failed">
    * Verify username and password in connection string
    * Check authSource parameter matches authentication database
    * Verify user has permissions on target database
  </Accordion>

  <Accordion title="CLEAN Query Errors">
    * Verify collection name is valid
    * Check placeholder names match topic structure
    * Ensure document structure is valid JSON
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Storage Routes Overview" icon="database" href="./overview">
    Compare all storage options.
  </Card>

  <Card title="OpenSearch Route" icon="magnifying-glass" href="./opensearch">
    Configure OpenSearch for search and analytics.
  </Card>
</CardGroup>