IntegrationsDatabasesAzure Cosmos DB

Azure Cosmos DB

Datafly Signal delivers events to Azure Cosmos DB for globally distributed, multi-model NoSQL storage with guaranteed single-digit 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/).
database_idstringYesThe Cosmos DB database ID.
container_idstringYesThe Cosmos DB container ID.
partition_key_pathstringYesThe partition key path for the container (e.g. /message_id).
access_keysecretYesThe Cosmos DB account primary or secondary 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 Cloud Storage.
  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_id": "analytics",
      "container_id": "events",
      "partition_key_path": "/message_id",
      "access_key": "YOUR_PRIMARY_KEY"
    },
    "delivery_mode": "server_side"
  }'

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.

Amazon RDSAzure SQL