MongoDB Connector Reference

The following operations allow you to work with the MongoDB Connector.

Connection configurations

The MongoDB connector can be used to deal with two types of connections:

  • Connection URI (URI): The connection URI used to connect to the MongoDB database.

  • Connection Parameters: The parameters used for creating the connection URI. Following protocols are supported by the MongoDB connector.

  • Standard Connection Parameters (STANDARD)

  • DNS Seed List Connection Parameters (DSL)

There are different connection configurations that can be used for the above protocols. They contain a common set of configurations and some additional configurations specific to the protocol.

Types of MongoDB connections

The supported connection URI types and connection options are listed in the MongoDB Connection String documentation.

Common configs to all connection types

Parameter Name Type Description Default Value Required
Connection Name String A unique name to identify the connection. - Yes
Connection Type String The protocol used to connect to the MongoDB database.
Possible values:
  • STANDARD: The standard format of the MongoDB connection URI.
  • DSL: The DNS-constructed seed list format of the MongoDB connection URI.
  • URI: The complete connection URI containing the server details, credentials and the connection options.
- Yes
Database String The name of the database in the MongoDB server. - Yes

URI connection configs

Parameter Name Type Description Default Value Required
Connection URI String The complete connection URI containing the server details, credentials, and the connection options. - Yes

Sample Configuration of URI configs

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="uriConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>uriConnection</name>
        <connectionType>URI</connectionType>
        <connectionURI>mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB</connectionURI>
        <database>users</database>
    </mongodb.init>
</localEntry>

Common configs for STANDARD and DSL types

Parameter Name Type Description Default Value Required
Replica Set String If the mongod is a member of a replica set, this parameter specifies the name of the replica set. - No
Auth Source String The database name associated with the user’s credentials. - No
Auth Mechanism String The authentication mechanism that MongoDB will use for authenticating the connection. - No
Auth Mechanism Properties String Properties for the specified authorisation mechanism as a comma-separated list of colon-separated key-value pairs. - No
Gssapi Service Name String The Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances to which you are connecting. - No
W String Corresponds to the write concern w Option. - No
W Timeout MS Number The time limit (in milliseconds) of the write concern. - No
Journal String When this option used, the Micro Integrator requests an acknowledgement from MongoDB that the write operation has been written to the journal. This applies when the write concern is set to 'j'. - No
Maximum Pool Size Number The maximum number of connections in the connection pool. 100 No
Minimum Pool Size Number The minimum number of connections in the connection pool. 0 No
Maximum Idle Time MS Number The maximum number of milliseconds that a connection can remain idle in the pool before being removed and closed. - No
Wait Queue Multiple Number The maximum pool size is multiplied by this value to calculate the maximum number of threads that are allowed to wait for a connection to become available in the pool. - No
Wait Queue Timeout MS Number The maximum time in milliseconds that a thread can wait for a connection to become available. - No
SSL Boolean A boolean to enable or disables TLS/SSL for the connection. - No
SSL Invalid Host Names Allowed Boolean User name used to connect with the file server. - No
Connect Timeout TS Number The time in milliseconds for attempting a connection before timing out. For most drivers, the default is to never timeout. - No
Socket Timeout MS Number The time in milliseconds for attempting a send or receive on a socket before the attempt times out. For most drivers, the default is to never timeout. - No
Compressors String Comma-delimited string of compressors to enable network compression for communication between this client and a mongod/mongos instance. - No
Zlib Compression Level Number An integer that specifies the compression level when zlib is used for network compression. - No
Read Concern Level String The level of isolation. - No
Read Preference String Specifies the read preferences for this connection. - No
Maximum Staleness Seconds Number The maximum time (in seconds) a connection can remain stale before the client stops using it for read operations. - No
Read Preference Tags String Document tags as a comma-separated list or colon-separated key-value pairs. - No
Local Threshold MS Number The latency (in milliseconds) that is allowed when selecting a suitable MongoDB instance from the list of available instances. 15 No
Server Selection Timeout MS Number The time (in milliseconds) that is allowed for server selection before an exception is thrown. 30,000 No
Server Selection Try Once Boolean When true, the driver scans the MongoDB deployment exactly once after server selection fails and then either selects a server or raises an error. When false, the driver searches for a server until the serverSelectionTimeoutMS value is reached. Only applies for single-threaded drivers. true No
Heartbeat Frequency MS Number Controls the intervals between which the driver checks the state of the MongoDB deployment. The interval (in milliseconds) between checks, counted from the end of the previous check until the beginning of the next one. - No
App Name String Specify a custom app name. - No
Retry Reads Boolean Enables retryable reads. - No
Retry Writes Boolean Enable retryable writes. - No
UUID Representation String The type of UUID representation. - No

