Unlike many end-user-facing data stores, full-text search is not used to locate resources via the API. Searches are performed over parameters, sometimes combining multiple parameter queries to complete the search. Each resource type has a defined set of parameters, which are not extensible by API consumers. These parameters typically map to the field values of the resource, but some non-standard searchable parameters exist, and not all fields have a corresponding parameter.
When searching, results are returned in a
Bundle, which will be empty if no matches for the search exist.
Bundles will automatically be split into 'pages' of results if a large enough number of resources are matched. If
Bundle is split, it will contain links leading to other relevant pages; simply follow the tagged link in order to
load additional results.
Bundles can be ordered by utilizing the
_sort accepts a list of search parameters, resolving ties on
the first parameter using the second, and so on. It is not guaranteed that sorting is perfectly deterministic or
time-stable for all parameters.
Parameter searches can be joined together, requiring both searches be satisfied, using
&. Multiple values of a
parameter may be allowed in a search either by supplying a comma-separated list, or by using inequality. Fuzzy matching
is currently unsupported.
Quantity parameters support inequality relationships to find resources where a given parameter
satisfies the inequality. These inequalities are approximate (
ap), ends before (
eb), equal (
gt), greater than or equal (
ge), less than (
lt), less than or equal (
le), not equal (
ne), and starts
sb). Such an inequality is indicated by prefixing the inequality's two-character shorthand before the search
parameter. For example:
GET /Encounter?_length=ge3 will retrieve
Encounter resources with a duration of greater than
or equal to three days. Some of these parameters bear additional explanation. Starts before (
sb) and ends
eb) can operate on search parameters which represent a range, such as a pair of dates; they each constrain one
of the two values. Approximate treats values similar enough to the target value as equal; however, the implementation
specifies the method of approximation, so for most uses a more well-defined parameter is preferred.
Token parameters can be searched for exactly a particular string. Fuzzy matching on tokens is not supported, and
typically is not the intended usage. A token parameter usually has a small number of allowed tokens indicated as allowed
values in the specification.
References indicate that another resource is related to the resource. For
will retrieve all
Encounter resources where the patient is set to id
References may be constrained to
a resource type - for example, here it is known that the patient should be a
GET /Encounter?patient=Patient/12345-ABCDE is the correctly scoped query.
String parameters are similar to tokens, but are free text. They can be searched for both exact matches, and for
substring matches. String parameter searches ignore both casing and accents.
Search for names which begin with 'Jonas'
Search for names which contain 'Jonas'
Search for names which are exactly 'Jonas'
Search for names which are not 'Jonas'
Composite parameters are a pair of items - a
code describing the parameter's usage and a value. For example, a
parameter with a
Number value might have a code describing the unit of that value;
codes are members of
code system and often identified by a uri describing the system and an id within that system. Support for this
feature is upcoming.
All resources have the
_id search parameter, which matches when searched with the same id as that resource. For
GET /Encounter?_id=12345-ABCDE will return a bundle with one
Encounter with the id
12354-ABCDE, or an
empty bundle if that resource does not exist.
Some other useful parameters that can be used during searching against all resource types include:
_content parameters are not supported.
Each resource has additional parameters for searching which are related to the typical uses and fields of that resource.
These parameters are distinct from resource fields even when those fields have similar names. Resource fields may be a
complex type, but resource parameters may not - they will only ever be one of the primitive parameter types described
above. In addition, parameters may be derived from or constrained by fields of a resource. For example,
patient searchable parameter, which will return results if
subject is a
Patient reference and that reference
matches the search;
subject may be some other
patient will only operate on
It is important to remember that the
Reference primitive is not required to reference only one resource type. For
participant parameter may be a
Reference to any of
RelatedPerson. However, as described above, it can never be a
String, nor may it be a complex type, such as an
Practitioner; this is in keeping with the rule that parameters are each a single primitive type.
- Searching for Patient by Name:
- String searches are typically case-insensitive, but you can use a modifier to make it exact:
- If you want all patients that contain the search value:
When searching for a particular resource, it's not uncommon to also want related resources. For example, if you're querying for an Appointment, you may also want the search results to include the Practitioner and the Patient on the appointment.
To do this, you can use _include and _revinclude.
_include is used when the resource you want to add to the results is on the resource type you're searching for directly.
For example, to retrieve all prescriptions and the patients they're prescribed
_revinclude can be used when the foreign reference is on the resources you're adding adding to the results. For example,
to retrieve all patients and their related appointments:
Suppose that you want to retrieve
Encounters with a particular
GET /Encounter?participant=12345-ABCDE would be the most direct formulation. However, it is not a requirement of the
12345-ABCDE only identify one resource - just that for each resource type, the identifier is
12345-ABCDE could identify one resource of each kind, although this is unlikely. Since
include not only
Practitioner references, but also several other reference types, it is preferred to scope the
GET /Encounter?participant=Practitioner/12345-ABCDE. While this is a perfectly valid request, by inspecting the
list of valid search parameters you can discover that the
practitioner search parameter is a derived search parameter
which already restricts
GET /Encounter?practitioner=12345-ABCDE is a
more concise equally valid request for the same information.
In order to filter
Patient resources by the patient's address, we might expect to use the
address search parameter.
address parameter is implementation defined, so it is preferred to use the specific parameters needed to
filter as desired. Assuming that you want to find all patients in a postal code, the
GET /Patient?address-postalcode=##### is the most appropriate query.