HL7 QRY messages issue a query in original-mode — the protocol HL7 defined before the purpose-built query/response pairs of later versions. A QRY message asks a receiving system to return data matching a set of filter criteria; the responding system answers with a paired response message such as ADR^A19 for patient demographics or ORF^R04 for observations. This page explains what a QRY message represents, the trigger events it carries, every segment the message can contain and what each one holds, and how QRY relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
Deprecation notice. QRY is deprecated as of HL7 v2.5 in favour of the QBP (Query by Parameter) message, which offers a more flexible and interoperable query framework. QRY remains widely deployed in legacy environments and is still encountered regularly in production interfaces, but new implementations should use QBP or a FHIR RESTful search instead.
What a QRY message represents
A QRY message — QRY stands for Query — is a request from one system to another for a specific set of records. The heart of the message is the QRD (Original Query Definition) segment, which carries the query identifier, the date and time the query was issued, how many records the requester wants, and the key filter criteria: who the query is about and what data is being requested. An optional QRF (Query Filter) segment adds further refinement — a collection date range, a patient event filter, or other secondary criteria.
The sender is whatever application needs data — an EHR, a clinical workstation, a result viewer, or an integration engine acting as a broker. The receiver is the system that holds the records: an ADT system for patient demographics, a laboratory or clinical repository for observations, a pharmacy system for medication data, or a document management system for transcribed reports. On receiving the QRY, the responding system assembles matching records and returns them in the paired response message designated for that trigger event.
When a QRY message is sent
A QRY message is sent when an application needs to pull data from a remote system on demand rather than receive it as an unsolicited feed. Common scenarios include a workstation requesting a patient's current demographics before an encounter, a results viewer pulling pending observations, or an integration engine querying a pharmacy system for a patient's active medications. Because QRY is a synchronous, point-to-point request, it is best suited to situations where a known, bounded set of records is needed immediately from a single authoritative source.
Trigger events
The QRY message type carries four trigger events, each pairing with a specific response message:
QRY^A19— Patient query. Requests patient demographic and visit information; the paired response is ADR^A19.QRY^R02— Observation query with patient demographics. Requests clinical observations (results); the paired response is ORF^R04.QRY^P15— Pharmacy query. Requests pharmacy or medication data from a pharmacy information system.QRY^T12— Document query. Requests transcribed or stored clinical documents from a document management system.
The trigger event in MSH-9 tells the receiving system which response message to construct and which records to search. The QRD segment carries the actual filter criteria regardless of the trigger event.
Integration topology
The diagram shows a requesting application sending a QRY message through the integration engine to a source system, which returns the paired response message.
{{diagram: requesting application → QRY message → integration engine → source system (ADT / LIS / pharmacy / document system) → paired response (ADR^A19 / ORF^R04) → integration engine → requesting application}}
Typical senders: EHR, clinical workstation, result viewer, integration engine acting as query broker.
Typical receivers: ADT system, laboratory information system, pharmacy information system, document management system.
Direction: request/response — the QRY travels from requester to source system, and the paired response returns matching records in the opposite direction.
Segments in a QRY message
The QRY message structure is deliberately lean: a required MSH, an optional SFT, a required QRD that drives the query, and an optional QRF that adds supplemental filter criteria. Cardinality follows HL7 notation: [X] optional, {X} repeating, [{X}] optional and repeating; a bare code is required. Each segment code links to its canonical field-by-field reference.
| Segment | Description |
|---|---|
MSH | Message Header. Opens every QRY message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (e.g. QRY^A19), carries the message control id in MSH-10, and pins the HL7 version. The receiving system routes on MSH-9 to determine which source to query and which response message to build, and deduplicates on MSH-10. |
[{SFT}] | Software Segment. Identifies the software product behind the querying application — vendor, product, and version. Optional and repeating; useful when query behaviour or field usage differs across application releases. |
QRD | Original Query Definition. The heart of every QRY message. QRD-1 carries the query date and time; QRD-4 carries a unique query ID that the responding system echoes back in its response, enabling the requester to match each response to its originating query. QRD-6 (Quantity Limited Request) specifies the maximum number of records the requester wants returned — it acts as a row limit on the response. QRD-7 (Who Subject Filter) identifies what category of subject the query concerns, e.g. DEM for demographics or LAB for laboratory results. QRD-8 (What Subject Filter) carries the specific identifier being queried — typically the patient ID — along with the type of data requested. Together, QRD-7 and QRD-8 are the primary filter that the responding system evaluates against its records. |
[QRF] | Query Filter. Optional supplemental criteria that narrow the result set beyond what QRD specifies. QRF-2 and QRF-3 carry a start and end collection date/time range, limiting results to records collected within that window. QRF-5 carries a patient event filter (e.g. a specific visit number or event type). Other QRF fields support ordering and additional selection criteria. When absent, the responding system applies only the QRD filter criteria. |
[ ] = optional, { } = repeating
The compactness of the QRY structure is intentional: all query semantics are concentrated in QRD, with QRF providing secondary refinement. The responding system uses the trigger event in MSH-9 to determine which records to search, then applies QRD and QRF criteria to select and limit the result. The canonical segment pages carry the full field-by-field detail.
Sample QRY message
Note. Constructed for illustration. Patient identifiers, query IDs, dates, and names are fictional.
MSH|^~&|CLNWKS|MERCYGEN|ADT|MERCYGEN|20260604103000||QRY^A19^QRY_A19|QMSG00042|P|2.5.1
QRD|20260604103000|R|I|QID20260604-042|||5^RD|MR98765^^^MERCYGEN^MR|DEM|PID
QRF|ADT|20260101000000|20260604235959
What this sample shows
The QRY^A19 in MSH-9 marks a patient demographics query; the responding system will build an ADR^A19 response. The QRD carries the query timestamp 20260604103000 in QRD-1, a unique query ID QID20260604-042 in QRD-4, a row limit of 5 records in QRD-6, the patient identifier MR98765 scoped to MERCYGEN in QRD-8, and the subject filter DEM (demographics) in QRD-7. The QRF narrows results to ADT events collected between 1 January 2026 and 4 June 2026, using the start and end datetime fields QRF-2 and QRF-3.
Working with QRY messages
QRD-4 is the correlation key
The responding system must echo QRD-4 (query ID) in its response so the requester can match each response to the query that triggered it. When your integration engine fans a single QRY out to multiple source systems or retries a timed-out request, the query ID is the only field that unambiguously ties a response back to its request. Treat it as a required correlation key even though the standard marks it conditionally required.
Honour the quantity limit in QRD-6
QRD-6 (Quantity Limited Request) specifies the maximum number of records the requester is prepared to handle. A responding system that ignores QRD-6 and returns an unbounded result set can overwhelm the requester's buffer or parsing layer. Apply the limit before sending; if the result set exceeds it, some implementations return a continuation pointer so the requester can page through further results.
Validate QRD-7 and QRD-8 together
QRD-7 (Who Subject Filter) and QRD-8 (What Subject Filter) work as a pair: QRD-7 sets the category (e.g. DEM, LAB, PHR) and QRD-8 supplies the specific identifier within that category. Responding systems that mis-read one without the other return results for the wrong subject or reject the query. Confirm the expected values for both fields against the partner's interface specification, as implementations vary in which codes they support.
Prefer QBP for new implementations
QRY is deprecated as of v2.5. New query interfaces should use QBP, which supports named event-based query profiles, richer filter expressions, and a standardised continuation mechanism. When maintaining a legacy QRY interface, document which trigger events and QRD field values the partner supports, because original-mode query behaviour was never as tightly constrained by the standard as QBP profiles are.
Vendor variance. The
QRFsegment is optional and its field usage is inconsistently implemented. Some systems treat the date range inQRF-2/QRF-3as mandatory context; others ignore it entirely and return all records matchingQRD-8. ConfirmQRFsupport and semantics with the responding system before relying on date-range filtering.
FHIR equivalent
There is no published FHIR mapping for QRY. The HL7 v2-to-FHIR Implementation Guide provides no message map for QRY and no ConceptMap for the QRD or QRF segments — QRY is a legacy query protocol that predates the FHIR interaction model and has no structural counterpart in it.
The functional equivalent in a FHIR environment is a FHIR RESTful search request: a GET against the appropriate resource type with search parameters that correspond to the QRD filter criteria (QRD-8 maps loosely to a patient identifier search parameter, QRD-6 maps to _count). For environments that must bridge HL7 v2 queries to a FHIR back end, an integration engine typically translates the QRY trigger event and QRD fields into a FHIR search URL, executes the search, and transforms the FHIR Bundle response back into the appropriate v2 response message. The modern v2 equivalent for new implementations is QBP, which has a cleaner mapping to FHIR search semantics than original-mode QRY.
Common pitfalls
Pitfall. Not echoing QRD-4 in the response. The query ID is the only field that correlates a response to its originating request; a responding system that omits or changes it breaks the requester's ability to match asynchronous responses, especially when multiple queries are in flight simultaneously.
Pitfall. Ignoring the quantity limit in QRD-6. Returning an unbounded result set when the requester specified a limit can overflow parsing buffers or trigger connection timeouts on low-resource clients. Apply the limit before transmitting the response.
Pitfall. Treating QRY as equivalent to QBP. QRY's
QRDfilter criteria are less formally constrained than QBP query profiles, so field semantics vary significantly between implementations. Do not assume that a QRY interface will accept the same filter values or return the same structure as a QBP interface for the same trigger event.
How Vorro handles QRY messages
Vorro receives QRY messages over MLLP, parses the trigger event from MSH-9 to determine the query type, and extracts the filter criteria from QRD and QRF. The query ID in QRD-4 is carried through the entire transaction and echoed in the response so the originating application can correlate results. Vorro applies the quantity limit from QRD-6 to prevent oversized responses, routes the request to the appropriate source system, and returns the paired response message — ADR^A19, ORF^R04, or another — in the format the receiving application expects. Where a destination uses FHIR, Vorro translates the QRD filter criteria into a RESTful search and maps the response Bundle back to the appropriate v2 message, since the v2-to-FHIR Implementation Guide publishes no map for this query protocol.
Related messages
- QBP — the modern replacement for QRY; provides named query profiles and a standardised continuation mechanism.
- ADR — the ADR^A19 response message returned in reply to a QRY^A19 patient demographics query.
- ORF — the ORF^R04 response message returned in reply to a QRY^R02 observation query.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for QRY
- HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for QRD or QRF
- HL7 Messaging Standard Version 2.5.1 product brief
