HL7 RTB Messages: Tabular Data Response

HL7 RTB messages return query results in a structured tabular format — a schema definition followed by one row segment per matching record. An RTB message is the server-side response to a QBP^Q13 query, and is chosen when the querying system wants plain tabular data rather than the segment-pattern response that an RSP message provides. This page explains what an RTB message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how an RTB tabular response relates to FHIR. Sample content is constructed for illustration with fictional identifiers.

What an RTB message represents

An RTB message — RTB stands for Tabular Data Response — delivers query results as a two-part structure: a schema and a set of data rows. The RDF (Row Definition) segment declares the table schema, listing the column count and, for each column, its name, HL7 data type, and maximum length. Each RDT (Row Data) segment that follows carries one result row, with its fields corresponding positionally to the columns defined in RDF.

The sender is the system that holds the queried data — a server, registry, or repository — and the receiver is the system that issued the original QBP^Q13 query. RTB is explicitly chosen over RSP when the querying system wants to consume results as tabular rows rather than as a sequence of typed HL7 segments. Because the schema and data are separated, the receiver can process an RTB response generically without knowing in advance the HL7 segment structure of the queried domain.

When an RTB message is sent

An RTB message is sent in direct response to a QBP^Q13 tabular query. The responding server evaluates the query parameters echoed in the QPD segment, assembles the matching rows, and returns the full result set — or the next page of it when a DSC continuation pointer was provided in the original query. If the query produces no results the server still returns an RTB message; it simply contains no RDT segments, and the QAK segment carries the NF (no data found) acknowledgement code.

Trigger event

The RTB message type carries a single trigger event:

• RTB^K13 — Tabular Data Response, in reply to a QBP^Q13 tabular query.

Because RTB has one trigger event, the receiver's handling turns on the contents of QAK — specifically the query response status — and on the column definitions in RDF, rather than on the trigger code in MSH-9.

Integration topology

The diagram shows the querying system sending a QBP^Q13 through the integration engine and receiving an RTB^K13 tabular response in return.

{{diagram: querying system → QBP^Q13 → integration engine → data server → RTB^K13 → integration engine → querying system}}

Typical senders: clinical data repository, patient registry, laboratory information system, pharmacy system, or any HL7 query server configured to return tabular responses.

Typical receivers: clinical workstation, integration engine, reporting application, or any system that issued a QBP^Q13 query and expects structured rows.

Direction: request/response — the querying system initiates with a QBP^Q13 and the responding server replies with RTB^K13.

Segments in an RTB message

The RTB_K13 message is organised into a fixed outer shell and an optional result block. The outer shell — MSH, MSA, optional ERR segments, QAK, and QPD — is always present and conveys the acknowledgement status and the echoed query parameters. The result block — RDF and the repeating RDT segments — carries the actual data and is omitted when the query returns no rows. The optional DSC closes the message when more pages remain. 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.

[ ] = optional, { } = repeating

The RDF segment acts as the table header and must precede the RDT rows. A receiver that encounters an RDT without a preceding RDF cannot safely interpret the row's fields. The canonical segment pages carry the full field-by-field detail.

Sample RTB message

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

MSH|^~&|PATREGISTRY|MERCYGEN|QUERYSYS|MERCYGEN|20260604083000||RTB^K13^RTB_K13|MSG00045|P|2.5.1
MSA|AA|QRY88821
QAK|QRY88821|OK||3|0
QPD|Q13^Query by Parameter^HL7nnnn|QRY88821|Smith^John
RDF|3|PatientID^CX^20~PatientName^XPN^48~DateOfBirth^DT^8
RDT|MR10011^^^MERCYGEN^MR|Smith^John^A|19720315
RDT|MR10027^^^MERCYGEN^MR|Smith^Jonathan^B|19651122
RDT|MR10093^^^MERCYGEN^MR|Smith^John^C|19900807

What this sample shows

