HL7 MFQ Messages: Master Files Query

HL7 MFQ messages let a system ask a master file server for one or more master file records by identifier — the practitioner directory query that retrieves a provider by staff ID, the location lookup that returns a bed or department record, or the charge query that fetches a billing code definition. Where an MFN message pushes master file changes from the owning system outward to subscribers, an MFQ message pulls specific records on demand, and the server answers with an MFR master files response. This page explains what an MFQ message represents, the trigger events that distinguish one master file from another, the QRD and QRF segments that carry the query, and how an MFQ query relates to FHIR. Sample content is constructed for illustration with fictional identifiers.

What an MFQ message represents

An MFQ message — MFQ stands for Master Files Query — is a request sent from a querying application to a master file server, asking it to return one or more specific master file records. The query identifies which master file to search, who is asking, how many records are wanted, and the identifier of the record or records to retrieve. The master file server processes the request and replies with an MFR Master Files Response that carries the matching records.

Two segments give the query its content. The QRD Original Query Definition segment is required and carries the essential query parameters: a query ID and timestamp, the name of the querying application, a requested quantity, the subject filter that declares the type of data being requested, and — most importantly — the what subject filter in QRD-8, which holds the identifier of the specific master file record or records the querying application wants. The QRF Query Filter segment is optional and allows the querying application to narrow the result further, specifying a start or end date-time range and what user data to include in the response.

The sender is the application that needs a master file record — an EHR resolving an unfamiliar staff ID, a scheduling system looking up a location, or a billing system fetching a charge code definition — and the receiver is the master file server that owns the reference data. Because an MFQ retrieves records on demand rather than receiving pushed updates, it fits workflows where the querying system does not maintain a local copy of the master file and cannot wait for the next MFN broadcast.

When an MFQ message is sent

An MFQ message is sent when an application needs one or more master file records and cannot obtain them from a local cache or an MFN subscription. A query can request a single record — one staff ID, one location code — or multiple records in the same message, and the requested quantity in QRD-6 tells the server how many matching entries to return. The server replies with an MFR that carries the records matching the identifiers in QRD-8, using the same trigger event as the query so the querying application knows which master-file-specific segments to expect in the response.

Trigger events

Like MFN, MFQ defines a family of trigger events, each tied to the master file being queried. The trigger event in MSH-9 declares which master file the querying application is targeting, and the server uses it to determine which master-file-specific segments to include in the MFR response. HL7 v2.5.1 Chapter 8 defines:

• MFQ^M01 — Query master file not otherwise specified (retained for backward compatibility only).
• MFQ^M02 — Query staff/practitioner master file.
• MFQ^M03 — Query service/test/observation master file (retained for backward compatibility only).
• MFQ^M04 — Query charge description master file.
• MFQ^M05 — Query location master file.
• MFQ^M06 — Query clinical study with phases and scheduled master file.
• MFQ^M07 — Query clinical study without phases but with scheduled master file.
• MFQ^M08 — Query test/observation (numeric) master file.
• MFQ^M09 — Query test/observation (categorical) master file.
• MFQ^M10 — Query test/observation batteries master file.
• MFQ^M11 — Query test/calculated observations master file.
• MFQ^M12 — Query test/observation (other attributes) master file.
• MFQ^M13 — Query master file — general.
• MFQ^M14 — Query master file — site defined.
• MFQ^M15 — Query inventory item master file.

The M01 and M03 events are retained for backward compatibility. The trigger event the querying application places in MSH-9 must match the trigger event the server echoes back in the MFR response.

Integration topology

The diagram shows the querying application sending an MFQ to the master file server, which answers with an MFR carrying the requested records.

{{diagram: querying application → MFQ query → master file server → MFR response (matching records) → querying application}}

Typical senders: EHR, laboratory information system, scheduling system, billing system, or any application that needs a master file record on demand and does not maintain a full local copy of the reference data.

Typical receivers: master file server — typically a registration or patient-administration system, credentialing or provider-directory system, chargemaster, or laboratory dictionary management platform.

Direction: request-response — the MFQ travels from the querying application to the server, and the MFR returns along the same path.

Segments in an MFQ message

The MFQ message is compact: it carries a message header, the required query definition, and an optional query filter. 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 simplicity of this structure is deliberate: the MFQ message delegates all record selection to the server, which applies QRD-8 identifiers and any QRF filters to its master file and builds the MFR response. The canonical segment pages carry the full field-by-field detail.

Sample MFQ message

Note. Constructed for illustration. Query identifiers, staff IDs, dates, and facility names are fictional.

MSH|^~&|EHRSYS|MERCYGEN|HRSYS|MERCYGEN|20260604090000||MFQ^M02^MFQ_M01|QRY00041|P|2.5.1
QRD|20260604090000|R|I|QID20260604001|||1^RD|STF^Staff^HL70048|PROV998^MERCYGEN^MR|

What this sample shows

