Search with related resources

A client can add related resources to a search result using (rev)include FHIR parameters and with Aidbox parameter. In ORM frameworks, such feature is sometimes called an "associations eager loading". This technique can save extra roundtrips from the client to the server and potential N+1 problem.


This example demonstrates how _include, _revinclude, and _with search parameters work_._ You may want to get encounters with patients (each encounter refers to patient):

Create Patient

PUT /Patient

resourceType: Patient
id: pat-234
  - family: Smith

Create Encounter

PUT /Encounter

resourceType: Encounter
id: enc-234
  resourceType: Patient
  id: pat-234
class: {code: 'IMP', 
  system: '', 
  display: 'inpatient encounter'}
status: finished

Search with _include

GET /Encounter?_include=Encounter:subject:Patient

Search with _with

GET /Encounter?_with=subject{Patient}

Or you can request patients and return all Encounter resources that refer to them (by a reverse reference):

GET /Patient?_revinclude=Encounter:subject:Patient

Aidbox can do the same in a compact way:

GET /Patient?_with=Encounter.subject

An field has a value match if the resource is in the search set because it matched the search criteria and has a value include if another resource refers to it.

Last updated