The RTB^K13 in MSH-9 marks a tabular data response. MSA carries AA (accept acknowledgement) and echoes the query control id QRY88821, matching the response to the originating query. QAK reports OK in QAK-2, a hit count of 3 in QAK-4, and 0 remaining hits in QAK-5, indicating that all results fit in this single message. QPD echoes the original query parameters — query name Q13 and search string Smith^John. RDF declares three columns: PatientID (type CX, max 20 characters), PatientName (type XPN, max 48 characters), and DateOfBirth (type DT, max 8 characters). Each of the three RDT segments carries one patient row, with fields aligned positionally to those columns. No DSC is present because the result set is complete.

Working with RTB messages

Parse RDF before reading any RDT

The column order, data types, and maximum lengths in RDF govern how each RDT row must be interpreted. Always parse RDF first and build a positional column map before reading any RDT. A server may return columns in a different order or with a different count than a previous response if the query profile or server version has changed.

Use QAK for flow control

QAK-2 determines whether result segments will be present at all. An NF status means no rows follow and no RDF is present; treat this as an empty result set, not an error. An AE or AR status means an ERR segment is present with the cause. Do not attempt to parse RDT rows until QAK-2 is confirmed as OK.

Handle paged responses with DSC

When DSC is present, the result set continues beyond this message. Capture the pointer value in DSC-1 and submit it in the next QBP^Q13 continuation request. Reassemble pages in arrival order, since a paged RTB sequence shares a single RDF schema — the first page defines the columns and subsequent pages contain only RDT rows.

Correlate the response to the query

Always match the query tag in QAK-1 and the control id in MSA-2 against the originating QBP^Q13. In asynchronous environments, responses may arrive out of order; the query tag is the reliable correlation key.

Vendor variance. Some server implementations omit RDF when the column schema is considered implicit from the query profile name in QPD-1. Confirm a partner's field usage against their interface specification — do not assume RDF is always present even when rows are returned.

FHIR equivalent

An RTB tabular response is conceptually equivalent to a FHIR Bundle of type searchset, where each RDT row maps to a Bundle entry and the resource type is determined by the query domain (for example, Patient, Observation, or Medication).

There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for RTB_K13 — the tabular query/response pattern has no direct counterpart in the FHIR RESTful query model, where search results are always returned as typed resources in a Bundle rather than as schema-defined rows. A FHIR Bundle searchset produced from an RTB response is therefore constructed manually, deriving the resource type from the query profile and mapping each RDT column to the corresponding resource element using the column names declared in RDF.

Common pitfalls

Pitfall. Reading RDT fields by position without first parsing RDF. If the column order changes between server versions or query profiles, positional assumptions silently mismap data — always derive the column index from the RDF definition.

Pitfall. Treating an NF response as an error. A QAK-2 value of NF means the query succeeded but matched no records. It is a valid, empty result set and should not trigger an error path.

Pitfall. Discarding DSC and stopping after the first page. When DSC-1 is populated, additional result rows exist on subsequent pages. Stopping at the first response produces an incomplete result set without any visible error.

Pitfall. Assuming RDF is repeated on every page of a paged response. The schema is defined once in the first page; continuation pages carry only MSH, MSA, QAK, QPD, RDT rows, and optionally another DSC. Re-using the RDF from the first page is the correct approach.

How Vorro handles RTB messages

Vorro receives RTB responses over MLLP or another transport, matches each response to its originating QBP^Q13 query using the tag in QAK-1 and the control id in MSA-2, and routes the result rows to the requesting system in the format it expects. Vorro parses RDF on arrival to build the column schema, interprets each RDT row positionally against that schema, and handles paged responses by following DSC continuation pointers through to the final page before delivering a complete result set downstream. Where a FHIR destination is configured, Vorro maps the tabular rows to a Bundle searchset — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message.

Related messages

• QBP — the query by parameter message that triggers an RTB^K13 response.
• RSP — the segment-pattern query response used when the querying system wants typed HL7 segments rather than tabular rows.
• QRY — the original query message type, superseded by QBP in v2.5 but still encountered in legacy interfaces.

Sources

• HL7 v2-to-FHIR IG — message maps index — confirms no message map for RTB_K13
• HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for RDF or RDT
• HL7 Messaging Standard Version 2.5.1 product brief