6.7 QIDO-RS Request/Response

DICOM QIDO-RS defines several action types. An implementation shall support the following action types:

  1. SearchForStudies

    This action searches for DICOM Studies that match specified search parameters and returns a list of matching studies and the requested attributes for each study.

  2. SearchForSeries

    This action searches for DICOM Series that match specified search parameters and returns a list of matching series and the requested attributes for each series.

  3. SearchForInstances

    This action searches for DICOM Instances that match specified search parameters and returns a list of matching instances and the requested attributes for each instance.

6.7.1 QIDO-RS - Search

6.7.1.1 Request

The specific resources to be used for the search actions shall be as follows:

  • Resource

    • SearchForStudies

      • {SERVICE}/studies[?query]

    • SearchForSeries

      • {SERVICE}/studies/{StudyInstanceUID}/series[?query]

      • {SERVICE}/series[?query]

    • SearchForInstances

      • {SERVICE}/studies/{StudyInstanceUID}/series/{SeriesInstanceUID}/instances[?query]

      • {SERVICE}/studies/{StudyInstanceUID}/instances[?query]

      • {SERVICE}/instances[?query]

    where

    • {SERVICE} is the base URL for the QIDO RESTful service. This may be a combination of scheme (http or https), host, port, and application.

    • {StudyInstanceUID} is the unique Study Instance UID for a single study.

    • {SeriesInstanceUID} is the unique Series Instance UID for a single series.

  • Method

    • GET

  • Headers

    • Accept - The Media Type of the query results. The types allowed for this request header are:

      • multipart/related; type=application/dicom+xml (default)

        Specifies that the results should be DICOM PS3.19 XML (one part per result)

      • application/json

        Specifies that the results should be DICOM JSON

      A QIDO-RS provider shall support both Accept header values

    • Cache-control: no-cache (recommended)

      If included, specifies that search results returned should be current and not cached.

  • Query key=value pairs

    • {attributeID}={value}

      0-n / {attributeID}={value} pairs allowed

    • includefield={attributeID} | all

      0-n includefield / {attributeID} pairs allowed, where "all" indicates that all available attributes should be included for each response.

    Each {attributeID} must refer to one of:

    • Patient IE attributes

    • Study IE attributes

    • Series IE attributes (SearchForSeries or SearchForInstances requests only)

    • Composite Instance IE attributes (SearchForInstances requests only)

    • Additional Query / Retrieve Attributes (Section C.3.4 in PS3.4 )

    • Timezone Offset From UTC (0008,0201)

    Each {attributeID} query value must be unique unless the associated DICOM Attribute allows UID List matching (see Section C.2.2.2.2 in PS3.4 ), in which case each {value} will be interpreted to be an element of the UID List.

    The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attributeID} (see Section C.2.2.2 in PS3.4 ). All characters in {value} that are disallowed for URLs must be URL encoded. See IETF RFC 1738 for details.

    If an {attributeID} is passed as the value of an "includefield" query key this is equivalent to C-FIND Universal matching for the specified attribute (see Section C.2.2.2.3 in PS3.4 ).

    • fuzzymatching=true | false

    • limit={maximumResults}

    • offset={skippedResults}

    {attributeID} can be one of the following:

    • {dicomTag}

    • {dicomKeyword}

    • {dicomTag}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomTag}

    • {dicomKeyword}.{attributeID}, where {attributeID} is an element of the sequence specified by {dicomKeyword}

    {dicomTag} is the eight character hexadecimal string corresponding to the Tag of a DICOM Attribute (see 6 in PS3.6 ).

    {dicomKeyword} is the Keyword of a DICOM Attribute (see 6 in PS3.6 ).

    Note

    Examples of valid values for {attributeID}:

    • 0020000D

    • StudyInstanceUID

    • 00101002.00100020

    • OtherPatientIDsSequence.PatientID

    • 00101002.00100024.00400032

    • OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID

Note

Examples of valid QIDO-RS URLs:

  • http://dicomrs/studies​?PatientID=11235813

  • http://dicomrs/studies​?PatientID=11235813​&StudyDate=20130509

  • http://dicomrs/studies​?00100010=SMITH*​&00101002.00100020=11235813​&limit=25

  • http://dicomrs/studies​?00100010=SMITH*​&OtherPatientIDsSequence.00100020=11235813

  • http://dicomrs/studies​?PatientID=11235813​&includefield=00081048​&includefield=00081049​&includefield=00081060

  • http://dicomrs/studies​?PatientID=11235813​&StudyDate=20130509-20130510

  • http://dicomrs/studies​?StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587​%2c1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583

6.7.1.2 Response

The Server shall perform the query indicated in the request. The Server shall return the query results or, when the query cannot be performed, an error code.

If the limit query key is not specified or its value exceeds the total number of matching results then {maximumResults} is the lesser of the number of matching results and the maximum number of results supported by the Server.

