This page is part of the FHIR Specification (v5.0.0-draft-final: Final QA Preview for R5 - see ballot notes). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions

3.2.7 FHIR-X-Query

FHIR Infrastructure Work Group

Maturity Level: Normative

Standards Status: Trial use

3.2.7.1 x-fhir-query documentation

The Expression type indicates that one of the allowed languages is application/x-fhir-query. This is defined as a FHIR search string. Normally this will not include the base URL and is intended to be invoked against the server that is in scope (usually based on the base URL of the resource containing the Expression). However, in some cases, a full URL might be specified, i.e. if the author of the resource wants resources to always be retrieved from a specific source.

In addition to the base query syntax, this specification allows for the injection of FHIRPath into the query expressions. This allows the queries to take advantage of context when they are invoked. Systems SHALL evaluate and substitute the results of such queries before executing them. The FHIRPaths are denoted by surrounding them with double curly-braces (i.e. {{ fhirpath goes here }}) in the same way expressions are denoted in the Liquid templating language.

For example:

Observation?code=http://loinc.org|65972-2&date=gt{{today()-7 days}}&subject={{%patient.id}}

would return all Observations with the specified LOINC code made in the last week for the specified patient (the %patient variable be in scope from the application's knowledge of the patient context).

NOTE: Some of the FHIRPath content may need to be escaped (percent-encoded) in order to constitute a valid URL.

Aside from specifying a FHIR search string, the query can also be used to invoke operations. For example:

Observation/$stats?subject=Patient/123&code=2339-0&system=http://loinc.org&duration=24&statistic=average

would return an Observation resource with the average for Glucose [Mass/​volume] in Blood (2339-0) in the last 24 hours for the specified patient.

This specification provides the following rules for the application/x-fhir-query language:

• If the expression resolves to a complex element of type Coding, Identifier, or Reference, the element content will be substituted using the standard token format.
• If the expression resolves to a complex element of type CodeableConcept, the processing will behave as though the expression had an additional node specifying ".coding" (i.e. the substitution will execute on the collection of codings resolved to within the CodeableConcept).
• If the expression resolves to an element of type Quantity, it will be converted to a search type of 'quantity'.
• If the expression resolves to a collection of more than one value, the substitution will be a list of comma-separated values (i.e. behaving as 'or').