The MFQ^M02 in MSH-9 marks a query against the staff/practitioner master file. The QRD timestamps the query at 20260604090000 and assigns it the query ID QID20260604001 in QRD-4, which the server will echo in the MFR to tie the response to this request. QRD-6 requests up to one record (1^RD). QRD-7 declares the who subject filter as STF (staff), identifying the type of data being asked for. QRD-8 carries the what subject filter — the identifier PROV998 in the MERCYGEN assigning authority — telling the server exactly which staff record to return. No QRF is present, so no additional date or user-data filtering applies. The server will respond with an MFR^M02 carrying the matching STF and any associated PRA, ORG, and other practitioner segments for PROV998.

Working with MFQ messages

QRD-8 is the record selector — populate it precisely

QRD-8, the what subject filter, is the field that tells the server which records to retrieve. It repeats, so a single MFQ can request several records by their identifiers in one round trip. Include the assigning authority alongside the identifier — as a CWE triplet — so the server can resolve the ID unambiguously when it operates multiple identifier domains. An incomplete or ambiguous QRD-8 returns more records than expected or none at all.

Match the trigger event to the master file

The trigger event in MSH-9 must identify the master file the querying application is targeting. A query sent with MFQ^M02 asks the server to look in the staff/practitioner file; one sent with MFQ^M05 asks for location records. The server echoes the same trigger event in the MFR, so the querying application knows which master-file-specific segments to parse in the response. Do not default to M01 (not otherwise specified) unless the target file truly has no dedicated event — most server implementations route on the trigger event to select the query handler.

Idempotency and deduplication

Use MSH-10, the message control id, as the deduplication key for the query itself, and use the query ID in QRD-4 to correlate the MFR response to this request. Queries are sometimes retried after a timeout; treating a repeated control id as a duplicate prevents duplicate query processing or a second round-trip for a result already in flight.

Use QRF to constrain large result sets

When querying a master file that can return many records matching a broad QRD-8 filter, include a QRF with a date-time window in QRF-2 and QRF-3 to limit results to records active within a period of interest. This keeps the MFR response manageable and reduces load on the server.

Vendor variance. The MFQ/MFR query pattern is less widely implemented than the MFN push pattern. Many master file servers expose only MFN broadcasts and do not support on-demand MFQ queries at all. Confirm with a partner whether their master file server accepts MFQ messages and, if so, which trigger events and QRD-8 identifier formats they support, before building a query-based integration.

FHIR equivalent

There is no FHIR message that corresponds to MFQ. Conceptually, an MFQ query against a given master file is equivalent to a FHIR RESTful search on the corresponding resource — a staff/practitioner query (M02) maps toward a GET /Practitioner?identifier=... search, a location query (M05) toward GET /Location?identifier=..., and an inventory item query (M15) conceptually toward a search on a supply or device resource.

There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for any MFQ trigger event and no ConceptMap for the QRD or QRF segments. The IG's published message maps cover a subset of clinical and administrative message types but do not include the master files query family. Any FHIR equivalent of an MFQ exchange is therefore a RESTful search constructed manually, choosing the target resource from the trigger event and translating the QRD-8 identifier into a FHIR search parameter.

Common pitfalls

Pitfall. Omitting the assigning authority from QRD-8. A bare identifier without an assigning authority is ambiguous when the server manages multiple identifier domains — for example when the same numeric staff ID exists in two facility namespaces — and may return no record or the wrong one.

Pitfall. Using MFQ^M01 (not otherwise specified) when a dedicated trigger event exists. Most server implementations route on the trigger event to select the query handler and the response segments; an M01 query against a server that expects M02 for staff queries will likely return an error or an empty response.

Pitfall. Assuming all master file servers support MFQ. The push-based MFN pattern is far more common; many servers that broadcast MFN notifications do not implement the MFQ query interface at all. Validate partner support before building a query-based integration.

How Vorro handles MFQ messages

Vorro acts as both a querying application and a query router in master files workflows. As a router, Vorro accepts MFQ messages over MLLP or another transport, deduplicates on MSH-10, routes each query by the trigger event in MSH-9 to the appropriate master file server, and returns the MFR response to the originating application. Vorro reads the record identifiers from QRD-8 and applies any QRF date or data filters before forwarding the query, and correlates the response to the originating request using the query ID in QRD-4. Where a querying application expects a FHIR response rather than an MFR, Vorro maps the returned master file records to the conceptually equivalent FHIR resource — Practitioner, Location, or the appropriate alternative — constructed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message.

Related messages

• MFR — the Master Files Response that the server returns in reply to an MFQ query, carrying the requested master file records.
• MFN — the Master Files Notification, the push-based alternative that broadcasts master file changes without a preceding query.
• MFK — the Master Files Acknowledgement returned by a receiver after processing an MFN notification.

Sources

• HL7 v2-to-FHIR IG — message maps index — confirms no message map for any MFQ trigger event
• HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for QRD or QRF
• HL7 Messaging Standard Version 2.5.1 product brief