HL7 QAK Segment: Query Acknowledgment

The QAK (Query Acknowledgment) segment appears in a response message and tells the requesting application how the query was processed. It echoes the Query Tag that ties the response back to the original request, reports a Query Response Status that says whether data was found, and carries hit-counting fields that describe how many records matched and how many remain. QAK is the response-side counterpart to the request-side query definition: where the request specifies what to look for, QAK reports what happened when the search ran.

Purpose

The purpose of QAK is to communicate the disposition of a query within a response message. It answers three practical questions for the receiving system: did the query succeed, how many records matched the search criteria, and how much of the result set is being returned in this transmission. The Query Response Status field distinguishes an empty result ("no data found") from an error, an applied filter, or a successful match, which lets a client decide whether to retry, page for more data, or stop. Because QAK also repeats the Query Tag, it preserves the correlation between an asynchronous response and the request that triggered it.

Used in

QAK is part of the modern query group introduced with the Query by Parameter framework. It is used in:

RSP (response) query messages, where QAK leads the response and summarizes the query outcome. See QBP and the query framework.

In a typical exchange, a client sends a QBP (query by parameter) message containing a QPD request and an RCP response-control segment. The responder replies with an RSP message in which QID and QAK lead the response: QID restates the query identity and QAK reports its status and hit counts before the matching data segments follow.

Field-by-field reference

Source: HAPI HL7v2 v2.5.1 javadocs (QAK.html) for sequence, name, data type, and repetition. Length is not published in the javadocs (—); Required and Table # are filled from the HL7 v2.5.1 standard where well-established.

Seq	Name	Data Type	Length	Req	Repeat	Table #	Description
QAK-1	Query Tag	st	—	O	—	—	Echoes the request Query Tag for correlation
QAK-2	Query Response Status	id	—	R	—	HL70208	Outcome of the query, e.g. OK or NF
QAK-3	Message Query Name	ce	—	O	—	—	Identifies the named query that was run
QAK-4	Hit Count Total	nm	—	O	—	—	Total number of records matching the query
QAK-5	This payload	nm	—	O	—	—	Number of matching records in this response
QAK-6	Hits remaining	nm	—	O	—	—	Records still to be returned after this payload

Most-used fields

QAK-1 Query Tag: the primary correlation key. Receivers match this value against the Query Tag they sent in QPD-2 to pair a response with its request.
QAK-2 Query Response Status: the field most integration logic branches on. Values from HL70208 such as OK (data found), NF (no data found), AE (application error), and AR (application reject) drive retry and error handling.
QAK-4 Hit Count Total, QAK-5 This payload, QAK-6 Hits remaining: the paging triad. Together they tell a client whether continuation queries are needed to retrieve the full result set.

Version differences (2.3 to 2.8.2)

QAK is a member of the Query by Parameter family that matured in the 2.4 and 2.5 era. Earlier query messaging in 2.3 relied on the older query group (QRD and QRF) rather than the QPD/QAK/QID/RCP set, so QAK as used here is effectively a 2.4-and-later construct; in 2.3 the role of reporting query status was largely carried by fields in QRD and the message acknowledgment. From 2.4 through 2.8.2 the QAK structure is stable: the Query Tag, Query Response Status, Message Query Name, and the three hit-count fields remain in the same sequence. Across these versions the Message Query Name field is described with the CE data type in 2.5.1; in later releases the underlying coded element conventions trend toward CWE, but the field position and meaning are unchanged. Always confirm the Query Response Status table (HL70208) against the specific version your trading partner implements, as permitted values were refined over time.

Common mistakes

Treating QAK-2 as free text. Query Response Status is an ID drawn from HL70208; sending an unlisted value breaks receiver branching logic.
Confusing "no data found" with an error. NF is a successful query that simply matched zero records; failing to distinguish it from AE or AR causes spurious retries.
Dropping QAK-1. Omitting the Query Tag breaks correlation, especially for asynchronous responses where multiple queries are in flight.
Misusing the hit-count fields. QAK-5 (this payload) should reflect only the records in the current response, not the total; mixing it up with QAK-4 (total) confuses paging.
Assuming QAK repeats. None of the QAK fields repeat in v2.5.1; build parsers that read single occurrences.

