Search Parameters

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. Bundles 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; codes 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

Currently, the _text and _content parameters are not supported.

Per-Resource Parameters

Each resource has additional parameters for search 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 Encounters 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 participants 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.