HL7 QVR messages ask a responding system for the events it has recorded within a specified time window — the past ADT events, scheduled appointments, observations, or other event-typed records that fall between a start and an end date. A QVR message is the request half of a query-response exchange: a requesting system parameterizes the query name, the event-type filter, and the time-window criteria, and the responder replies with the matching records in an RSP message. This page explains what a QVR message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a QVR query relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
What a QVR message represents
A QVR message — QVR stands for Query for Previous Events — carries a parameterized request for events the responder has on file within a time window. The core of the message is the QPD segment, which carries the query parameters: the message query name in QPD-1 that names the published query the requester is invoking, the query tag in QPD-2 that the responder echoes so the requester can match the response to its outstanding query, and the user parameters in QPD-3 that carry the event-type filter and the time-window criteria (start date/time and end date/time). Each QVR records one query, not a result.
QVR is a query message: it is sent to elicit an RSP reply rather than as an unsolicited notification. The RCP segment carries response control parameters — the query priority in RCP-1 (I for immediate, D for deferred), the response quantity limit in RCP-2, and the modify indicator in RCP-5 — so the responder knows how to package and pace the reply. The sender is the application building a view of past events, and the receiver is the system of record that holds them. Because the request describes events that have already occurred, the QPD is the authoritative statement of what is being asked, while the surrounding RCP carries the response shaping.
When a QVR message is sent
A QVR message is sent when a requesting system needs the past events a responder has recorded within a time window — for example, the ADT events for a patient between two dates, the scheduled appointments for a resource over a shift, or the observations posted for an encounter. When the requester has the query parameters in hand, it issues a QVR message naming the published query in QPD and the response shape in RCP, and the responder replies with the matching records in an RSP message — typically RSP^ZV1 or an RSP variant aligned to the query.
Trigger event
The QVR message type carries a single trigger event:
QVR^Q17– Query for previous events.
Because QVR has one trigger event, the responder's handling turns on the query name in QPD-1 and the event-type and time-window parameters in QPD-3 — what is being asked and over what window — rather than on the trigger code in MSH-9.
Integration topology
The diagram shows the requesting system issuing the parameterized query and the system of record replying through the integration engine with the matching past events.
{{diagram: querying application → QVR query → integration engine → system of record → RSP response → integration engine → querying application}}
Typical senders: any application building a view of past events — reporting, analytics, audit, reconciliation, or a clinical viewer assembling a timeline.
Typical receivers: the system of record that holds the events — ADT, scheduling, observation, or audit log.
Direction: the request leg of a synchronous query-response exchange — the QVR travels from the requesting application to the system of record, and the matching RSP^ZV1 reply returns over the same channel.
Segments in a QVR message
The QVR_Q17 message opens with MSH, optionally carries one or more SFT software segments, and then carries the query itself: QPD with its parameters, an optional QBP for time-bounded filter extensions, the required RCP for response control, and an optional DSC for continuation. 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 QVR message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (QVR^Q17), carries the message control id in MSH-10, and pins the HL7 version. Receivers route on MSH-9 and deduplicate on MSH-10. |
[{SFT}] | Software. Identifies the software that produced the query — vendor, product, version, install date. Optional and repeating; helps the responder reason about quirks of the requesting application. |
QPD | Query Parameter Definition. The core of the message. QPD-1 carries the message query name that names the published query being invoked, QPD-2 carries the query tag the responder echoes so the requester can match the response to its query, and QPD-3 carries the user parameters — the event-type filter and the time-window criteria (start date/time and end date/time) that scope which past events are returned. Required. |
[QBP] | Query By Parameter. An extension that refines QPD with additional time-bounded filter criteria when the published query supports them. Optional; present when the requester needs to layer a finer filter on top of the time window in QPD-3. |
RCP | Response Control Parameter. Shapes the response. RCP-1 carries the query priority — I for immediate or D for deferred — RCP-2 carries the quantity-limited request that caps how many records the responder returns in one reply, and RCP-5 carries the modify indicator that signals whether the query modifies an earlier one. Required. |
[DSC] | Continuation Pointer. Supports continuation of a large response across messages — the pointer the requester sends back to fetch the next segment of results. Optional, closing the query. |
[ ] = optional, { } = repeating
The structure closely follows QBP but is purpose-built for time-windowed event retrieval — the event-type filter and the start/end date-time in QPD-3 are what distinguish a QVR from a generic query by parameter. The canonical segment pages carry the full field-by-field detail.
Sample QVR message
Note. Constructed for illustration. Patient identifiers, query tags, dates, and names are fictional.
MSH|^~&|VIEWER|MERCYGEN|ADT|MERCYGEN|202006150930||QVR^Q17^QVR_Q17|MSG00077|P|2.5.1
QPD|Q17^Query for Previous Events^HL70471|QRY00077|ADT^A01~A03~A08|MR12345^^^MERCYGEN^MR|202006010000|202006150000
RCP|I|50^RD|R
What this sample shows
The QVR^Q17 in MSH-9 marks a query for previous events. QPD names the published query in QPD-1 (Q17^Query for Previous Events^HL70471), carries the query tag QRY00077 in QPD-2 so the response can be matched back, and in QPD-3 carries the user parameters — the event-type filter (ADT^A01~A03~A08 — admits, discharges, and updates), the patient identifier MR12345, and the time window from 202006010000 through 202006150000. The RCP sets the query priority to I (immediate) in RCP-1, limits the quantity to 50 records in RCP-2, and sets the modify indicator to R in RCP-5.
Working with QVR messages
Name the published query in QPD-1
A QVR is parameterized against a published query — the responder needs to know which query it is being asked to run. Carry the message query name in QPD-1 (for QVR^Q17, this is Q17^Query for Previous Events^HL70471) and confirm both ends agree on the query identifier before going live, or the responder will return an error rather than results.
Carry the time window and event type in QPD-3
The event-type filter and the start/end date-time live in QPD-3 as user parameters, not in a separate filter segment. Place the event-type code (or a repeating list of codes) and the inclusive start and exclusive end of the window in the user parameters defined by the published query, and the responder will scope its results to that window.
Tag the query and match the response
QPD-2 carries the query tag the responder echoes back in its RSP^ZV1 reply. Generate a tag that is unique within the requester's outstanding queries, store it with the request, and match incoming responses by tag rather than by MSH-10 alone — the message control id and the query tag are not interchangeable.
Shape the response with RCP
A large time window can return many events. Set the priority in RCP-1 to I only when an immediate, synchronous reply is acceptable, and cap the response with RCP-2 (for example 50^RD for the first 50 records) so the responder can page the result through DSC rather than returning an unbounded reply.
Vendor variance. The optional
QBPextension for time-bounded filters is not used by every system. Some responders carry all filter criteria — including the time window — in the user parameters ofQPD-3; others accept theQBPextension for finer filters layered on top of the window. Confirm a partner's field usage against their interface specification rather than assuming the base standard.
FHIR equivalent
A query for past events within a time window corresponds, in FHIR, to a RESTful search rather than to a messaging exchange. The closest general-purpose target is the AuditEvent resource with date parameters; for a query scoped to a specific clinical resource type, the search runs against that resource (for example Encounter?patient=…&date=geXX&date=leYY for past admissions, Appointment?date=geXX&date=leYY for scheduled appointments, or Observation?patient=…&date=geXX&date=leYY for observations).
There is no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for QVR_Q17. A FHIR representation produced from a QVR query is therefore expressed manually, translating the published query name in QPD-1 to a resource endpoint, the event-type filter in QPD-3 to a _type or resource-specific code parameter, and the start/end date-time in QPD-3 to FHIR date search parameters (date=geXX&date=leYY).
Common pitfalls
Pitfall. Omitting the query tag in
QPD-2or reusing one across outstanding queries. Without a unique tag, the requester cannot reliably match an incomingRSP^ZV1to the query it answers, and responses cross-link to the wrong request.
Pitfall. Treating the time window in
QPD-3as a free-text range. The user parameters are positional and typed against the published query — a start and end must be valid HL7 date/time values, not strings, or the responder will reject the query.
Pitfall. Issuing a QVR with
I(immediate) priority across an unbounded time window. A long window with no quantity limit inRCP-2can produce a response that exceeds practical message sizes; cap the response and useDSCfor continuation instead.
How Vorro handles QVR messages
Vorro builds each QVR query with the correct published query name in QPD-1, generates and tracks a unique query tag in QPD-2, and assembles the event-type filter and the start/end date-time in QPD-3 to match the responder's published query definition. Vorro sets the response shape in RCP — priority, quantity limit, modify indicator — caps unbounded windows so responders can page results, follows DSC to gather continued replies, and correlates each incoming RSP^ZV1 back to its originating query by tag. Where a FHIR destination is configured, Vorro translates the QVR query to a RESTful search — against AuditEvent or the resource type of interest — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message.
Related messages
- QBP — the general query by parameter that QVR's structure closely follows, used when the query is not scoped to past events within a time window.
- RSP — the segment-pattern response that returns the events matching a QVR query (typically
RSP^ZV1). - QRY — the original-mode query message that predates the parameterized QPD/RCP query model.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for QVR_Q17
- HL7 v2-to-FHIR IG — segment maps index
- HL7 Messaging Standard Version 2.5.1 product brief
