Extended query tags
By default, the DICOM® service supports querying on the DICOM tags specified in the conformance statement. When extended query tags are enabled, the list of tags can easily be expanded based on the application's needs.
Using the following listed APIs, users can index their DICOM studies, series, and instances on both standard and private DICOM tags such that they can be specified in QIDO-RS queries.
APIs
Version: v1
To help manage the supported tags in a given DICOM service instance, the following API endpoints have been added.
| API | Description |
|---|---|
| POST .../extendedquerytags | Add Extended Query Tags |
| GET .../extendedquerytags | List Extended Query Tags |
| GET .../extendedquerytags/{tagPath} | Get Extended Query Tag |
| DELETE .../extendedquerytags/{tagPath} | Delete Extended Query Tag |
| PATCH .../extendedquerytags/{tagPath} | Update Extended Query Tag |
| GET .../extendedquerytags/{tagPath}/errors | List Extended Query Tag Errors |
| GET .../operations/{operationId} | Get Operation |
Add extended query tags
Adds one or more extended query tags and starts a long-running operation that reindexes current DICOM instances with the specified tags.
POST .../extendedquerytags
Request header
| Name | Required | Type | Description |
|---|---|---|---|
| Content-Type | True | string | application/json is supported |
Request body
| Name | Required | Type | Description |
|---|---|---|---|
| body | Extended Query Tag for Adding[] |
Limitations
The following VR types are supported:
| VR | Description | Single Value Matching | Range Matching | Fuzzy Matching |
|---|---|---|---|---|
| AE | Application Entity | X | ||
| AS | Age String | X | ||
| CS | Code String | X | ||
| DA | Date | X | X | |
| DS | Decimal String | X | ||
| DT | Date Time | X | X | |
| FD | Floating Point Double | X | ||
| FL | Floating Point Single | X | ||
| IS | Integer String | X | ||
| LO | Long String | X | ||
| PN | Person Name | X | X | |
| SH | Short String | X | ||
| SL | Signed Long | X | ||
| SS | Signed Short | X | ||
| TM | Time | X | X | |
| UI | Unique Identifier | X | ||
| UL | Unsigned Long | X | ||
| US | Unsigned Short | X |
Note
Sequential tags, which are tags under a tag of type Sequence of Items (SQ), are currently not supported. You can add up to 128 extended query tags. We do not index extended query tags if the value is null or empty.
Responses
| Name | Type | Description |
|---|---|---|
| 202 (Accepted) | Operation Reference | Extended query tags have been added, and a long-running operation has been started to reindex existing DICOM instances |
| 400 (Bad Request) | Request body has invalid data | |
| 409 (Conflict) | One or more requested query tags already are supported |
List extended query tags
Lists of all extended query tags.
GET .../extendedquerytags
Responses
| Name | Type | Description |
|---|---|---|
| 200 (OK) | Extended Query Tag[] |
Returns extended query tags |
Get extended query tag
Get an extended query tag.
GET .../extendedquerytags/{tagPath}
URI parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by 00100020 or PatientId |
Responses
| Name | Type | Description |
|---|---|---|
| 200 (OK) | Extended Query Tag | The extended query tag with the specified tagPath |
| 400 (Bad Request) | Requested tag path is invalid | |
| 404 (Not Found) | Extended query tag with requested tagPath isn't found |
Delete extended query tag
Delete an extended query tag.
DELETE .../extendedquerytags/{tagPath}
URI parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by 00100020 or PatientId |
Responses
| Name | Type | Description |
|---|---|---|
| 204 (No Content) | Extended query tag with requested tagPath has been successfully deleted. | |
| 400 (Bad Request) | Requested tag path is invalid. | |
| 404 (Not Found) | Extended query tag with requested tagPath isn't found |
Update extended query tag
Update an extended query tag.
PATCH .../extendedquerytags/{tagPath}
URI parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by 00100020 or PatientId |
Request header
| Name | Required | Type | Description |
|---|---|---|---|
| Content-Type | True | string | application/json is supported. |
Request body
| Name | Required | Type | Description |
|---|---|---|---|
| body | Extended Query Tag for Updating |
Responses
| Name | Type | Description |
|---|---|---|
| 20 (OK) | Extended Query Tag | The updated extended query tag |
| 400 (Bad Request) | Requested tag path or body is invalid | |
| 404 (Not Found) | Extended query tag with requested tagPath isn't found |
List extended query tag errors
Lists errors on an extended query tag.
GET .../extendedquerytags/{tagPath}/errors
URI parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath is the path for the tag, which can be either tag or keyword. For example, Patient ID is represented by 00100020 or PatientId |
Responses
| Name | Type | Description |
|---|---|---|
| 200 (OK) | Extended Query Tag Error [] |
List of extended query tag errors associated with the tag |
| 400 (Bad Request) | Requested tag path is invalid | |
| 404 (Not Found) | Extended query tag with requested tagPath isn't found |
Get operation
Get a long-running operation.
GET .../operations/{operationId}
URI parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| operationId | path | True | string | The operation ID |
Responses
| Name | Type | Description |
|---|---|---|
| 200 (OK) | Operation | The completed operation for the specified ID |
| 202 (Accepted) | Operation | The running operation for the specified ID |
| 404 (Not Found) | The operation isn't found |
QIDO with extended query tags
Tag status
The Status of extended query tag indicates the current status. When an extended query tag is first added, its status is set to Adding, and a long-running operation is kicked off to reindex existing DICOM instances. After the operation is completed, the tag status is updated to Ready. The extended query tag can now be used in QIDO.
For example, if the tag Manufacturer Model Name (0008,1090) is added, and in Ready status, from then on the following queries can be used to filter stored instances by the Manufacturer Model Name.
../instances?ManufacturerModelName=Microsoft
They can also be used with existing tags. For example:
../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true
Tag query status
QueryStatus indicates whether QIDO is allowed for the tag. When a reindex operation fails to process one or more DICOM instances for a tag, that tag's QueryStatus is set to Disabled automatically. You can choose to ignore indexing errors and allow queries to use this tag by setting the QueryStatus to Enabled via Update Extended Query Tag API. Any QIDO requests that reference at least one manually enabled tag will include the set of tags with indexing errors in the response header erroneous-dicom-attributes.
For example, suppose the extended query tag PatientAge had errors during reindexing, but it was enabled manually. For the following query, you would be able to see PatientAge in the erroneous-dicom-attributes header.
../instances?PatientAge=035Y
Definitions
Extended query tag
A DICOM tag that will be supported for QIDO-RS.
| Name | Type | Description |
|---|---|---|
| Path | string | Path of tag, normally composed of group ID and element ID. for example, PatientId (0010,0020) has path 00100020 |
| VR | string | Value representation of this tag |
| PrivateCreator | string | Identification code of the implementer of this private tag |
| Level | Extended Query Tag Level | Level of extended query tag |
| Status | Extended Query Tag Status | Status of the extended query tag |
| QueryStatus | Extended Query Tag Query Status | Query status of extended query tag |
| Errors | Extended Query Tag Errors Reference | Reference to extended query tag errors |
| Operation | Operation Reference | Reference to a long-running operation |
Code example 1 is a standard tag (0008,0070) in Ready status.
{
"status": "Ready",
"level": "Instance",
"queryStatus": "Enabled",
"path": "00080070",
"vr": "LO"
}
Code example 2 is a standard tag (0010,1010) in Adding status. An operation with ID 1a5d0306d9624f699929ee1a59ed57a0 is running on it, and 21 errors have occurred so far.
{
"status": "Adding",
"level": "Study",
"errors": {
"count": 21,
"href": "https://localhost:63838/extendedquerytags/00101010/errors"
},
"operation": {
"id": "1a5d0306d9624f699929ee1a59ed57a0",
"href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
},
"queryStatus": "Disabled",
"path": "00101010",
"vr": "AS"
}
Operation reference
Reference to a long-running operation.
| Name | Type | Description |
|---|---|---|
| ID | string | operation ID |
| Href | string | Uri to the operation |
Operation
Represents a long-running operation.
| Name | Type | Description |
|---|---|---|
| OperationId | string | The operation ID |
| OperationType | Operation Type | Type of the long running operation |
| CreatedTime | string | Time when the operation was created |
| LastUpdatedTime | string | Time when the operation was updated last time |
| Status | Operation Status | Represents run time status of operation |
| PercentComplete | Integer | Percentage of work that has been completed by the operation |
| Resources | string[] |
Collection of resources locations that the operation is creating or manipulating |
The following code example is a running reindex operation.
{
"resources": [
"https://localhost:63838/extendedquerytags/00101010"
],
"operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
"type": "Reindex",
"createdTime": "2021-10-06T16:40:02.5247083Z",
"lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
"status": "Running",
"percentComplete": 10
}
Operation status
Represents a run time status of long running operation.
| Name | Type | Description |
|---|---|---|
| NotStarted | string | The operation isn't started |
| Running | string | The operation is executing and hasn't yet finished |
| Completed | string | The operation has finished successfully |
| Failed | string | The operation has stopped prematurely after encountering one or more errors |
Extended query tag error
An error that occurred during an extended query tag indexing operation.
| Name | Type | Description |
|---|---|---|
| StudyInstanceUid | string | Study instance UID where indexing errors occurred |
| SeriesInstanceUid | string | Series instance UID where indexing errors occurred |
| SopInstanceUid | string | Sop instance UID where indexing errors occurred |
| CreatedTime | string | Time when error occurred(UTC) |
| ErrorMessage | string | Error message |
The following code example contains an unexpected value length error on a DICOM instance. It occurred at 2021-10-06T16:41:44.4783136.
{
"studyInstanceUid": "2.25.253658084841524753870559471415339023884",
"seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
"sopInstanceUid": "2.25.225286918605419873651833906117051809629",
"createdTime": "2021-10-06T16:41:44.4783136",
"errorMessage": "Value length is not expected."
}
Extended query tag errors reference
Reference to extended query tag errors.
| Name | Type | Description |
|---|---|---|
| Count | Integer | Total number of errors on the extended query tag |
| Href | string | URI to extended query tag errors |
Operation type
The type of a long-running operation.
| Name | Type | Description |
|---|---|---|
| Reindex | string | A reindex operation that updates the indices for previously added data based on new tags |
Extended query tag status
The status of extended query tag.
| Name | Type | Description |
|---|---|---|
| Adding | string | The extended query tag has been added, and a long-running operation is reindexing existing DICOM instances |
| Ready | string | The extended query tag is ready for QIDO-RS |
| Deleting | string | The extended query tag is being deleted |
Extended query tag level
The level of the DICOM information hierarchy where this tag applies.
| Name | Type | Description |
|---|---|---|
| Instance | string | The extended query tag is relevant at the instance level |
| Series | string | The extended query tag is relevant at the series level |
| Study | string | The extended query tag is relevant at the study level |
Extended query tag query status
The query status of extended query tag.
| Name | Type | Description |
|---|---|---|
| Disabled | string | The extended query tag isn't allowed to be queried |
| Enabled | string | The extended query tag is allowed to be queried |
Note
Errors during the reindex operation disables QIDO on the extended query tag. You can call the Update Extended Query Tag API to enable it.
Extended query tag for updating
Represents extended query tag for updating.
| Name | Type | Description |
|---|---|---|
| QueryStatus | Extended Query Tag Query Status | The query status of extended query tag |
Extended query tag for adding
Represents extended query tag for adding.
| Name | Required | Type | Description |
|---|---|---|---|
| Path | True | string | Path of tag, normally composed of the group ID and element ID that's the PatientId (0010,0020) has path 00100020 |
| VR | string | Value representation of this tag. It's optional for standard tag, and required for private tag | |
| PrivateCreator | string | Identification code of the implementer of this private tag. Only set when the tag is a private tag | |
| Level | True | Extended Query Tag Level | Represents the hierarchy at which this tag is relevant. Should be one of Study, Series or Instance |
Code example 1 MicrosoftPC is defining the private tag (0401,1001) with the SS value representation on the instance level.
{
"Path": "04011001",
"VR": "SS",
"PrivateCreator": "MicrosoftPC",
"Level": "Instance"
}
Code example 2 uses the standard tag with keyword ManufacturerModelName with the LO value representation that's defined on the series level.
{
"Path": "ManufacturerModelName",
"VR": "LO",
"Level": "Series"
}
Code example 3 uses the standard tag (0010,0040) and is defined on studies. The value representation is already defined by the DICOM standard.
{
"Path": "00100040",
"Level": "Study"
}
Summary
This conceptual article provided you with an overview of the Extended Query Tag feature within the DICOM service.
Next steps
Deploy the DICOM service to Azure
Use DICOMweb APIs with the DICOM service
Note
DICOM® is the registered trademark of the National Electrical Manufacturers Association for its Standards publications relating to digital communications of medical information.