Azure Cosmos DB (NoSQL)

Azure Cosmos DB with the Core (NoSQL) API provides a flexible document database with global distribution capabilities. This guide covers configuring Cloud Replicator to use Cosmos DB NoSQL as a destination.

Overview

Cosmos DB NoSQL stores data as JSON documents in containers (collections). Cloud Replicator maps Business Central data to this structure:

Cosmos DB Concept	Business Central Mapping
Database	Configured database name
Container	Business Central table name (sanitized)
Partition Key	Company name field (`/_Company`)
Document ID	Primary key or SystemId
Document Body	Field values as JSON

Prerequisites

Before configuring Cosmos DB NoSQL:

Azure Subscription: Active Azure subscription
Cosmos DB Account: Account with Core (SQL) API created
Database: A database created within the account
Access Key: Primary or secondary key from the account

Creating a Cosmos DB Account

If you don't have a Cosmos DB account:

Step 1: Create Account in Azure Portal

Sign in to the Azure Portal (https://portal.azure.com)
Click "Create a resource"
Search for "Azure Cosmos DB" and select it
Click "Create"
Select Azure Cosmos DB for NoSQL (Core SQL API)

Step 2: Configure Basic Settings

Setting	Recommended Value
Subscription	Your subscription
Resource group	Create new or use existing
Account name	Unique globally (lowercase)
Location	Same region as Business Central
Capacity mode	Provisioned throughput or Serverless

Step 3: Configure Throughput (if Provisioned)

For Provisioned throughput mode:

Start with 400 RU/s for initial testing
Enable Autoscale for production workloads
Scale up based on replication volume

Step 4: Complete Creation

Click "Review + create"
Review settings and click "Create"
Wait for deployment (may take several minutes)

Step 5: Create a Database

Navigate to your Cosmos DB account
Go to "Data Explorer"
Click "New Database"
Enter a database ID (e.g., "BusinessCentralData")
Configure throughput (shared or dedicated)
Click "OK"

Step 6: Get Access Key

Navigate to "Keys" under Settings
Copy the "Primary Key" or "Secondary Key"
Note the "URI" for reference

Configuring Cloud Replicator

Setup Steps

Search for "Cloud Replicator Setup" in Business Central
Locate the Azure Cosmos DB (NoSQL) section
Enter the following:

Field	Value
Cosmos DB Core Account Name	Your account name (just the name, not full URI)
Cosmos DB Core Access Key	The primary or secondary key
Cosmos DB Database	The database name you created
Partition Key Postfix	(Optional) Additional text for partition keys

Testing the Connection

After entering credentials:

Create a table mapping for a small table
Select "Azure Cosmos DB (NO SQL API)" as the destination
Run a manual replication
Check the Replication Log for success
Verify data in Azure Portal > Data Explorer

Data Structure in Cosmos DB

Containers

Cloud Replicator creates one container per Business Central table:

Container names are sanitized table names
Partition key path is always /_Company
Containers are created automatically during first replication

Document Structure

Each Business Central record becomes a JSON document:

{
  "id": "10000",
  "__Company": "CRONUS_International_Ltd_",
  "__CompanyName": "CRONUS International Ltd.",
  "Name": "Adatum Corporation",
  "Address": "192 Market Square",
  "City": "Atlanta",
  "Phone_No_": "4255550100",
  "SystemCreatedAt": "2024-01-15T10:30:00Z",
  "SystemCreatedBy": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "SystemModifiedAt": "2024-02-01T14:45:00Z",
  "SystemModifiedBy": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "SystemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Notes:

_Company is the partition key (the cleaned, sanitized company name plus any partition key postfix).
CompanyName is only present when a Field Name for Company is configured in Setup (default CompanyName); it holds the unmodified company name.

Document ID

The document id is generated from:

Primary key field values (formatted and sanitized)
OR SystemId GUID if "SystemId as RowKey" is enabled

Partition Key

The partition key (_Company) contains the company name, enabling:

Efficient single-company queries
Company-level data isolation
Optimized cross-partition queries when needed

Querying Data

Azure Portal Data Explorer

Navigate to your Cosmos DB account
Open "Data Explorer"
Select your database and container
Use SQL queries to explore data

Example queries:

-- All customers in a company
SELECT * FROM c
WHERE c.__Company = "CRONUS International Ltd."

-- Specific customer
SELECT * FROM c
WHERE c.__Company = "CRONUS International Ltd."
AND c.id = "10000"

-- Filter by field
SELECT c.Name, c.City FROM c
WHERE c.City = "Atlanta"

SDK Access

Use Azure Cosmos DB SDK for programmatic access:

// C# Example
var container = cosmosClient.GetContainer("BusinessCentralData", "Customers");
var query = new QueryDefinition(
    "SELECT * FROM c WHERE c.__Company = @company")
    .WithParameter("@company", "CRONUS International Ltd.");

var iterator = container.GetItemQueryIterator<dynamic>(query);

Series Containers (Per Day)

When "Per Day" is enabled, Cloud Replicator creates a "Series" container:

Contains daily snapshots of data
Document ID includes the date
Useful for historical trend analysis

Performance Optimization

Request Units (RU/s)

Cosmos DB throughput is measured in Request Units per second:

Each operation consumes RUs based on complexity
Writes typically cost 5-10 RUs per document
Reads cost 1-5 RUs depending on document size

Scaling Recommendations

Scenario	RU/s Recommendation
Initial testing	400 RU/s (minimum)
Small replications (<1000 records)	400-1000 RU/s
Medium replications	1000-5000 RU/s
Large initial loads	5000+ RU/s (scale down after)

Autoscale

For production, enable Autoscale:

Automatically scales between 10% and 100% of max RU/s
Handles variable replication workloads
Cost-effective for periodic replications

Serverless Option

For infrequent replications, consider Serverless mode:

Pay only for consumed RUs
No minimum throughput charge
May have cold start latency

Cost Management

Understanding Costs

Cosmos DB costs include:

Throughput: RU/s provisioned (or consumed in Serverless)
Storage: Per GB stored per month
Data transfer: Between regions if globally distributed

Cost Optimization Tips

Use Autoscale to avoid over-provisioning
Scale down after large initial replications
Replicate only needed fields using Field Actions
Consider Serverless for infrequent use

Advanced Configuration

Partition Key Postfix

Add a postfix to partition keys for additional categorization:

Useful for multi-tenant scenarios
Adds text after the company name
Configure in Cloud Replicator Setup

Global Distribution

Cosmos DB supports multi-region distribution:

Configure additional read regions in Azure Portal
Data automatically replicates to all regions
Applications read from nearest region

Troubleshooting

Connection Errors

Verify account name (without .documents.azure.com)
Check access key is correct
Ensure Cosmos DB firewall allows Business Central

Database Not Found

Verify database name matches exactly (case-sensitive)
Create the database manually in Azure Portal
Check for typos in configuration

Request Rate Too Large (429)

Increase provisioned RU/s
Enable Autoscale
Reduce number of replication engines
Increase retry delay

Container Creation Fails

Verify database exists
Check permissions on access key
Review error message in Replication Log

Security Best Practices

Network Security

Enable firewall rules
Use private endpoints for production
Configure virtual network service endpoints

Key Management

Rotate keys periodically
Use resource tokens for limited access
Consider Azure Active Directory authentication

Data Protection

Enable encryption at rest (default)
Use customer-managed keys if required
Review Azure compliance certifications