IntegrationsDatabasesAzure Cosmos DB

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.

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

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

Create a Database and Container

  1. Open your Cosmos DB account in the Azure portal.
  2. Go to Data Explorer in the left sidebar.
  3. Click New Database.
  4. Enter a Database ID (e.g. analytics).
  5. Click OK.
  6. Click New Container within the database.
  7. Enter a Container ID (e.g. events).
  8. Set the Partition key to /message_id (or another high-cardinality field).
  9. 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

  1. In your Cosmos DB account, go to Settings > Keys.
  2. Copy the PRIMARY KEY (or Secondary Key as a backup).
  3. 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

FieldTypeRequiredDescription
endpointstringYesThe Cosmos DB account endpoint URL (e.g. https://my-account.documents.azure.com:443/).
databasestringYesThe Cosmos DB database ID. Also accepts database_id.
containerstringYesThe Cosmos DB container ID. Also accepts container_id.
partition_key_pathstringYesThe partition key path for the container (e.g. /event_id).
account_keysecretYesThe Cosmos DB account primary or secondary access key. Also accepts access_key.

Signal Setup

Quick Setup

  1. Navigate to Integrations in the sidebar.
  2. Open the Integration Library tab.
  3. Find Azure Cosmos DB or filter by Database.
  4. Click Install, select a variant if available, and fill in the required fields.
  5. 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.

Consent

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

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

Troubleshooting

ProblemSolution
Events not appearing in the containerVerify 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 mismatchThe partition_key_path must match the partition key defined on the container. Verify in Data Explorer > container Settings.
Credential errorsVerify 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.

See also

Amazon RDSAzure SQL