# MongoDB

## Overview

**Document database support** is provided using the **MongoDB Publisher Transport.** Processed events are published to a specified MongoDB database collection.

The events are serialised using a [document formatter](#document-formatter) serialiser or a custom transformer implementation.

This transport is designed to facilitate efficient data publishing into MongoDB with customisable serialisation options.

Some key features are:

1. <mark style="color:green;">**MongoDB integration**</mark>\
   Sends processed events to a defined MongoDB collection.
2. <mark style="color:green;">**Serialiser options**</mark>\
   Uses a default Document Formatter serialiser or allows custom serialisation.

{% hint style="info" %}
**Driver details:** [org.mongodb:mongodb-driver-sync:4.8.1](https://mvnrepository.com/artifact/org.mongodb/mongodb-driver-sync/4.8.1)
{% endhint %}

## Examples & DSL attributes

This example sets up the MongoDB Publisher Transport to send events to a local MongoDB instance (`localhost:27017`).

It stores data in the `customerdb` database and `emea_customers` collection, using ordered inserts.

Authentication is done with the `joule` user and SCRAM-SHA-1 mechanism. Events are serialised individually (not in batches) with `Base64` encoding and `application/octet-stream` content type. SSL is disabled.

<pre class="language-yaml"><code class="lang-yaml"><strong>mongodbPublisher:
</strong>  servers:
    localhost: 27017
  enable ssl: false

  database: customerdb
  collection: emea_customers
  ordered inserts: true

  credentials:
    user: joule
    password: password
    mechanism: SCRAM_SHA_1

  serializer:
    batch: false
    formatter:
      documentFormatter:
        contentType: application/octet-stream
        encoding: base64
</code></pre>

### Attributes schema

<table><thead><tr><th width="193">Attribute</th><th width="217">Description</th><th width="219">Data Type</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>database</td><td>Name of database</td><td>String</td><td>true</td></tr><tr><td>collection </td><td>Name of collection inserts will be applied to</td><td>String</td><td>true</td></tr><tr><td>ordered inserts</td><td>Hint to MongDB to insert documents using presented ordering</td><td><p>Boolean</p><p>Default: true</p></td><td>false</td></tr><tr><td>servers</td><td>Map of servers with associated ports</td><td>Map&#x3C;String,Integer></td><td>true</td></tr><tr><td>enable ssl</td><td>Enable SSL</td><td><p>boolean</p><p>Default: false</p></td><td>false</td></tr><tr><td>credentials</td><td>Credential configuration</td><td>See <a href="#credential-attributes-schema">Credential attributes</a> section</td><td>true</td></tr><tr><td>serializer</td><td>Serialisation configuration</td><td>See <a href="#serialisation-attributes-schema">Serialisation attributes</a> section</td><td>false</td></tr></tbody></table>

### Credential attributes schema

<table><thead><tr><th width="193">Attribute</th><th width="217">Description</th><th width="219">Data Type</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>username</td><td>Username</td><td>String</td><td>true</td></tr><tr><td>password</td><td>password</td><td>String</td><td>true</td></tr><tr><td>authentication database</td><td>Database to use to authenticate connected user</td><td><p>String</p><p>Default: admin </p></td><td>false</td></tr><tr><td>mechanism</td><td><p>Authentication mechanism</p><p></p><p>Options</p><ul><li>PLAIN</li><li>SCRAM_SHA_1</li><li>SCRAM_SHA_256</li></ul></td><td><p>String</p><p>Default: SCRAM_SHA_1</p></td><td>false</td></tr></tbody></table>

### **Serialisation** attributes schema

This topic provides configuration parameters available object serialisation process.&#x20;

<table><thead><tr><th width="200">Attribute</th><th width="220">Description</th><th width="222">Data Type</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td>transform</td><td>User provided implementation</td><td>CustomTransformer</td><td>false</td></tr><tr><td>formatter</td><td>This is used when a custom transformer is not provided. Useful when chaining Joule processes</td><td><p>Formatter</p><p>Default: documentFormatter (See Document Formatter)</p></td><td>false</td></tr><tr><td>contentType</td><td>Type of content to inform receiving application</td><td><p>String</p><p>Default: application/octet-stream</p></td><td>false</td></tr><tr><td>encoding</td><td>Payload encoding method</td><td><p>String</p><p>Default: base64</p></td><td>false</td></tr><tr><td>batch</td><td>Flag to batch multiple messages in to a single payload</td><td><p>Boolean</p><p>Default: false</p></td><td>false</td></tr></tbody></table>

### **Serialiser example**

The configuration below will serialise `StreamEvents` as MongoDB documents.

```yaml
mongodbPublisher:
  ...

  serializer:
    batch: false
    formatter:
      documentFormatter:
        contentType: application/octet-stream
        encoding: base64
```

## Document formatter

The **document formatter** in Joule is a built-in tool that converts `StreamEvents` into MongoDB's **Document** type.

This allows the processed events to be **formatted correctly before being inserted** into a MongoDB collection. The formatter ensures that the data is serialised in a way that MongoDB can **understand and store efficiently**.

## Additional resources

* Official MongoDB [documentation](https://www.mongodb.com/docs/)
* Official MongoDB [docker image](https://hub.docker.com/_/mongo)
* Mongo Compass [UI](https://www.mongodb.com/products/compass)&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fractalworks.io/joule/components/connectors/sinks/mongodb.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.