STANDARD connection configs

Parameter Name Type Description Default Value Required
Host String The name of the host. It identifies either a hostname, IP address, or unix domain socket. Defaults to 127.0.0.1 if not provided. 127.0.0.1 No
Port Number The port number. Defaults to 27017 if not provided. 27017 No
Seed List String A seed list is used by drivers and clients (like the mongo shell) for initial discovery of the replica set configuration. Seed lists can be provided as host:port pairs. This is used in replica sets and shared clusters. - No
Username String The user name to authenticate the database associated with the user. - No
Password String The password to authenticate the database associated with the user. - No

Sample configuration of STANDARD configs

Sample configuration of STANDARD (standalone) configs.

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="standaloneStandardConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>standaloneStandardConnection</name>
        <connectionType>STANDARD</connectionType>
        <host>localhost</host>
        <port>27017</port>
        <database>users</database>
        <username>administrator</username>
        <password>1234</password>
    </mongodb.init>
</localEntry>

Sample configuration of STANDARD (replica set) configs

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="replicaSetStandardConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>replicaSetStandardConnection</name>
        <connectionType>STANDARD</connectionType>
        <seedList>mongodb1.example.com:27317,mongodb2.example.com:27017</seedList>
        <database>users</database>
        <username>administrator</username>
        <password>1234</password>
        <authSource>aDifferentAuthDB</authSource>
        <ssl>true</ssl>
        <w>majority</w>
        <replicaSet>mySet</replicaSet>
        <retryWrites>true</retryWrites>
    </mongodb.init>
</localEntry>

DSL connection configs

Parameter Name Type Description Default Value Required
Host String The name of the host. It identifies either a hostname, IP address, or unix domain socket. - Yes
Username String The user name to authenticate the database associated with the user. - No
Password String The password to authenticate the database associated with the user. - No

Sample Configuration of DSL configs

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="dslConnection" xmlns="http://ws.apache.org/ns/synapse">
    <mongodb.init>
        <name>dslConnection</name>
        <connectionType>DSL</connectionType>
        <host>server.example.com</host>
        <database>users</database>
        <username>administrator</username>
        <password>1234</password>
        <authSource>aDifferentAuthDB</authSource>
        <retryWrites>true</retryWrites>
        <w>majority</w>
    </mongodb.init>
</localEntry>

Operations

The following operations allow you to work with the MongoDB connector. Click an operation name to see parameter details and samples on how to use it.

insertOne

Inserts a document into a collection. See the related insertOne documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Document JSON String A document to insert into the collection. - Yes

**Sample Configuration**

```xml
<mongodb.insertOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <document>{json-eval($.document)}</document>
</mongodb.insertOne>

```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "document": {
        "_id": "123",
        "name": "John Doe"
    }
}
```
insertMany

Inserts multiple documents into a collection. See the related insertMany documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Documents JSON String An array of documents to insert into the collection. - Yes
Ordered Boolean A boolean specifying whether the MongoDB instance should perform an ordered or unordered insert. true No

**Sample Configuration**

```xml
<mongodb.insertMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <documents>{json-eval($.documents)}</documents>
    <ordered>True</ordered>
