Search Examples
Below are some examples of FHIR API queries. These examples present various search parameters, modifiers, chained and reverse chained searches, composite searches, and more.
Examples of Search Result Parameter Queries
FHIR searches are based on defined search parameters. The parameters that are available depend on the ResourceType you are querying. You can check the FHIR specification's ResourceType page for each ResourceType to see what parameters are available for that resource.
_include
The _include parameter enables you to search for resource instances then include other resources that are referenced by the target resource instances in the results. In this example, the API request returns all MedicationRequest resource instances in the database and all patients referenced by the MedicationRequest instances.
GET [baseurl]/MedicationRequest?_include=MedicationRequest:patient
_revinclude
The _revinclude parameter enables you to search for resource instances and include other resources that reference the target resource instances in the results. In this example, you search for patients then reverse include all encounters that reference the patients.
GET [baseurl]/Patient?_revinclude=Encounter:subject
_elements
The _elements parameter narrows the results information to a subset of the elements defined for a resource type. The _elements parameter accepts a comma-separated list of base elements. The following example shows how to query for a bundle of patients where each entry in the bundle only includes a patient's identifier(s) and active status.
GET [baseurl]/Patient?_elements=identifier,active
The entries in the response will contain a meta.tag value of Subsetted to indicate that not all elements defined for the resource are included.
Examples of Search Modifiers
Modifiers 
enable you to qualify search parameters with additional conditions.
:not
The :not modifier enables you to search for resources with an element that does not have a given value. The following example illustrates how to search for patients who are not female. The returned bundle would contain all Patient resources whose gender element value is not "female", including any patients with no gender value specified. This is different from searching for Patient resources with the "male" gender value since in that request that the returned bundle would not include patients with no specified gender.
GET [baseurl]/Patient?gender:not=female
:missing
The :missing modifier returns all resources that either do or do not have a value for the specified element.
- When
:missing=true the query returns all resources that do not have a value for the specified element. For simple data type elements, :missing=true will search for all resources where an element is present but has an empty value.
- When
:missing=false the query returns all specified resources that contain the specified element with a value.
This example shows how to find all Patient resources that are missing birthdate information.
GET [baseurl]/Patient?birthdate:missing=true
:exact
The :exact modifier returns all elements with string data types; it returns positive if the parameter value precisely matches the case and full character sequence of the element value. The following example returns Patient resources that have the given or family name of "Jon".
GET [baseurl]/Patient?name:exact=Jon
If the data contains Patient resources with names such as "Jonathan" or "JON", the search would ignore those resources since their names do not match the specified value exactly.
:contains
The :contains modifier returns all elements with string data types that match the specified value anywhere within the field. The following example returns all Patient resources with address element fields that contain the string "Meadow" (case insensitive). This means you could have addresses with values such as "Meadows Ave", "Pinemeadow St", or "Meadowlark Rd" that return positive matches.
GET [baseurl]/Patient?address:contains=Meadow
Examples of Chained Searches
A chained search enables you to perform targeted queries for resources. These targeted queries contain a reference to another resource within the query.To perform search operations that cover elements contained within a referenced resource, "chain" a series of parameters together with the . character.
The following request returns all DiagnosticReport resources using a subject reference to a patient, who is specified by name. This request would return all DiagnosticReport resources with a patient subject named "Sara". The . points the chained search to the name element within the referenced Patient resource.
GET [baseurl]/DiagnosticReport?subject:Patient.name=Sara
A FHIR search is also commonly used to find all encounters for a specific patient. You can do this using a regular (non-chained) search for Encounter resources that reference a Patient with a given ID:
GET [baseurl]/Encounter?subject=Patient/78a89cbe-7268-44fd-a321-d63e9916366f
However, if you use a chained search, you can find all Encounter resources that reference patients whose details match a search parameter. This example demonstrates how to search for encounters referencing patients narrowed by birthdate. The query returns all Encounter instances that reference patients with the specified birthdate value.
GET [baseurl]/Encounter?subject:Patient.birthdate=1981-02-10
You can also initiate multiple chained searches by using the & operator. This operator enables you to search against multiple references in one request. When you use the & operator, the chained search scans for each element value specified in the query.
GET [baseurl]/Patient?general-practitioner:Practitioner.name=Sarah&general-practitioner:Practitioner.address-state=WA
This query returns all Patient resources that have a reference to "Sara" as a general practitioner plus a reference to a general practitioner that has an address in the state of Washington. In other words, if a patient had a general practitioner named Sara from New York state and another general practitioner named Bill from Washington state, this query would return both Sara and Bill as each satisfies at least one of the search criteria.
Note: If you need to search using a logical AND condition that strictly checks for paired element values, see the Composite Searches section below.
Examples of Reverse Chained Searches
Using a reverse chained search in FHIR enables you to search for target resource instances referenced by other resources: you can search for resources based on the properties of resources that refer to them. To do this, use the _has parameter.
The following example finds all Patient resources that are referenced by an Observation with a specified code (842).
GET [baseurl]/Patient?_has:Observation:patient:code=842
This request returns all Patient resources that are referenced by Observation resources with the code 842.
Reverse chained searches can also have a recursive structure. So, if you want to search for all patients referenced by an Observation where the observation is referenced by an AuditEvent from a specific practitioner named janedoe use:
GET [baseurl]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe
Examples of Composite Searches
A composite search enables you to search for resources that contain elements grouped together as logically connected pairs. It joins single parameter values together using the $ operator to form a connected pair of parameters. In a composite search, a positive match occurs when the intersection of element values satisfies all conditions set in the paired search parameters (as opposed to chained searches in which positive matches occur with the intersection of any one value with the listed parameters).
The following example returns all DiagnosticReport resources that contain a potassium value less than 9.2:
GET [baseurl]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2
In this case, the paired elements would be the code element (from an Observation resource referenced as the result) and the value element connected with the code. Following the code with the $ operator sets the value condition as lt (less than) 9.2 (for the potassium mmol/L value).
You can also use composite searches to filter multiple component code value quantities with a logical OR systolic blood pressure greater than 140:
GET [baseurl]/Observation?component-code-value-quantity=http://loinc.org|8462-4$gt90,http://loinc.org|8480-6$gt140
