NEWFree ROI Calculators — quantify what prior auth and siloed data are costing your organization.Prior Auth ROI Siloed Data ROI
HL7 v2Message⏱ 12 min read

HL7 QBP Messages: Query by Parameter

HL7 QBP messages carry a query — a request for data that the sender names by query profile and fills in with parameters, expecting a matching response in return. QBP is the canonical query mechanism introduced in HL7 v2.5: rather than defining a new message type for every kind of question, QBP carries a query name and a list of parameters in a single reusable structure, and the receiver answers with a RSP response (or a tabular or display response, depending on the profile). This page explains what a QBP message represents, the trigger events it carries, every segment the message can contain and what each one holds, and how a parameterized query relates to FHIR. Sample content is constructed for illustration with fictional identifiers.

What a QBP message represents

A QBP message — QBP stands for Query by Parameter — communicates a request for data. The core of the message is the QPD segment, the Query Parameter Definition, which names the query being run in QPD-1 and carries the search criteria in the fields that follow. A second segment, the RCP Response Control Parameter, tells the responder how the answer should be shaped — how much to return, with what priority, and in what delivery modality. Together QPD and RCP are the backbone of every QBP message: the QPD says what is being asked, and the RCP says how the answer should come back.

Unlike an ADT or RDS message, which a source pushes unsolicited to its subscribers, a QBP is solicited — the sender asks a question and waits for an answer. The exchange is therefore a request/response pair: the querying system sends the QBP, and the responding system returns a matching response message carrying the data, an acknowledgment, and an echo of the query so the requester can correlate the answer to its question. Because the query is named rather than free-form, both sides must agree in advance on the query profile — the named set of parameters and the shape of the response — that QPD-1 identifies.

When a QBP message is sent

A QBP message is sent whenever one system needs to pull data from another on demand rather than wait for it to be pushed. Typical uses are looking up a patient's demographics, finding candidate patient records that match a set of traits, retrieving the identifiers a patient is known by in another system, or asking a master person index to allocate a new identifier. The query is real-time and conversational: the requester blocks (or correlates asynchronously) on the response, and large result sets are paged back over several messages using the continuation pointer.

Trigger events

The QBP message type carries several trigger events, each tied to a query profile and to the kind of response the profile expects. The events verified in HL7 v2.5.1 are:

  • QBP^Q11 – Query by parameter requesting an RSP segment-pattern response.
  • QBP^Q13 – Query by parameter requesting an RTB tabular response.
  • QBP^Q15 – Query by parameter requesting an RDY display response.
  • QBP^Q21 – Get person demographics.
  • QBP^Q22 – Find candidates.
  • QBP^Q23 – Get corresponding identifiers.
  • QBP^Q24 – Allocate identifiers.
  • QBP^Q25 – Personnel information by segment query.

The event in MSH-9 selects the query profile and the response style. Q11, Q13, and Q15 are the generic Chapter 5 query events that differ only in the form of the response — a segment pattern (RSP), a table (RTB), or a display (RDY) — while Q21 through Q25 are named queries whose request reuses the same QBP^Q21 structure and which answer with an RSP. The segment backbone of the request is the same across all of them; what varies is the query named in QPD-1, the parameters that follow it, and the response message type the profile defines.

Integration topology

The diagram shows the querying system asking a question through the integration engine and receiving a matching response from the system that holds the data.

{{diagram: querying system → QBP query → integration engine → responding system (MPI / registry / EHR) → RSP response → querying system}}

Typical senders: any system that needs to look up data — an EHR, an ordering application, a registration system, or a downstream clinical app.

Typical receivers: the system of record for the data being asked about — a master person index, an enterprise master patient index, a registry, or an EHR.

Direction: bidirectional request/response — the QBP goes out and a matching response comes back, in contrast to the unidirectional broadcast of an ADT or RDS feed.

Segments in a QBP message

The QBP message is short and parameter-driven: its backbone is the QPD that names the query and carries its parameters and the RCP that controls the response, framed by the MSH header and an optional continuation pointer. The structure below is the QBP_Q11 / QBP_Q21 form verified in HL7 v2.5.1; Q11, Q21, Q22, Q23, Q24, and Q25 all use this same segment layout, and Q13 and Q15 differ only in the response message they request, not in the request structure. 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.

SegmentDescription
MSHMessage Header. Opens every QBP message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (for example QBP^Q11), carries the message control id in MSH-10, and pins the HL7 version. The event in MSH-9 selects the query profile and the expected response style.
[{SFT}]Software Segment. Identifies the software product behind the sender — vendor, product, and version. Optional and repeating; useful when query behaviour differs across releases of the querying system.
QPDQuery Parameter Definition. The core of the message. QPD-1 names the query being run — the Message Query Name that identifies the agreed query profile — and QPD-2 carries the query tag the requester uses to correlate the response. The fields after QPD-2 hold the query parameters themselves; they are positional, understood from the profile named in QPD-1 rather than labelled in the message. Required.
RCPResponse Control Parameter. Tells the responder how to shape the answer: the query priority in RCP-1 (the time frame in which a response is expected), the quantity-limited request in RCP-2 (the maximum amount of data to return, by default counted in segments), and the response modality in RCP-3 (the timing and grouping of the response messages). Required.
[DSC]Continuation Pointer. Carries the continuation pointer when the requester is asking for the next page of a result set that was returned across multiple messages. Absent on an initial query; present only on a continuation request. Optional.

[ ] = optional, { } = repeating

The whole message is just five possible segments, and only MSH, QPD, and RCP are required — the expressive power of QBP is in the parameters carried inside QPD, not in a long segment list. The canonical segment pages carry the full field-by-field detail.

The matching response

