Database Containers
Goal: Create containers on a CosmosDB account your workspace owns, and declare what each one holds.
Containers are created from the Database node, not from a menu and not in the Azure Portal. There is no credential step: the account was provisioned into the cloud your workspace is already connected to.
Before you start
You need a provisioned CosmosDB account - start at CosmosDB Setup. The Database node appears in the Node Bank only once one exists. Drag it onto the canvas and point it at the account.
Open Manage containers
- Select the Database node on the canvas.
- In the inspector, choose Manage containers.
TIP
The button is disabled until the Database node points at a data store account: "Choose a data store account first — a container has to live somewhere."
The Manage database window opens on Containers. A database with nothing in it says so: "No containers yet. A container is where documents actually live."
Create a container
Choose Create new container. Four things are settled when you create a container, and two of them (the partition key and the residency field) can never be changed.
| Field | What it does |
|---|---|
| Name | The container name in Cosmos |
| Partition key path | A path into each document, for example /deviceId or /meta/region. Cannot be changed later |
| Residency field (optional) | Leave it blank unless records have to be stored in different regions; if set, it names the field that decides where each record goes. Cannot be changed later |
| What kind of data will this table hold? | The data class. Required, with no default |
NOTE
The partition key cannot be changed after the container is created. Choosing a different one later means creating a new container and moving the documents.
Choosing a partition key
Pick the field your reads will filter on most often - a device id, a site code, a study id. A nested field
like /meta/region is valid, and the path must start with /.
NOTE
A wrong partition key does not produce an error. Reads come back empty, because the query looked in a partition the document was never written to. If documents you know exist appear to be missing, check this first.
What the form refuses
Create container stays disabled until every check passes, and it lists what is unmet, for example:
- "Give the container a name."
- "A container name cannot contain /, \, # or ?."
- "Remove the spaces at the start or end of the container name."
- "Choose a partition key path."
- "A partition key path starts with "/" — for example /studyId."
- "Declare what kind of data this table holds. There is no default — an undeclared table is not the same as an ordinary one."
A container you create is built in your Cosmos account when someone presses Deploy.
Declare what the container holds
The form asks What kind of data will this table hold? and starts on Not declared yet: "There is no default. An undeclared table is not the same as an ordinary one."
| Class | What it means |
|---|---|
| Operational | Day-to-day working data |
| Reference | Static lookups (units, site codes, controlled vocabularies) |
| Evidence | Append-only records kept to prove what happened |
Declaring evidence is refused: "A table declared as holding evidence cannot be provisioned here. Evidence records need an append-only store with retention guarantees that this account does not provide." Documents in a CosmosDB container can be updated and deleted.
NOTE
A declaration, not a control
The data class is self-declared. It stops you creating a container while declaring that it holds evidence. It does not stop anyone declaring operational and storing evidence in it anyway.
OpenX does not inspect your documents. There is no default because "not classified" and "classified as harmless" must never look alike.
Choose what the container publishes
Expand a container's row to set its API: see Table endpoints. Nothing is published until you switch methods on.
Read documents
The window's Data tab reads a container's documents, a page at a time: press Read documents, then Load more. It only reads; the table endpoints are the way to change documents. It needs Read switched on for the container; otherwise it says:
Read is not published for "...", so its documents cannot be browsed here. Switch the API and its Read method on in the Containers tab, and save. This is not the same as the container being empty.
An empty container reads "The data store answered and this container holds no documents."
Retention
A container can carry a retention period (a time to live) in seconds. On an existing container with a retention period, the row's Retention box offers Raise to (seconds):
Retention can be raised here and never shortened: shortening deletes the older documents on the next sweep. Use -1 to let each document set its own.
A proposal that shortens a container's retention is refused. The Create new container form has no retention field.
Remove a container
Only a container that was never provisioned can be removed today. It has nothing in Azure, so it goes when you save the workspace, with nothing left for a Deploy. (The window's note about a container that "keeps working until the next Deploy" describes removing a provisioned one, which is not switched on yet.) See Removals.
NOTE
Removing a container that already exists in Azure is not switched on yet: the copy of its documents that must be taken first is not switched on. If you try, Remove tells you so and nothing changes.
Ask Azi, or an agent
An agent can propose a container. A proposed one shows Proposed in Manage containers: "Proposed, not created yet." Accept or reject it in Proposals. A proposal may switch on Create or Read only; switching on Update or Delete is a person's change.
Next steps
| If you want to... | Go to... |
|---|---|
| Read and write documents over HTTP | Table endpoints |
| Provision another account | CosmosDB Setup |
| Something is not working | Data Stores troubleshooting |