HL7 QPD Segment: Query Parameter Definition

The QPD (Query Parameter Definition) segment defines the request side of a Query by Parameter exchange. It names the query to run through the Message Query Name, supplies a Query Tag that the response will echo for correlation, and then carries the actual search parameters in successive user-defined fields. QPD is the heart of a QBP (query by parameter) message: it states both what query is being invoked and the specific criteria the responder should match.

Purpose

The purpose of QPD is to express a query request in a structured, query-specific way. The first field, Message Query Name, selects a named query whose definition (the set of expected parameters and the shape of the response) is agreed in advance between trading partners. The second field, Query Tag, is a requester-generated handle that the responder echoes in QID and QAK so the response can be correlated. From the third field onward, QPD carries the user parameters that constitute the actual search criteria, with their meaning and data types determined by the named query selected in QPD-1. Paired with an RCP segment that controls how the response is returned, QPD fully specifies a query.

Used in

QPD is part of the modern query group built on the Query by Parameter framework. It is used in:

QBP (query by parameter) request messages, where QPD defines the query alongside RCP. See QBP and the query framework.

A client builds a QBP message containing QPD (the request definition) and RCP (the response control). The responder answers with an RSP message in which QID and QAK lead the response, echoing the Query Tag from QPD-2 and the Message Query Name from QPD-1.

Field-by-field reference

Source: HAPI HL7v2 v2.5.1 javadocs (QPD.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
QPD-1	Message Query Name	ce	—	R	—	—	Names the query to be executed
QPD-2	Query Tag	st	—	O	—	—	Requester-generated tag echoed in the response
QPD-3	User Parameters (in successive fields)	varies	—	O	—	—	Query criteria defined by the named query

Most-used fields

QPD-1 Message Query Name: the required field that selects which named query runs. Everything else in QPD is interpreted relative to this value, so it is the primary key of the request.
QPD-2 Query Tag: the correlation handle. The requester generates it, and it returns unchanged in QID-1 and QAK-1. It is how clients pair responses to requests.
QPD-3 and beyond, User Parameters: the actual search criteria. The number, order, names, and data types of these fields are fixed by the named query in QPD-1, so they vary from one query to another.

Version differences (2.3 to 2.8.2)

QPD is the request-side foundation of the Query by Parameter framework that became standard in 2.4 and 2.5. There is no QPD segment in 2.3, where queries used the older QRD/QRF group with a fixed parameter layout. From 2.4 through 2.8.2, QPD keeps the same structure: a Message Query Name, a Query Tag, and then a variable run of user-parameter fields whose layout is governed by the named query rather than the segment itself. The Message Query Name uses the CE data type in 2.5.1; later versions trend toward CWE for coded elements, but the position and role are unchanged. The most meaningful version-to-version variation is not in QPD's skeleton but in the catalog of named queries and their parameter sets, which are defined per conformance profile and expand over time.

Common mistakes

Omitting the Message Query Name. QPD-1 is required; without it the responder cannot know which query to run or how to interpret the user parameters.
Treating QPD-3 onward as fixed. The user-parameter fields are defined by the named query, not by QPD itself; hard-coding a layout that works for one query will break another.
Reusing or omitting the Query Tag. QPD-2 should be unique per outstanding request so responses can be correlated; reusing a tag across in-flight queries confuses pairing.
Putting response-control options in QPD. Paging, sort order, and quantity limits belong in RCP, not in QPD.
Misordering user parameters. The named query fixes the order of QPD-3 onward; sending criteria out of order yields wrong or empty results.

Examples

Minimal valid segment (Message Query Name is the only required field):

QPD|Z44^Demographics Query^HL70471

Fully-populated segment, a patient demographics query keyed by name and birth date:

QPD|Z44^Demographics Query^HL70471|Q4815162342|DOE^JANE|19850214|F

Annotated breakdown:

QPD|Z44^Demographics Query^HL70471|Q4815162342|DOE^JANE|19850214|F
    |                              |           |        |        |
    |                              |           |        |        +-> QPD-6 user param: sex = F
    |                              |           |        +----------> QPD-5 user param: birth date = 19850214
    |                              |           +-------------------> QPD-4 user param: patient name = DOE^JANE
    |                              +-------------------------------> QPD-2 Query Tag = Q4815162342 (echoed in response)
    +--------------------------------------------------------------> QPD-1 Message Query Name = Z44 (required)

In-context excerpt 1, a patient demographics request inside a QBP^Q11 message, with QPD and RCP:

MSH|^~&|EHR|CLINIC_A|MPI|CENTRAL|20260610101459||QBP^Q11^QBP_Q11|MSG00042|P|2.5.1
QPD|Z44^Demographics Query^HL70471|Q4815162342|DOE^JANE|19850214|F
RCP|I|25^RD&Records&HL70126|R

In-context excerpt 2, a visit-history request showing a different named query and its own parameter set:

MSH|^~&|EHR|CLINIC_A|MPI|CENTRAL|20260610101600||QBP^Q11^QBP_Q11|MSG00044|P|2.5.1
QPD|Z45^Visit History Query^HL70471|Q9001234567|MR67890^^^CLINIC_A^MR|20250101|20260101
RCP|I|50^RD&Records&HL70126|R

FHIR mapping

QPD is not mapped at the segment level. No segment-level ConceptMap is published in the v2-to-FHIR Implementation Guide for QPD because query/response infrastructure has no direct FHIR resource equivalent. In FHIR, the role of QPD is filled by a RESTful search interaction: the named query corresponds to a resource type or named operation, and the user parameters correspond to URL search parameters or operation inputs. There is no segment-level field translation, so engines bridging v2 query traffic to FHIR map the named query and its parameters onto the appropriate search request rather than transforming QPD directly.

Engine considerations

Because QPD's parameter fields are defined by the named query rather than the segment, interface engines usually treat QPD-1 as a dispatch key: read the Message Query Name, then apply the parameter template registered for that query to interpret QPD-3 onward. Engines validate that QPD-1 is present and recognized, and that the Query Tag in QPD-2 is unique among outstanding requests so the eventual response correlates cleanly. Some engines store the QPD-2 value in a pending-query table keyed for matching against inbound QID-1 and QAK-1. Generic parsers should avoid assuming a fixed field count past QPD-2.

How Vorro parses and produces QPD

When parsing an inbound QBP, Vorro reads QPD-1 first and uses it to select the parameter template for the named query, which tells it how to interpret each subsequent user-parameter field. The Query Tag in QPD-2 is captured as the request correlation key and stored so the matching response can be reunited with it. When producing a QPD, Vorro emits the required Message Query Name, generates a unique Query Tag, and lays out the user parameters in the order the named query prescribes, leaving unset optional parameters empty to preserve position. It keeps response-control concerns out of QPD and places them in the companion RCP segment.

Sources

← Back to HL7 v2 Guide