A QBP query is answered by a response message whose type the query profile fixes. For the generic Chapter 5 events the choice is explicit in the trigger: Q11 requests an RSP segment-pattern response, Q13 requests an RTB tabular response, and Q15 requests an RDY display response. The named queries Q21 through Q25 answer with an RSP.

The RSP response (verified here in its RSP_K11 form) carries, after its MSH and optional SFT: an MSA acknowledging the query, an optional ERR when something went wrong, a QAK query acknowledgment, an echo of the QPD, the response data itself, and an optional DSC continuation pointer when the result is paged. The QAK is where the requester reads the outcome: QAK-1 echoes the query tag from QPD-2, QAK-2 carries the query response status — important when a query simply found nothing, which is a valid outcome rather than an error — QAK-3 names the query that was answered, and QAK-4 gives the total hit count. Echoing the QPD and the query tag lets the requester correlate the answer to the question it asked, which matters when several queries are in flight at once.

Sample QBP message

Note. Constructed for illustration. Patient identifiers, names, query tags, and the query name are fictional.

MSH|^~&|EHR|MERCYGEN|MPI|MERCYGEN|202006031200||QBP^Q22^QBP_Q21|MSG00021|P|2.5.1
QPD|Q22^Find Candidates^HL70471|QRY00042|@PID.5.1^DOE~@PID.5.2^JOHN~@PID.7^19800101
RCP|I|10^RD

What this sample shows

The QBP^Q22 in MSH-9 marks a "Find candidates" query, sent from the EHR to the master person index, and it uses the QBP_Q21 message structure. The QPD names the query in QPD-1 (Q22^Find Candidates), tags it QRY00042 in QPD-2 so the response can be correlated, and carries the search criteria after the tag — here a family name, given name, and date of birth expressed as query parameters. The RCP sets an immediate query priority (I in RCP-1) and limits the response to 10 records (RCP-2, 10^RD). The responder would answer with an RSP carrying a QAK hit count, an echo of this QPD, and the matching candidate records.

Working with QBP messages

Read the query from QPD-1, then the parameters

QPD-1 names the query profile; everything after QPD-2 is parameters whose meaning is positional and defined by that profile, not labelled in the message. A receiver must dispatch on QPD-1 (and the event in MSH-9) to know how to interpret the fields that follow, because the same field position means different things under different query names.

Correlate the response by the query tag

The query tag in QPD-2 is the requester's correlation key: the responder echoes it in QAK-1 and it stays constant across every continuation message for the query, unlike the message control id in MSH-10 which changes per message. Correlate responses to outstanding queries on the query tag, especially when several queries share a channel.

Treat "no data found" as a valid answer

A query that matches nothing is not an error. The outcome lives in QAK-2, the query response status, which distinguishes "data found", "no data found", and error conditions. Read QAK-2 rather than inferring failure from an empty response, and reserve ERR handling for genuine errors.

Paging large result sets

When a result set is larger than the RCP-2 limit or the responder chooses to fragment it, the response carries a DSC continuation pointer. To fetch the next page, the requester sends a follow-up QBP carrying that pointer in its own DSC. On an initial query the DSC is absent.

Vendor variance. The query profile named in QPD-1 is an agreement between the two systems, and the parameter set, the field positions, and even the response message type are fixed by that profile rather than by the bare QBP structure. Confirm a partner's query profiles and parameter usage against their interface specification rather than assuming the base standard.

FHIR equivalent

Conceptually, a parameterized query corresponds to a FHIR RESTful search — a named query with parameters maps naturally onto a search interaction against a resource type, or onto a messaging query — and the RSP response corresponds to the searchset Bundle a search returns. The query itself produces no resource; it is a request, and the data comes back in the response.

There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for QBP and no ConceptMap for the QPD or RCP segments. The IG's published message maps cover event-driven messages — an ADT subset and a handful of order, result, dispense, document, and scheduling messages — not the query/response interaction, which FHIR expresses through its search API rather than through a mapped message. Any correspondence between a QBP query and a FHIR search is therefore designed by hand against the specific query profile, not derived from an official map.

Common pitfalls

Pitfall. Dispatching on MSH-9 alone. The trigger event selects the response style, but the actual question lives in QPD-1 and its parameters; routing without reading QPD-1 cannot distinguish two queries that share a structure, such as Q21 through Q25 on QBP_Q21.

Pitfall. Treating an empty response as a failure. "No data found" is reported in QAK-2 as a normal status, not as an ERR; raising an error on an empty result misreports a legitimate answer.

Pitfall. Correlating on MSH-10 instead of the query tag. The message control id changes per message, so it cannot tie a continuation response back to the original query; use the query tag in QPD-2 / QAK-1.

How Vorro handles QBP messages

Vorro accepts a QBP query over MLLP or another transport, dispatches on the trigger event in MSH-9 together with the query named in QPD-1, applies the response limits in RCP, and routes the query to the system that holds the data — a master person index, a registry, or an EHR. Vorro returns the matching RSP response, echoing the query tag so the requester can correlate it, and pages large result sets with the DSC continuation pointer. Because the v2-to-FHIR Implementation Guide publishes no map for QBP, any bridge to a FHIR search interaction is configured per query profile rather than derived from an official map.

  • RSP — the segment-pattern response that answers a QBP query.
  • QRY — the older original-mode query that QBP supersedes.
  • QCN — the query cancellation message used to withdraw an outstanding query.

Sources

</invoke>
← Back to HL7 v2 Guide

Ready to Integrate This Into Your Workflow?

Talk to a Vorro expert about implementing HL7 v2 in your specific environment.

Browse HL7 v2 Guides
HL7 QBP Messages: Query by Parameter | Vorro Academy | Vorro