This page explains how to search for FHIR resources using more advanced query
functionality available through the
method. This guide assumes that you are already familiar with the contents of
Searching for FHIR resources.
String search modifiers
A string search defaults to a prefix match that is case and accent insensitive through folding to the standard Unicode NFC form. Punctuation and extra whitespace is ignored.
The following modifiers are available:
:containsmatches resources with the specified value anywhere in the string, for example
:exactmatches the entire string including case and accents, for example
Comparators and precision for numbers, dates, and quantities
Values used in a numeric or date search depend on the precision of the parameter
value. For example, the number
7.00 has an implicit range of
7.005 exclusive. The date
2015-08-12 has a range of
2015-08-12T00:00:00 inclusive to
Precision affects what results are returned for equality comparisons. For
example, a value of
7.03 in a resource would match a search for
but would not match a search for
All clinically significant floating point values in FHIR are represented by types such as Decimal and Quantity that record the precision of the stored value. As an exception there are a few fields that use simple integers, for example to represent a position in a sequence, and searches on those fields are exact numerical matches.
The following prefixes apply to numeric comparisons against a singleton value.
If no prefixes are specified, the default is
eq: equals, the exact stored value is inside the range defined by the precision of the parameter value
ne: not equals, the opposite of
gt: the exact stored value is greater than the exact parameter value
lt: the exact stored value is less than the exact parameter value
ge: the exact stored value is greater than or equal to the exact parameter value
le: the exact stored value is less than or equal to the exact parameter value
Date values have an implicit range based on the level of specificity of the
value (one year, one month, one day). Other data types such as Range
contain explicit upper and lower bounds. The following prefixes apply to range
comparisons. If no prefixes are specified, the default is
eq: equals, the range of the parameter value fully contains the range of the target
ne: not equals, the opposite of
gt: greater than, the range above the parameter value overlaps with the range of the target
lt: less than, the range below the parameter value overlaps with the range of the target
ge: greater than or equal to
le: less than or equal to
sa: the range of the parameter value starts after the target range
eb: the range of the parameter value ends before the target range
Token search parameters apply to cases where a value is not an arbitrary string, but rather an entity in a naming system. String matching on a token parameter is exact.
Most token searches apply to complex data types that contain a
system that is
a URI indicating the naming system that the
code value is taken from. These
searches support the following value syntaxes:
codevalue regardless of the
[parameter]=[system]|[code]must match both the
systemvalue is empty
codewith the given
There are several modifiers that trigger alternate token search functionality:
:notnegates the matching conditions of a token search
:textdoes a string search (not exact match) on the
displayfield associated with the code, instead of the code value itself
:abovetakes a parameter only of the form
[system]|[code]and matches resources where the code in the resource subsumes the query parameter. To use this modifier the specified
systemmust exist in the FHIR store as a
:abovebut matches if the code in the resource is subsumed by the query parameter.
:intakes a single parameter using the reference parameter syntax, for example
code:in=ValueSet/1234. The reference must refer to a
ValueSetresource within the same FHIR store. The modifier matches any code that is in the referenced
:not-innegates the conditions of
Token searches also apply to boolean and URI fields and certain string
fields where only exact match is allowed. In these cases, the only parameter
Searching for missing values
The search modifier
:missing can be used on any search parameter to match
based on the presence or absence of any value in the specified field. For
Patient?gender=unknown matches resources that explicitly contain the
unknown enum value for gender, but as this field is not required there may be
other resources that do not populate the field at all. Such resources can be
Patient?gender:missing=true. The converse,
matches any resource that explicitly populates this field.
The special search parameter
_content performs a text match on string-based
fields (excluding number, date, or enum fields) if the field is the target of
any search parameter on the resource. By default it matches resources that
contain all of the words in the query, with support for additional operators:
|is the OR operator, for example
abc | def | ghi xyzwill match a resource that contains
xyzand one or more of
-is the NOT operator, for example
abc -defwill match a resource that contains
abcbut does not contain
The matching is based on complete words and does not match substrings or non-alphanumeric characters. The order of the words does not matter. Matching words can be spread across multiple fields in the resource.
_text performs the same type of match only on the Narrative
field that is intended to contain a human-readable summary of the resource
contents. The Cloud Healthcare API does not automatically generate this
summary but supports the
_text search parameter if this data was populated by
the client when creating or updating the resource.
Composite search parameters
When searching using multiple query parameters, there are cases where individual search parameters combined with AND would match unintended results. Composite search parameters are a special type of search parameter that address this issue.
For example, the
Observation resource may contain multiple values in the
component field, each of which contains a pair of
value. A search
match a resource that had one component containing a
code of 8867-4 and a
different component containing a
value less than 50. This search cannot be
used to restrict to a match of these two values within the same component.
Composite search parameters define a new parameter that combines two other
search parameters and defines a level of nesting within which they must both
match. In the query, the two values are joined by
$. For example,
Observation has a composite parameter
component-code-value-quantity that can
restrict the previous example to a single component by searching for
Observation?component-code-value-quantity=8867-4$lt50. These parameters are
defined by the FHIR specification and do not exist for all combinations of
Composite search parameters do not allow modifiers.
A chained search allows a search to traverse references within the context of a query. The basic syntax for a chained search is:
[reference parameter]:[resource type].[inner search parameter]=[inner value]
If the reference parameter only refers to one resource type, the
type] may be omitted, resulting in:
[reference parameter].[inner search parameter]=[inner value]
Observation has a reference search parameter
subject that may
point to a
Location. To find
that have a
subject which is a
Patient having a name beginning with "Joe",
you can search
If the query has multiple chained parameters, each chain is evaluated
separately. For example,
would match a
Patient that had two
general-practitioner references, one named "Joe" and the other having an
address in Canada. There is no syntax to group these clauses together to match
only Joe from Canada.
The Cloud Healthcare API supports single-level chained searches. You can't do a chained search using more than one level of chaining.
Reverse chained search
A reverse chained search matches resources based on criteria on other resources that refer to them. The syntax for a reverse chained search is:
_has:[resource type]:[reference parameter]:[search parameter]=[value]
For example, the
Appointment resource has a search parameter
referring to a
Patient resource. To find all
Patient resources that are
referenced by an
Appointment resource with a date of
Reverse chains can be recursive, for example
would match a
Practitioner P if there is an
Encounter E and a
Claim C such
that C has a created date of
2020-04-01, C refers to E through its
reference, and E refers to P through its
Including additional resources in search results
_revinclude parameters request that the search results
include additional resources ("included resources") related to the resources
directly matching the query ("primary results"). Using these parameters is more
efficient than making a series of requests to retrieve these additional
resources separately. In the
searchset bundle returned from the search,
resources added by these parameters will be flagged with
entry.search.mode = include to distinguish them from primary results which
entry.search.mode = match.
Forward inclusion with
_include adds resources and resource versions
referenced by the primary results, and reverse inclusion with
resources that reference the primary results. The reference to follow is
specified by the name of a search parameter, and only reference fields that are
available as search parameters can be used in this way.
The parameter formats to
_revinclude are the same, taking two
or three values delimited by
:. The first value is the resource type that the
reference is coming from, the second value is the search parameter name, and the
optional third value limits the resource type to a single type in cases where
the reference can point to more than one type.
MedicationRequestresources, and for each resource returned also returns the target of the
subjectreference which might be a
Patientas defined in the FHIR specification.
MedicationRequest?_include=MedicationRequest:subject:Patientis similar but only returns
MedicationRequestresources, and for each resource returned also returns any
Provenanceresources where the
Provenancerefers to the matching resource.
:iterate causes an
_include to be evaluated iteratively.
This modifier can follow an extra layer of references from included results,
or follow recursive structures such as
Observation. The depth of recursion is limited.
Observationresources and recursively follows the derived-from reference from matching
Observationresources, and then from included resources, and so on.
MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agentwill search over
Provenanceresources with a
targetthat is in this result set, and then also include resources referenced through the
agentparameter of those
A wild card,
*, indicates that all references available as search parameters
should be included. You can use the
* wild card as the first and only argument
_include, or in place of the search parameter name from the standard
_include, where the optional third value limits the resource type to a single
type as in the original behavior.
Observationresources, and for each resource also returns all referenced resources.
Observation?_include=Observation:*is equivalent to the preceding.
MedicationRequest?_include=MedicationRequest:*:Patientreturns all references to
Patientresources for each
Included resources will be deduplicated so only one copy of a resource will be returned within a page of results even if it is found through multiple references. The same included resource will be returned on each page of results where a primary result relates to it.
Limiting fields returned in search results
_elements parameter allows the client to request that only a subset of
fields is returned for each search result to reduce the size of the response by
omitting unnecessary data. The parameter accepts a comma-separated list of base
element names in the resource, for example
Patient?_elements=identifier,contact,link. Only these fields and their
children will be included in the returned resources. Resources in the response
that have been altered by this parameter will contain a
meta.tag value of
SUBSETTED to indicate that they are incomplete.
The Cloud Healthcare API has limited support for the
which provides pre-defined subsets of resource fields similar to
_summary=textreturns only the
textfield and returns all other fields