HL7 Query Messages: QBP & RSP

HL7 v2 query messages let one system request data from another on demand, rather than waiting for an unsolicited feed. The modern query/response pair is QBP (Query by Parameter) — the request — answered by RSP (Segment Pattern Response) — the reply. QBP/RSP was introduced in HL7 v2.4 and replaced the older QRY/ADR query pair, which has since been deprecated.

Message	Name	Role
QBP	Query by Parameter	The request — names the query and supplies search parameters
RSP	Segment Pattern Response	The reply — returns a query status plus the requested data segments

A QBP message carries a query name that identifies which predefined query the receiver should run. Both systems must agree in advance on the supported query names and the parameters each one accepts.

Each query is identified by a trigger event in MSH-9. A QBP event is answered by the corresponding RSP event.

Query	Response	Purpose
QBP^Q11	RSP^K11	Query for a list of results / patient data by parameter
QBP^Q21	RSP^K21	Get Person Demographics — patient demographics lookup
QBP^Q22	RSP^K22	Find Candidates — Master Patient Index probabilistic matching
QBP^Q23	RSP^K23	Get Corresponding Identifiers — cross-reference patient IDs

QBP^Q11/RSP^K11 is the general-purpose query/response structure used across many domains, including immunization registries. QBP^Q22/RSP^K22 (“Find Candidates”) is the standard Master Patient Index (MPI) query for resolving a patient against an enterprise identity registry.

Segment	Name	Required	Purpose
MSH	Message Header	Yes	Sender, receiver, message type, version
QPD	Query Parameter Definition	Yes	Query name and the search parameters
RCP	Response Control Parameter	Yes	Controls and limits the response

Segment	Name	Required	Purpose
MSH	Message Header	Yes	Sender, receiver, message type, version
MSA	Message Acknowledgment	Yes	Accept/error/reject status of the query message
ERR	Error	No	Error detail when MSA-1 is AE or AR
QAK	Query Acknowledgment	Yes	Query status — whether data was found
QPD	Query Parameter Definition	Yes	Echoes the QPD from the original query
data segments	—	No	The requested data (e.g., PID, OBX), present when results are found

The RSP echoes both an MSA (acknowledging the query message itself) and a QAK (reporting the outcome of running the query). The data segments that follow depend on the query — an immunization query returns patient and immunization segments; an MPI query returns candidate patient records.

The QPD segment defines what is being asked. It carries the query name and one or more search parameters.

Field	ID	Description
Message Query Name	QPD-1	Identifies the predefined query (e.g., Z34^Request Immunization History)
Query Tag	QPD-2	A unique tag the requester assigns to correlate the response
User Parameters	QPD-3+	The search parameters — fields vary by query name

The fields after QPD-2 are query-specific. For an immunization history query, they typically include the patient’s name, date of birth, and identifiers.

The RCP segment controls how the response is returned.

Field	ID	Description
Query Priority	RCP-1	I (Immediate) or D (Deferred)
Quantity Limited Request	RCP-2	Maximum number of records to return
Response Modality	RCP-3	R (Real-time), T (Batch), etc.

RCP-2 is how a requester caps the result set — useful when a broad query could match many records.

The QAK segment appears in the RSP and reports the outcome of running the query. It is distinct from the MSA, which only acknowledges that the query message was received.

Field	ID	Description
Query Tag	QAK-1	Echoes QPD-2 from the request for correlation
Query Response Status	QAK-2	The query outcome — see codes below
Message Query Name	QAK-3	Echoes the query name from QPD-1
Hit Count Total	QAK-4	Number of records matched (when reported)

Code	Meaning	Description
OK	Data found, no errors	Query succeeded and returned results
NF	No data found, no errors	Query ran successfully but matched nothing
AE	Application error	The query could not be processed
AR	Application reject	The query was rejected

NF is an important distinction — it means the query executed correctly but found no matching records, which is different from an error.

A common use case is querying an Immunization Information System (IIS) for a patient’s vaccination history. The request is a QBP^Q11; the response is a RSP^K11.

When QAK-2 is NF instead of OK, the RSP still returns the MSA, QAK, and echoed QPD, but no patient or data segments follow — the query ran successfully and simply matched nothing.

Browse the HL7 sample messages catalog for more annotated examples, each ready to copy as valid HL7 or download as a .hl7 file.

Before v2.4, queries used the QRY (Query) message answered by ADR (Application Data Response), with the query criteria carried in a QRD/QRF segment pair. QRY/ADR is now deprecated in favor of QBP/RSP.

Aspect	QRY/ADR (deprecated)	QBP/RSP (current)
Request message	QRY	QBP
Response message	ADR	RSP
Query criteria segment	QRD / QRF	QPD
Response control	QRD fields	RCP
Query outcome reporting	Limited	QAK segment

New interfaces should implement QBP/RSP. QRY/ADR may still appear on long-lived legacy interfaces.

QBP queries are not free-form. Each query name (QPD-1) corresponds to a predefined conformance profile that specifies exactly which parameters are accepted and which segments the RSP returns. Both the requesting and responding systems must implement the same profile. Immunization registries, for example, follow the CDC HL7 v2.5.1 Implementation Guide for Immunization Messaging, which defines the Z34 (request immunization history) and Z44 query profiles.

Two identifiers tie a query to its response:

1. MSH-10 / MSA-2 — the message control ID correlates the RSP message to the QBP message, exactly as with any ACK.
2. QPD-2 / QAK-1 — the query tag correlates the query itself, which matters when query handling is asynchronous or queued.

QBP^Q22 (“Find Candidates”) is the standard query for an enterprise Master Patient Index. The requester supplies partial demographics in the QPD; the MPI runs probabilistic matching and returns a RSP^K22 containing zero or more candidate patient records, often with a match-confidence score. The requester then resolves the patient — automatically above a confidence threshold, or by routing lower-confidence matches to a human reviewer.

Treat QAK-2 = NF as a valid, successful outcome, not an error. A patient with no immunization history on file, or an MPI search with no candidates, both legitimately return NF. Reserve error handling for AE and AR and for a missing or malformed RSP.