|
| 1 | +--- |
| 2 | +title: Enable data partitioning for the DICOM service in Azure Health Data Services |
| 3 | +description: Learn how to enable data partitioning for efficient storage and management of medical images for the DICOM service in Azure Health Data Services. |
| 4 | +author: bcarthic |
| 5 | +ms.service: healthcare-apis |
| 6 | +ms.subservice: fhir |
| 7 | +ms.topic: overview |
| 8 | +ms.date: 03/26/2024 |
| 9 | +ms.author: mmitrik |
| 10 | +--- |
| 11 | + |
| 12 | +# Enable data partitioning |
| 13 | + |
| 14 | +Data partitioning allows you to set up a lightweight data partition scheme to store multiple copies of the same image with the same unique identifier (UID) in a single DICOM instance. |
| 15 | + |
| 16 | +Although UIDs should be [unique across all contexts](http://dicom.nema.org/dicom/2013/output/chtml/part05/chapter_9.html), it's common practice for healthcare providers to write DICOM files to portable storage media and then give them to a patient. The patient then gives the files to another healthcare provider, who then transfers the files into a new DICOM storage system. Therefore, multiple copies of one DICOM file do commonly exist in isolated DICOM systems. Data partitioning provides an on-ramp for your existing data stores and workflows. |
| 17 | + |
| 18 | +## Limitations |
| 19 | + |
| 20 | +- The partitions feature can't be turned off after you turn it on. |
| 21 | +- Querying across partitions isn't supported. |
| 22 | +- Updating and deleting partitions is also not supported. |
| 23 | + |
| 24 | +## Enable data partitions during initial deployment |
| 25 | + |
| 26 | +1. Select **Enable data partitions** when you deploy a new DICOM service. After data partitioning is turned on, it can't be turned off. In addition, data partitions can't be turned on for any DICOM service that is already deployed. |
| 27 | + |
| 28 | + After the data partitions setting is turned on, the capability modifies the API surface of the DICOM server and makes any previous data accessible under the `Microsoft.Default` partition. |
| 29 | + |
| 30 | + :::image type="content" source="media/enable-data-partitions/enable-data-partitions.png" alt-text="Screenshot showing the Enable data partitions option on the Create DICOM service page." lightbox="media/enable-data-partitions/enable-data-partitions.png"::: |
| 31 | + |
| 32 | +> [!IMPORTANT] |
| 33 | +> Data partitions can't be disabled if partitions other than `Microsoft.Default` are present. When this situation happens, the system throws a `DataPartitionsFeatureCannotBeDisabledException` error on startup. |
| 34 | +
|
| 35 | +## API changes |
| 36 | + |
| 37 | +### List all data partitions |
| 38 | +This command Lists all data partitions: |
| 39 | + |
| 40 | +```http |
| 41 | +GET /partitions |
| 42 | +``` |
| 43 | + |
| 44 | +### Request header |
| 45 | + |
| 46 | +| Name | Required | Type | Description | |
| 47 | +| ------------ | --------- | ------ | ------------------------------- | |
| 48 | +| Content-Type | false | string | `application/json` is supported | |
| 49 | + |
| 50 | +### Responses |
| 51 | + |
| 52 | +| Name | Type | Description | |
| 53 | +| ----------------- | ----------------------------- | ------------------------------------- | |
| 54 | +| 200 (OK) | `[Partition] []` | A list of partitions is returned. | |
| 55 | +| 204 (No Content) | | No partitions exist. | |
| 56 | +| 400 (Bad Request) | | Data partitions capability is disabled. | |
| 57 | + |
| 58 | +### STOW, WADO, QIDO, delete, export, update, and worklist APIs |
| 59 | + |
| 60 | +After partitions are enabled, STOW, WADO, QIDO, delete, export, update, and worklist requests must include a data partition URI segment after the base URI, with the form `/partitions/{partitionName}`, where `partitionName` is: |
| 61 | + |
| 62 | + - Up to 64 characters long. |
| 63 | + - Any combination of alphanumeric characters, `.`, `-`, and `_`, to allow both DICOM UID and GUID formats, as well as human-readable identifiers. |
| 64 | + |
| 65 | +| Action | Example URI | |
| 66 | +| ------- | ------------------------------------------------------------------- | |
| 67 | +| STOW | `POST /partitions/myPartition-1/studies` | |
| 68 | +| WADO | `GET /partitions/myPartition-1/studies/2.25.0000` | |
| 69 | +| QIDO | `GET /partitions/myPartition1/studies?StudyInstanceUID=2.25.0000` | |
| 70 | +| Delete | `DELETE /partitions/myPartition1/studies/2.25.0000` | |
| 71 | +| Export | `POST /partitions/myPartition1/export` | |
| 72 | +| Update | `POST /partitions/myPartition-1/studies/$bulkUpdate` | |
| 73 | + |
| 74 | +### New responses |
| 75 | + |
| 76 | +| Name | Message | |
| 77 | +| ----------------- | --------------------------------------------------------- | |
| 78 | +| 400 (Bad Request) | Data partitions capability is disabled. | |
| 79 | +| 400 (Bad Request) | `PartitionName` value is missing in the route segment. | |
| 80 | +| 400 (Bad Request) | Specified `PartitionName {PartitionName}` doesn't exist. | |
| 81 | + |
| 82 | +### Other APIs |
| 83 | +All other APIs, including extended query tags, operations, and change feed continue to be accessed at the base URI. |
| 84 | + |
| 85 | +### Manage data partitions |
| 86 | + |
| 87 | +The only management operation supported for partitions is an implicit creation during STOW and workitem create requests. If the partition specified in the URI doesn't exist, the system creates it implicitly and the response returns a retrieve URI including the partition path. |
| 88 | + |
| 89 | +### Partition definitions |
| 90 | + |
| 91 | +A partition is a unit of logical isolation and data uniqueness. |
| 92 | + |
| 93 | +| Name | Type | Description | |
| 94 | +| ------------- | ------ | -------------------------------------------------------------------------------- | |
| 95 | +| PartitionKey | int | System-assigned identifier. | |
| 96 | +| PartitionName | string | Client-assigned unique name, up to 64 alphanumeric characters, `.`, `-`, or `_`. | |
| 97 | +| CreatedDate | string | The date and time when the partition was created. | |
0 commit comments