CosmosDB Setup
Goal: Create a CosmosDB account your workspace owns, so you can add databases, containers and documents.
You are not connecting to a database someone else set up. You are creating one, in your own Azure subscription, from inside your workspace.
Before you start
- A connected Azure cloud on this workspace.
- A provisioned landing zone - Environment -> Manage Private CALZ. An account has to be provisioned into something.
TIP
Databases shows in the Environment menu only once the workspace has its private landing zone. Without one, the menu has no Databases entry, and Azi or an agent that proposes an account is told: "This needs a private landing zone, which this workspace does not have yet."
Create an account
1. Open Environment -> Databases
Open Environment in the top bar and choose Databases.
2. Fill in the account
| Field | What it does |
|---|---|
| Name | How the account appears in your workspace. Name the purpose, not the technology |
| Description | Optional. What the account is for |
| Scaling profile | Serverless, Standard, Medium volume, High volume or Very high volume |
| Backup | How far back the account can be restored: a continuous 7, 30 or 35-day window, or Periodic |
| Protect from deletion | When the account is provisioned (Save & Provision or Save & Apply), a 'CanNotDelete' lock is put on it, so it cannot be removed from here or from the Azure portal |
| API | Which Cosmos API the account publishes. NoSQL (SQL API) is the default, and the only one served end to end today. Fixed at creation |
| Region | Only for an additional account (see below). Fixed at creation |
| Resource group | Optional. Leave it blank and the landing zone decides |
The scaling profile is a named intent, not a number of request units. Serverless reserves no throughput and bills for the requests you make and the data you store; it is chosen when the account is created, and an existing account cannot be switched to or from it. The other four set every container's autoscale ceiling:
| Profile | Each container autoscales between | Azure raises the ceiling once a container stores more than |
|---|---|---|
| Standard | 100 and 1,000 RU/s | 100 GB |
| Medium volume | 500 and 5,000 RU/s | 500 GB |
| High volume | 1,000 and 10,000 RU/s | 1,000 GB |
| Very high volume | 2,000 and 20,000 RU/s | 2,000 GB |
The ceiling is not a cap on the bill: Azure raises it on its own as a container's data grows past the size shown, and the standing cost rises with it.
3. Save & Provision
Choose Save & Provision:
Saved. Provisioning runs in the background and this list updates as it completes.
This Save builds the account in your subscription; it does not wait for Deploy. On an account that is already live the button reads Save & Apply, because saving re-runs provisioning against it.
Each account appears as a row showing its region, scaling profile and state:
| State | Means |
|---|---|
| Not started | The record exists and provisioning has not begun |
| Provisioning | Provisioning is in flight. The list updates as it completes |
| Live | Ready to use. You can create databases inside it |
| Needs attention | Provisioning reported an error. The account may exist but is not usable as configured |
| Unknown | The record could not be read. This is "we cannot tell", not "not yet" |
Which region your data is in
NOTE
The region is fixed when the account is created and can never be changed afterwards.
| Account | Region |
|---|---|
| Your first account | This account is created in your workspace landing zone region. It is not a choice made here. |
| Any additional account | An additional account must state its own region. It is not inherited from your landing zone. |
An additional account refuses to save without a region: "Choose a region for this additional account. It cannot be left blank and it is not filled in for you." Inheriting one would be choosing a region for you.
Each region is a separate CosmosDB account with its own cost floor.
There is nothing to paste
There is no endpoint field, no account key, and no Test Connection button - and that is deliberate. The account is provisioned into the Azure cloud your workspace is already connected to, and every call resolves credentials server-side. A key you never collect cannot be stored, leaked, or left in a browser.
What this account is not for
NOTE
A working store, not an evidence store
A CosmosDB container is a working store. Documents in it can be updated and deleted. There is no write-once mode and no retention lock; CosmosDB does not offer one, so neither can OpenX.
Records you need to keep as proof of what happened belong in a store built for that. A container declared as holding evidence is refused when you create it, for exactly this reason. Each container's API settings decide which methods its table endpoints publish, and a container with no API settings publishes nothing. That is an access setting, not a record of what happened.
Creating the account and being allowed to read its documents are two separate grants. If listing containers works but documents are refused, save the account again with Save & Apply in Environment -> Databases (the product calls this re-deploying the data store) - that re-runs the step that grants document access.
Next steps
| If you want to... | Go to... |
|---|---|
| Add a database and its containers | Containers |
| Read and write a container's documents | Table endpoints |
| Build queries on database data | Warm Queries |
| Something is not working | Data Stores troubleshooting |