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.