_include and _revinclude are the FHIR search parameters that shift the latency conversation from "one query" to "one query and a fan of follow-ups." The syntax is clean; the underlying execution is a set of joined lookups the FHIR server performs before it assembles the Bundle. When the fan is small the pattern is efficient; when the fan is large the tail latency shows up in the response.
Naming the fan is the discipline. For related walkthroughs, related FHIR walkthroughs collects the surrounding material.
What the Parameter Does
_include=Observation:patient on an Observation search adds the referenced Patient resource to the response Bundle. The FHIR server executes the primary search, collects the Patient references, and then fetches each Patient resource. The fetches are usually batched but they are additional work.
The pattern is elegant when the primary result set is small. It scales poorly when the result set is large. A pass through the site's search-query p99 lookup surfaces the tail figure per include pattern.
The Fan-Out Multiplier
Every _include reference adds a fetch per matched primary result. A search returning one hundred Observations with _include=Observation:patient triggers up to one hundred Patient reads (deduplicated) after the primary search.
The multiplier is bounded by the referenced resource type. If most Observations point at the same handful of Patients, the fan-out compresses well. If each Observation points at a different Patient, the fan-out is full.
The _revinclude Version
_revinclude runs in the opposite direction. A Patient search with _revinclude=Observation:patient fetches Observations referring to each matched Patient. The fan-out is potentially larger because Patients can have thousands of Observations. For the reverse-side comparison with chained parameters, chained search parameters and their latency tax covers the alternative.
Iterative Includes Compound
_include:iterate walks references recursively. _include:iterate=Encounter:subject on a MedicationRequest search first pulls Encounters, then pulls the Patient references from the Encounters, and so on until the tree is exhausted.
Iterative includes look convenient and produce very deep trees on real data. The tail latency reflects the tree depth. For the cache-warmth interaction with these deeper trees, why the same FHIR search runs fast on Tuesday and slow on Friday covers the variance.
The Index Coverage Trap
Every _include reference requires an index on the referenced resource's reverse index. When the index does not cover the reference, the fan-out becomes a filtered scan. For the covering-index framing specifically, when a covering index is a lie for FHIR JSON queries covers the trap.
Pagination Interaction
Pagination interacts with includes in a subtle way. A page of one hundred primary results plus their includes can produce a Bundle with several hundred entries. Client-side pagination often surprises the client with larger-than-expected Bundle sizes.
Deployments that expose pagination should document expected Bundle sizes for common include patterns. Clients that assume fixed page sizes get caught out otherwise.
Cap the Includes Where You Can
The mitigation that consistently works is to cap the include depth and the number of included references. Servers that expose these limits explicitly give clients room to plan; servers that expose neither leave the client guessing.
Every _include in a hot-path query should be examined for its fan-out. The examination is cheap; the surprise it prevents is expensive.
Sources
- HL7 FHIR core specification of _include and _revinclude - HL7 FHIR core specification of _include and _revinclude semantics