Examples

Minimal valid segment (status only, the field the standard requires):

QAK||OK

Fully-populated segment:

QAK|Q4815162342|OK|Z44^Demographics Query^HL70471|3|3|0

Annotated breakdown:

QAK|Q4815162342|OK|Z44^Demographics Query^HL70471|3|3|0
    |          |  |                              | | |
    |          |  |                              | | +-> QAK-6 Hits remaining = 0
    |          |  |                              | +---> QAK-5 This payload = 3
    |          |  |                              +-----> QAK-4 Hit Count Total = 3
    |          |  +------------------------------------> QAK-3 Message Query Name = Z44
    |          +---------------------------------------> QAK-2 Query Response Status = OK (data found)
    +--------------------------------------------------> QAK-1 Query Tag = Q4815162342 (echoes request)

In-context excerpt 1, a successful patient demographics response (RSP^K11) where QID and QAK lead the response:

MSH|^~&|MPI|CENTRAL|EHR|CLINIC_A|20260610101500||RSP^K11^RSP_K11|MSG00099|P|2.5.1
MSA|AA|MSG00042
QID|Q4815162342|Z44^Demographics Query^HL70471
QAK|Q4815162342|OK|Z44^Demographics Query^HL70471|1|1|0
PID|1||MR12345^^^CLINIC_A^MR||DOE^JANE^Q||19850214|F

In-context excerpt 2, a "no data found" response where QAK reports zero hits:

MSH|^~&|MPI|CENTRAL|EHR|CLINIC_A|20260610101530||RSP^K11^RSP_K11|MSG00100|P|2.5.1
MSA|AA|MSG00043
QID|Q7350199001|Z44^Demographics Query^HL70471
QAK|Q7350199001|NF|Z44^Demographics Query^HL70471|0|0|0

FHIR mapping

QAK is not mapped at the segment level. No segment-level ConceptMap is published in the v2-to-FHIR Implementation Guide for QAK because query/response infrastructure has no direct FHIR resource equivalent. FHIR expresses queries as RESTful search interactions and returns results in a searchset Bundle: the role QAK plays is approximated by Bundle.total (analogous to the hit count), the OperationOutcome resource (analogous to error or status reporting), and Bundle paging links (analogous to the hits-remaining and payload fields). There is no one-to-one field mapping, so engines bridging v2 query traffic to FHIR synthesize this information from the search response rather than translating QAK directly.

Engine considerations

Most interface engines model QAK as a flat, non-repeating segment and expose its six fields as simple variables. When routing RSP messages, engines commonly key on QAK-2 to branch: route OK responses to data-handling logic, NF to an "empty result" path, and AE or AR to an error queue. Because QAK-1 mirrors the request Query Tag, engines that correlate asynchronous responses store the outgoing tag and match it on inbound QAK-1. Paging-aware engines read QAK-4 through QAK-6 to decide whether to issue a continuation query. Validation rules should assert that QAK-2 is present and drawn from HL70208, and that the hit-count fields, when present, are numeric.

How Vorro parses and produces QAK

When Vorro parses an inbound RSP message, it reads QAK as a positional segment and normalizes each field into a structured response object: the Query Tag becomes the correlation key, the Query Response Status is validated against HL70208, and the three hit-count fields are coerced to integers for paging decisions. Vorro pairs the parsed QAK-1 with the original QPD-2 Query Tag to reunite the response with its request. When producing a QAK in a response it builds, Vorro sets the status from the search outcome, populates the hit counts from the result set, and echoes the Query Tag verbatim so downstream clients can correlate. Unset optional fields are emitted as empty so positions stay aligned.

Sources

← Back to HL7 v2 Guide