</mongodb.insertMany>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "documents": [
        {
            "name": "Jane Doe",
            "_id": "123"
        },
        {
            "name": "Jane Doe",
            "_id": "1234"
        },
        {
            "name": "Jane Doe",
            "_id": "12345"
        }
    ]
}
```
findOne

Returns one document that satisfies the specified query criteria on the collection. If multiple documents satisfy the query, this method returns the first document according to the natural order. See the related find documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String Specifies query selection criteria using query operators. To return the first document in a collection, omit this parameter or pass an empty document ({}). {} No
Projection JSON String Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document. - No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No

**Sample Configuration**

```xml
<mongodb.findOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
</mongodb.findOne>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "name": "Jane Doe"
    }
}
```
find

Selects documents in a collection or view and returns a cursor to the selected documents. See the related find documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String Selection filter using query operators. To return all documents in a collection, omit this parameter or pass an empty document ({}). {} No
Projection JSON String Specifies the fields to return using projection operators. Omit this parameter to return all fields in the matching document. - No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No
Sort JSON String A document that defines the sort order of the result set. - No

**Sample Configuration**

```xml
<mongodb.find configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
</mongodb.find>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "name": "John Doe"
    }
}
```
updateOne

Updates a single document within the collection based on the filter. See the related updateOne documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String The selection criteria for the update. The same query selectors as in the find() method are available. Specify an empty document {} to update the first document returned in the collection. {} No
Update JSON String The modifications to apply. - Yes
Upsert Boolean Creates a new document if no documents match the filter. false No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No
Array Filters JSON String An array of filter documents that determine which array elements to modify for an update operation on an array field. - No

!!! Info
    Array Filters parameter should be in a JSON object format. See the example given below.

    ```
    {
        "collection": "TestCollection",
        "query": {
            "grades": {
                "$gte": 100
            }
        },
        "update": {
            "$set": {
                "grades.$[element]": 100
            }
        },
        "arrayFilters": {
            "element": {
                "$gte": 100
            }
        }
    }
    ```

**Sample Configuration**

```xml
<mongodb.updateOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <update>{json-eval($.update)}</update>
    <upsert>False</upsert>
</mongodb.updateOne>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "_id": "123"
    },
    "update": {
        "$set": {
            "name": "Jane Doe"
        }
    }
}
```
updateMany

Updates all documents that match the specified filter for a collection. See the related updateMany documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String The selection criteria for the update. The same query selectors as in the find() method are available. Specify an empty document {} to update all documents in the collection. {} No
Update JSON String The modifications to apply. - Yes
Upsert Boolean Creates a new document if no documents match the filter. false No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No
Array Filters JSON String An array of filter documents that determine which array elements to modify for an update operation on an array field. - No

!!! Info
    Array filters parameter should be in a JSON object format. See the example given below.

    ```
    {
        "collection": "TestCollection",
        "query": {
            "grades": {
                "$gte": 100
            }
        },
        "update": {
            "$set": {
                "grades.$[element]": 100
            }
        },
        "arrayFilters": {
            "element": {
                "$gte": 100
            }
        }
    }
    ```

**Sample Configuration**

```xml
<mongodb.updateMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
    <update>{json-eval($.update)}</update>
    <upsert>False</upsert>
</mongodb.updateMany>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "_id": "123"
    },
    "update": {
        "$set": {
            "name": "Jane Doe"
        }
    }
}
```
deleteOne

Removes a single document from a collection. See the related deleteOne documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String Specifies deletion criteria using query operators. Specify an empty document {} to delete the first document returned in the collection. {} No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No

**Sample Configuration**

```xml
<mongodb.deleteOne configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
</mongodb.deleteOne>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "name": "Jane Doe"
    }
}
```
deleteMany

Removes all documents that match the query from a collection. See the related deleteMany documentation for more information.

Parameter Name Type Description Default Value Required
Collection String The name of the MongoDB collection. - Yes
Query JSON String Specifies deletion criteria using query operators. To delete all documents in a collection, pass in an empty document ({}). {} No
Collation JSON String Collation allows users to specify language-specific rules for string comparison, such as rules for letter case and accent marks. - No

**Sample Configuration**

```xml
<mongodb.deleteMany configKey="connectionURI">
    <collection>{json-eval($.collection)}</collection>
    <query>{json-eval($.query)}</query>
</mongodb.deleteMany>
```

**Sample Request**

```json
{
    "collection": "TestCollection",
    "query": {
        "name": "John Doe"
    }
}
```
Top