If the offset query key is not specified or its value is less than zero then {skippedResults} is zero.

The first result returned shall be result number ({skippedResults} + 1). The last result returned shall be result number ({skippedResults} + {maximumResults}). If ({skippedResults} + 1) exceeds {maximumResults} then no results are returned.

If the number of results exceeds the maximum supported by the server, the server shall return the maximum supported results and the response shall include the following HTTP/1.1 Warning header (see RFC 2616 Section 14.46):

Warning: 299 {SERVICE}: "The number of results exceeded the maximum supported by the server. Additional results can be requested.

Note

The client can request additional results by specifying a value for the "offset" query key.

The server shall be idempotent so that if the list of results is the same, the response to a request with a specific set of parameters shall always be the same, including order. If the complete list of results is different for subsequent transactions the responses may be different. In a situation where results are changing due to changes in the server contents, queries using the limit and offset may be inconsistent.

The response format depends on the Accept header specified in the request.

6.7.1.2.1 Matching

The matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see Section C.2.2.2 in PS3.4 ).

Matching results shall be generated according to the Hierarchical Search Method described in Section C.4.1.3.1.1 in PS3.4 .

Combined Datetime matching shall be performed (see Section C.2.2.2.5 in PS3.4 ).

Note

If a QIDO-RS provider is acting as a proxy for a C-FIND SCP that does not support combined Datetime matching the QIDO-RS provider will need to perform a C-FIND request using Date only and filter results outside the time range before returning a QIDO-RS response

If the TimezoneOffsetFromUTC / 00080201 query key is included in the request, dates and times in the request are to be interpreted in the specified time zone.

If the "fuzzymatching=true" query key/value is included in the request and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the service provider.

If the "fuzzymatching=true" query key/value is included in the request and it is not supported, the response shall include the following HTTP/1.1 Warning header (see RFC 2616 Section 14.46):

Warning: 299 {SERVICE}: "The fuzzymatching parameter is not supported. Only literal matching has been performed."

where {SERVICE} is the base URL for the QIDO-RS provider. This may be a combination of scheme (http or https), host, port, and application.

Note

The Warning header is separate from the Status Line and does not affect the returned Status Code.

6.7.1.2.1.1 Study Matching

Providers of the SearchForStudies service shall support the search query keys described in Table 6.7.1-1:

Table 6.7.1-1. QIDO-RS STUDY Search Query Keys

Key Word

Tag

StudyDate

00080020

StudyTime

00080030

AccessionNumber

00080050

ModalitiesInStudy

00080061

ReferringPhysicianName

00080090

PatientName

00100010

PatientID

00100020

StudyInstanceUID

0020000D

StudyID

00200010


6.7.1.2.1.2 Series Matching

Providers of the SearchForSeries service shall support the search query keys described in Table 6.7.1-1a:

Table 6.7.1-1a. QIDO-RS SERIES Search Query Keys

Key Word

Tag

Modality

00080060

SeriesInstanceUID

0020000E

SeriesNumber

00200011

PerformedProcedureStepStartDate

00400244

PerformedProcedureStepStartTime

00400245

RequestAttributeSequence

00400275

>ScheduledProcedureStepID

00400009

>RequestedProcedureID

00401001


If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

6.7.1.2.1.3 Instance Matching

Providers of the SearchForInstances service shall support the search query keys described in Table 6.7.1-1b:

Table 6.7.1-1b. QIDO-RS INSTANCE Search Query Keys

Key Word

Tag

SOPClassUID

00080016

SOPInstanceUID

00080018

InstanceNumber

00200013


