Azure Cosmos DB

Datafly Signal writes first-party events as documents into Azure Cosmos DB (Core SQL API) for globally distributed, multi-model NoSQL storage with millisecond latency.

Why route Azure Cosmos DB through Datafly Signal

The data lands in infrastructure you own. Signal writes to your Azure Cosmos DB directly from your own deployment. Datafly operates no intermediary and never holds a copy of your event data.
Client IP and user agent are recorded as event context. Both come from the original visitor request rather than from your server, so geography and device analysis done in the warehouse reflects the actual visitor.
Presets for Retail and General. The mapping starts from a working configuration for your vertical instead of a blank field map.
One consent decision governs every destination. Azure Cosmos DB is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

Before configuring Azure Cosmos DB in Signal, you need an Azure account with a Cosmos DB account (Core SQL API), a database, and a container.

Create an Azure Account

If you don’t already have one, sign up at azure.microsoft.com.

Create a Cosmos DB Account

In the Azure portal, search for Azure Cosmos DB and click Create.
Select Azure Cosmos DB for NoSQL (Core SQL API).
Enter an Account Name (e.g. datafly-events).
Select a Location close to your Signal deployment.
Choose a Capacity mode:
- Serverless — pay per request, ideal for variable workloads.
- Provisioned throughput — reserve RU/s for predictable workloads.
Click Review + Create > Create.
Once deployed, note the URI (endpoint) from the account overview page.

Create a Database and Container

Open your Cosmos DB account in the Azure portal.
Go to Data Explorer in the left sidebar.
Click New Database.
Enter a Database ID (e.g. analytics).
Click OK.
Click New Container within the database.
Enter a Container ID (e.g. events).
Set the Partition key to /message_id (or another high-cardinality field).
Click OK.

Choose a partition key with high cardinality to ensure even data distribution. The message_id field (unique per event) is a good default choice.

Get the Access Key

In your Cosmos DB account, go to Settings > Keys.
Copy the PRIMARY KEY (or Secondary Key as a backup).
Note the URI if you haven’t already.

⚠️

Store the access key securely. It provides full read/write access to the account. For production, consider using Azure RBAC with a managed identity instead of keys.

Configuration

Field	Type	Required	Description
`endpoint`	string	Yes	The Cosmos DB account endpoint URL (e.g. `https://my-account.documents.azure.com:443/`).
`database`	string	Yes	The Cosmos DB database ID. Also accepts `database_id`.
`container`	string	Yes	The Cosmos DB container ID. Also accepts `container_id`.
`partition_key_path`	string	Yes	The partition key path for the container (e.g. `/event_id`).
`account_key`	secret	Yes	The Cosmos DB account primary or secondary access key. Also accepts `access_key`.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find Azure Cosmos DB or filter by Database.
Click Install, select a variant if available, and fill in the required fields.
Click Install Integration to create the integration with a ready-to-use default blueprint.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/azure_cosmosdb/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Azure Cosmos DB",
    "variant": "default",
    "config": {
      "endpoint": "https://datafly-events.documents.azure.com:443/",
      "database": "analytics",
      "container": "events",
      "partition_key_path": "/event_id",
      "account_key": "YOUR_PRIMARY_KEY"
    },
    "delivery_mode": "server_side"
  }'

Schema

Each event becomes one Cosmos DB document with the canonical envelope as top-level fields:

{
  "id": "<event_id>",
  "event_id": "...",
  "type": "track",
  "event": "order_completed",
  "anonymous_id": "...",
  "user_id": "...",
  "timestamp": "2026-05-12T10:00:00Z",
  "received_at": "...",
  "sent_at": "...",
  "context":    { ... },
  "properties": { ... },
  "traits":     { ... },
  "source_id": "...",
  "integration_id": "..."
}

Cosmos DB items cannot exceed 2 MB. Choose a partition key with high cardinality — /event_id gives perfectly even distribution at the cost of cross-partition queries.

Cosmos DB is a first-party destination in your own Azure subscription. The default blueprint forwards all events. Apply consent filtering via pipeline transforms or query-time filters on context.consent if needed.

Testing

Enable the integration in Signal and trigger a test event on your website.
In the Azure portal, open your Cosmos DB account > Data Explorer.
Expand the database and container, then click Items.
Verify that event documents are appearing with the correct partition key and data.
In Signal, check the Live Events view to confirm delivery status shows as successful.

Troubleshooting

Problem	Solution
Events not appearing in the container	Verify the endpoint, database ID, container ID, and partition key path are correct.
`Unauthorized` (401)	The access key is invalid or has been regenerated. Get the current key from Settings > Keys.
`NotFound` (404)	The database or container does not exist. Verify the IDs in Data Explorer.
`RequestEntityTooLarge` (413)	Individual documents cannot exceed 2 MB. Check the event payload size.
`TooManyRequests` (429)	You have exceeded the provisioned RU/s. Increase throughput or switch to autoscale.
Partition key mismatch	The `partition_key_path` must match the partition key defined on the container. Verify in Data Explorer > container Settings.
Credential errors	Verify the endpoint URL ends with `:443/` and the access key is the full key string from the Keys page.

Visit Azure Cosmos DB documentation for full API reference, partitioning strategies, and throughput management.