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