If {StudyInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Study-level attributes specified in Table 6.7.1-1 shall also be supported.

If {SeriesInstanceUID} is not specified in the URL and this form of Relational Query is supported, all Series-level attributes specified in Table 6.7.1-1a shall also be supported.

6.7.1.2.2 Query Result Attributes
6.7.1.2.2.1 Study Result Attributes

For each matching Study, the QIDO-RS provider shall return all attributes in accordance with Table 6.7.1-2:

Table 6.7.1-2. QIDO-RS STUDY Returned Attributes

Attribute Name

Tag

Notes

Specific Character Set

(0008,0005)

If necessary for encoding any returned attributes

Study Date

(0008,0020)

Study Time

(0008,0030)

Accession Number

(0008,0050)

Instance Availability

(0008,0056)

Modalities in Study

(0008,0061)

Referring Physician's Name

(0008,0090)

Timezone Offset From UTC

(0008,0201)

May be absent if no value is available

Retrieve URL

(0008,1190)

Shall be empty if the resource cannot be retrieved via WADO-RS

Patient's Name

(0010,0010)

Patient ID

(0010,0020)

Patient's Birth Date

(0010,0030)

Patient's Sex

(0010,0040)

Study Instance UID

(0020,000D)

Study ID

(0020,0010)

Number of Study Related Series

(0020,1206)

Number of Study Related Instances

(0020,1208)

All other Study Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes

All other Study Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes

All available Study Level DICOM Attributes if the "includefield" query key is included with a value of "all"


Series Level and Instance Level attributes passed as "includefield" query values shall not be returned.

Note

The above list is consistent with those required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

6.7.1.2.2.2 Series Result Attributes

For each matching Series, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2a:

Table 6.7.1-2a. QIDO-RS SERIES Returned Attributes

Attribute Name

Tag

Notes

Specific Character Set

(0008,0005)

If necessary for encoding any returned attributes

Modality

(0008,0056)

Timezone Offset From UTC

(0008,0201)

May be absent if no value is available

Series Description

(0008,103E)

May be absent if no value is available

Retrieve URL

(0008,1190)

Shall be empty if the resource cannot be retrieved via WADO-RS

Series Instance UID

(0020,000E)

Series Number

(0020,0011)

Number of Series Related Instances

(0020,1209)

Performed Procedure Step Start Date

(0040,0244)

May be absent if no value is available

Performed Procedure Step Start Time

(0040,0245)

May be absent if no value is available

Request Attribute Sequence

(0040,0275)

May be absent if no value is available

>Scheduled Procedure Step ID

(0040,0009)

>Requested Procedure ID

(0040,1001)

All other Series Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes

All other Study or Series Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes

All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all"

If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2


Instance Level attributes passed as "includefield" query values shall not be returned.

Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

6.7.1.2.2.3 Instance Result Attributes

For each matching instance, the QIDO-RS provider shall return all attributes listed in Table 6.7.1-2b:

Table 6.7.1-2b. QIDO-RS INSTANCE Returned Attributes

Attribute Name

Tag

Notes

Specific Character Set

(0008,0005)

If necessary for encoding any returned attributes

SOP Class UID

(0008,0016)

SOP Instance UID

(0008,0018)

Instance Availability

(0008,0056)

Timezone Offset From UTC

(0008,0201)

May be absent if no value is available

Retrieve URL

(0008,1190)

Shall be empty if the resource cannot be retrieved via WADO-RS

Instance Number

(0020,0013)

Rows

(0028,0010)

Only present for Image Instances

Columns

(0028,0011)

Only present for Image Instances

Bits Allocated

(0028,0100)

Only present for Image Instances

Number of Frames

(0028,0008)

Only present for Multi-frame image instances

All other Instance Level DICOM Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes

All other Study, Series or Instance Level DICOM Attributes passed as "includefield" query values that are supported by the service provider as return attributes

All available Instance Level DICOM Attributes if the "includefield" query key is included with a value of "all"

If {StudyInstanceUID} is not specified, all Study-level attributes specified in Table 6.7.1-2

If {SeriesInstanceUID} is not specified, all Series-level attributes specified in Table 6.7.1-2a


Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1 and Table 4.14-2).

6.7.1.2.3 Query Result Messages

The server shall support returning query results as:

  • XML Results

  • JSON Results

The result format used shall depend on the Accept header of the request.

6.7.1.2.3.1 XML Results
  • Content-Type: multipart/related; type=application/dicom+xml

    • The response is a multipart message body where each part is a DICOM PS3.19 XML NativeDicomModel element containing the attributes for one matching Study, Series or Instance (see Section A.1 in PS3.19 ).

    • The provider of the QIDO service may use a BulkData reference at its discretion (see Table A.1.5-2 in PS3.19 and Section 6.5.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

    • If there are no matching results, the message body will be empty.

  • Each item in the multipart response will contain the following HTTP/1.1 headers:

    • Content-Type: application/dicom+xml

6.7.1.2.3.2 JSON Results
  • Content-Type: application/json

    • The response is a DICOM JSON message containing a DICOM JSON property for each matching study, series or instance containing sub-properties describing the matching attributes for each study, series or instance (see Section F.2).

    • The provider of the QIDO service may use a BulkDataURI reference at its discretion (see Section F.2.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

    • If there are no matching results, the JSON message is empty.

6.7.1.3 Status Codes

Table 6.7-1 lists the HTTP/1.1 status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.

Table 6.7-1. QIDO-RS HTTP/1.1 Status Codes

Code

Name

Description

Success

200

OK

The query completed and any matching results are returned in the message body.

Failure

400

Bad Request

The QIDO-RS Provider was unable to perform the query because the Service Provider cannot understand the query component.

401

Unauthorized

The QIDO-RS Provider refused to perform the query because the client is not authenticated.

403

Forbidden

The QIDO-RS Provider understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).

413

Request entity too large

The query was too broad and a narrower query or paging should be requested. The use of this status code should be documented in the conformance statement.

503

Busy

Service is unavailable.