The QRI (Query Response Instance) segment qualifies a single returned record in a query response. When a responder cannot return exact matches and instead returns a ranked list of candidates — most commonly in probabilistic patient lookups — QRI travels with each candidate to explain how confident the responder is, why the record matched, and which matching algorithm produced the result. QRI is a small but important part of the response-side query infrastructure, complementing the response-control and acknowledgement segments that frame a query response.
Purpose
QRI answers the question "why is this record in the result, and how much should I trust it?" Its three fields are all optional qualifiers attached to one response instance: the Candidate Confidence (QRI-1) is a numeric score expressing how strong the match is, the Match Reason Code (QRI-2) is a repeating coded value listing which attributes caused the match (for example name, date of birth, or identifier), and the Algorithm Descriptor (QRI-3) names the matching algorithm or rule set that the responder applied.
QRI does not carry the matched data itself; it annotates the data segments that accompany it within a single response instance. It is therefore always read in the context of the surrounding response group rather than on its own.
Used in
QRI carries a single response instance in query responses. It appears in tabular and candidate-list query responses, where each returned record is accompanied by a QRI describing the quality and basis of that match. It is part of the modern, conformance-based query infrastructure and is most often seen alongside the QAK (Query Acknowledgement) and QPD (Query Parameter Definition) segments in an RSP response to a QBP query. It is conceptually related to the legacy query mechanism described on the QRD and QRF pages, which used the original QRY message, but QRI itself belongs to the newer response model.
Field-by-field reference
Source: HAPI HL7v2 v2.5.1 javadocs (QRI) 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 |
|---|---|---|---|---|---|---|---|
| QRI-1 | Candidate Confidence | nm | — | O | — | — | Numeric confidence score for the match |
| QRI-2 | Match Reason Code | is | — | O | Y | — | Coded reasons the record matched |
| QRI-3 | Algorithm Descriptor | ce | — | O | — | — | Matching algorithm or rule set applied |
Note: all three QRI fields are optional in the HL7 v2.5.1 standard. QRI is itself an optional segment that appears only when the responder is returning ranked or probabilistic candidates rather than exact matches.
Most-used fields
- QRI-1 Candidate Confidence is the field that gives QRI its reason to exist. Receiving systems use it to rank, threshold, and auto-accept or hold candidate records.
- QRI-2 Match Reason Code is heavily used in master-person-index lookups to show which demographic attributes drove the match, which is important for both review and audit.
- QRI-3 Algorithm Descriptor matters when several matching algorithms are in play, so a downstream system can interpret QRI-1 in the context of the algorithm that produced it.
Version differences (2.3 to 2.8.2)
QRI does not exist in the original (pre-2.4) query mechanism. The legacy mechanism used the QRD and QRF segments inside a QRY message and answered with DSR/UDM responses, none of which carried per-record match metadata. QRI was added as part of the modern, conformance-based query infrastructure (the QPD/RCP/QBP model) to support tabular and candidate-list responses, where each returned row needs a confidence score and a match rationale. From its introduction through v2.5.1 and onward to v2.8.2 the segment's three-field structure is stable. New development uses QRI together with QBP/RSP rather than the deprecated original-style query segments.
Common mistakes
- Interpreting QRI-1 Candidate Confidence without knowing the algorithm in QRI-3, so scores from different algorithms are compared as if they were on the same scale.
- Treating QRI-2 Match Reason Code as single-valued when it repeats; a parser must read all reasons.
- Auto-accepting candidates above a confidence cut-off without surfacing the match reasons for human review where policy requires it.
- Expecting QRI in a legacy QRY/DSR exchange. It belongs to the modern QBP/RSP model, not to the original-style mechanism of QRD and QRF.
- Assuming a fixed numeric scale for QRI-1 without confirming with the responder whether it is a 0..1 fraction or a 0..100 score.
Examples
Minimal valid segment (a single confidence score):
QRI|0.92
Fully-populated segment:
QRI|0.92|NAME~DOB~SSN|EXACT^Exact deterministic match^HL7VORRO
Annotated breakdown:
QRI|0.92|NAME~DOB~SSN|EXACT^Exact deterministic match^HL7VORRO
| | |
| | +-> QRI-3 Algorithm Descriptor (coded algorithm/rule set)
| +--------------> QRI-2 Match Reason Code (NAME, DOB, SSN — repeating)
+-------------------> QRI-1 Candidate Confidence (0.92)
In-context excerpt 1 — QRI qualifying candidates in a tabular RSP query response to a patient demographics query:
MSH|^~&|RESPAPP|RESPFAC|REQAPP|REQFAC|20260610154500||RSP^K22^RSP_K21|MSG00041|P|2.5.1
MSA|AA|MSG00040
QAK|Q0050|OK|IHE_PDQ^Find Candidates^HL7VORRO|2
QPD|IHE_PDQ^Find Candidates^HL7VORRO|Q0050|@PID.5.1.1^SMITH
PID|1||PX0301^^^HOSP^MR||Smith^Jamie^A||19850214|F
QRI|0.97|NAME~DOB|PROB^Probabilistic match^HL7VORRO
PID|2||PX0302^^^HOSP^MR||Smith^Jamey^^||19850214|F
QRI|0.81|NAME~DOB|PROB^Probabilistic match^HL7VORRO
In-context excerpt 2 — a lower-confidence candidate returned with multiple match reasons:
MSH|^~&|RESPAPP|RESPFAC|REQAPP|REQFAC|20260610155500||RSP^K22^RSP_K21|MSG00042|P|2.5.1
MSA|AA|MSG00041
QAK|Q0051|OK|IHE_PDQ^Find Candidates^HL7VORRO|1
QPD|IHE_PDQ^Find Candidates^HL7VORRO|Q0051|@PID.5.1.1^ROE
PID|1||PX0410^^^HOSP^MR||Roe^Jordan^^||19901130|M
QRI|0.64|NAME~GENDER~ADDRESS|FUZZY^Fuzzy name match^HL7VORRO
FHIR mapping
There is no segment-level ConceptMap published in the v2-to-FHIR Implementation Guide for QRI. The query/response infrastructure has no direct FHIR resource equivalent: FHIR returns query matches as a searchset Bundle, and per-record match metadata is expressed through the Bundle.entry.search element. Conceptually, QRI-1 Candidate Confidence parallels Bundle.entry.search.score, and the matching disposition parallels Bundle.entry.search.mode (match, include, outcome). These are conceptual parallels for understanding only, not a normative mapping.
Engine considerations
- Pairing with data: associate each QRI with the response instance (for example the preceding PID and its group) it qualifies. Losing that association strips the confidence and reason from the record.
- Scale agreement: confirm with the responder whether QRI-1 is a 0..1 fraction or a 0..100 score, and normalize on ingest so downstream thresholds behave consistently.
- Algorithm awareness: keep QRI-3 alongside QRI-1, because a confidence score is only meaningful relative to the algorithm that produced it.
- Repetition: QRI-2 Match Reason Code repeats. Parsers must expand it into a list rather than reading only the first value.
- Thresholding: implement auto-accept and human-review cut-offs against QRI-1, and surface QRI-2 reasons wherever review policy requires an explanation.
- Optionality: do not assume QRI is present. Exact-match responses may omit it entirely; treat its absence as "no match metadata supplied," not as an error.
How Vorro parses and produces QRI
When Vorro ingests an RSP query response, it parses each QRI and binds it to the response instance it annotates, normalizing QRI-1 to a 0..1 confidence fraction (internally the primary confidence form) regardless of the scale the responder used. The repeating QRI-2 match reasons are expanded into a list, and QRI-3 is retained so the confidence can be interpreted relative to its algorithm.
When producing QRI, Vorro emits a confidence score in QRI-1, the contributing match reasons in QRI-2, and an algorithm descriptor in QRI-3 whenever its matching engine returns ranked candidates. QRI is generated only for candidate-list responses; exact deterministic matches are returned without it. Configurable thresholds let Vorro drop candidates below a confidence floor before they reach the requester, while preserving the match reasons for audit. QRI is paired with the QAK and QPD segments of the surrounding RSP response so the requester can correlate it with the original QBP query.
Related pages
- QAK segment — query acknowledgement that frames a query response
- QID segment — query identification in the modern query model
- QBP message — the conformance-based query message answered by responses carrying QRI
