Configuring an ADF Linked Service Connection for Azure Cosmos DB for MongoDB
For information on how to enable a connection for use with linked services, see Configuring a Linked Service Connection.
After selecting Azure Cosmos DB for MongoDB from the Linked Service Type dropdown, the form required for creating an Azure Cosmos DB for MongoDB Linked Service will appear.
The Azure Cosmos DB for MongoDB option is offered on connections that use the Azure Cosmos DB for MongoDB System Type.
Datasets, Sources and Sinks
An Azure Cosmos DB for MongoDB connection serves the source system, the landing area and the persistent landing area stages.
The dataset addresses each object as a collection, taking the collection name from the TargetObjectName parameter.
Each Azure Cosmos DB for MongoDB object is copied whole from its collection. The copy has no source query and passes the TargetSchemaName and TargetObjectName parameters to the dataset.
The copy source reads the setting keys below from the object's settings. Each key is a setting of the Setting Editor's Azure group, in the section Data Factory Copy Source Members, with the label the table names. These settings are blank by default. A value reaches an object as a Setting Override on that object. Add on the Azure group's Overrides tab opens the Add Setting Override form, where the Attribute Type is Object, the Connection and the Object select the object, the Setting is picked by its label (shown as Filter (Data Factory Copy Source Members)), and the Override Value holds the member's text. A key that is empty or holds the default in the table is not written to the copy source.
| Setting Key | Label | ADF Property | Default |
|---|---|---|---|
filter | Filter | filter | No default |
batchSize | Batch Size | batchSize | 100 |
cursorMethods.project | Cursor Project | cursorMethods.project | No default |
cursorMethods.sort | Cursor Sort | cursorMethods.sort | No default |
cursorMethods.limit | Cursor Limit | cursorMethods.limit | 0 |
cursorMethods.skip | Cursor Skip | cursorMethods.skip | 0 |
As a landing area or persistent landing area in a Data Factory or Fabric data pipeline project, the connection is the target of the copy. The copy sink writes to the collection the dataset names, and the copy passes the TargetSchemaName and TargetObjectName parameters to the dataset.
The sink carries no pre copy script. Documents are inserted into the collection by default, and replaced by key when the object's write behavior setting is upsert. The write behavior setting is the writeBehavior setting key of the object. The write batch size and the other sink members keep their defaults.
Choosing an Authentication Method
| Method | Credentials | Additional Settings |
|---|---|---|
| Connection String | The account name and key inside the Connection String | Server Version Above 3.2 (optional) |
Recommendation: Store the Connection String in Azure Key Vault rather than entering it as plaintext, since it carries the account key.
Complete Example: Connection String with Azure Key Vault
| Field | Example Value |
|---|---|
| Connect via Integration Runtime | AutoResolveIntegrationRuntime |
| Database Name | sales |
| Azure Key Vault Linked Service | bfx-kv |
| Secret Name (for Connection String) | BFX-SRC-CosmosMongoConnectionString |
The secret holds the whole connection string, for example mongodb://contoso-mongo:<password>@contoso-mongo.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb.
Required Fields
Common Required Fields
An Azure Cosmos DB for MongoDB Linked Service connection uses a single Authentication Type, so the same fields are required on every connection.
These common required fields are:
Connect via Integration Runtime
Connect via Integration Runtime names the integration runtime for an Azure Cosmos DB for MongoDB Linked Service connection.
The default value is AutoResolveIntegrationRuntime.
To use a custom runtime, select one of the Azure Integration Runtimes saved in BimlFlex settings, or select + New and enter the name of the runtime.
A runtime added through + New is saved to the custom integration runtimes.
The custom values that appear in this dropdown can be maintained in Settings under Azure - AzureIntegrationRuntime.
The runtime is stored in the connection's LS_ConnectVia_IntegrationRuntime column. Any value other than AutoResolveIntegrationRuntime is written to the linked service as the runtime it connects through.
Azure Data Factory connects to Azure Cosmos DB for MongoDB through the Azure integration runtime or a self-hosted integration runtime. The Microsoft documentation names the self-hosted integration runtime for a data store located in a private network.
Connection String
The Connection String identifies the Azure Cosmos DB for MongoDB account and carries the account name and key, in the account form the Microsoft documentation gives, mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<cosmosdb-name>@ (for example, mongodb://contoso-mongo:<password>@contoso-mongo.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb).
The Connection String field accepts the value as plaintext in the LS_ConnectionString column, or an Azure Key Vault reference on the Connection String (Azure Key Vault) tab, stored in the LS_ConnectionStringKVS_ fields, that resolves to the connection string at runtime. It maps to the ADF connectionString property.
It is suggested that Azure Key Vault be used in place of manually entering the Connection String.
Database Name
The Database Name names the Azure Cosmos DB for MongoDB database the connector reads from (for example, sales).
It is stored in the connection's LS_Db column and maps to the ADF database property.
Server Version Above 3.2
The Server Version Above 3.2 checkbox marks an account whose server version is above 3.2. It is unticked by default. Ticking it stores the isServerVersionAbove32 key in the connection's additional settings, and the linked service carries the server version member as true. Left unticked, nothing is stored and the linked service carries no server version member, which the service reads as false.
Azure Data Factory Linked Service Additional Information
For additional information on ADF Azure Cosmos DB for MongoDB Linked Service and its connection requirements see the Azure Data Factory Azure Cosmos DB for MongoDB Connector documentation.