Search Paramters
Searching
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.
Search Responses
When searching, results are returned in a Bundle
, which will be empty if no matches for the search exist.
Bundle
s will automatically be split into 'pages' of results if a large enough number of resources are matched. If
the 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
setting. _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 Operations
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.
Parameter Operations
Date
, Number
, and Quantity
parameters support inequality relationships to find resources where a given parameter
satisfies the inequality. These inequalities are approximate (ap
), ends before (eb
), equal (eq
), greater
than (gt
), greater than or equal (ge
), less than (lt
), less than or equal (le
), not equal (ne
), and starts
before (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
before (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
example, GET /Encounter?patient=12345-ABCDE
will retrieve all Encounter
resources where the patient is set to id 12345-ABCDE
. References
may be constrained to
a resource type - for example, here it is known that the patient should be a Patient
, so
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.
Examples:
Search for names which begin with 'Jonas'
GET /Patient?name='Jonas'
Search for names which contain 'Jonas'
GET /Patient?name:contains='Jonas'
Search for names which are exactly 'Jonas'
GET /Patient?name:exact='Jonas'
Search for names which are not 'Jonas'
GET /Patient?name: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; code
s are members of
a code system
and often identified by a uri describing the system and an id within that system. Support for this
feature is upcoming.
Core Search Parameters
All resources have the _id
search parameter, which matches when searched with the same id as that resource. For
example: 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:
_lastUpdated
_has
_tag
_profile
_history
Currently, the _text
and _content
parameters are not supported.
Per-Resource Parameters
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, Encounter
has
a patient
searchable parameter, which will return results if subject
is a Patient reference
and that reference
matches the search; subject
may be some other reference
, but patient
will only operate on Patient references
.
It is important to remember that the Reference
primitive is not required to reference only one resource type. For
example, Encounter
's participant
parameter may be a Reference
to any of Practitioner
, PractitionerRole
,
or RelatedPerson
. However, as described above, it can never be a String
, nor may it be a complex type, such as an
actual Practitioner
; this is in keeping with the rule that parameters are each a single primitive type.
Examples
- Searching for Patient by Name:
Patient?name=salk
- String searches are typically case-insensitive, but you can use a modifier to make it exact:
Patient?name:exact=Salk
. - If you want all patients that contain the search value:
Patient?name:contains=salk
.
_include and _revinclude
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
for: GET /MedicationRequest?_include=MedicationRequest:patient
.
_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: GET /Patient?_revinclude=Appointment:patient
.
Encounters involving a Practitioner
Suppose that you want to retrieve Encounter
s with a particular Practitioner
, with identifier
12345-ABCDE
:
GET /Encounter?participant=12345-ABCDE
would be the most direct formulation. However, it is not a requirement of the
specification that 12345-ABCDE
only identify one resource - just that for each resource type, the identifier is
unique. 12345-ABCDE
could identify one resource of each kind, although this is unlikely. Since participant
can
include not only Practitioner
references, but also several other reference types, it is preferred to scope the
query: 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 participant
s to Practitioners
. Therefore, GET /Encounter?practitioner=12345-ABCDE
is a
more concise equally valid request for the same information.
Patient Addresses
In order to filter Patient
resources by the patient's address, we might expect to use the address
search parameter.
However, the 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
search GET /Patient?address-postalcode=#####
is the most appropriate query.