14.4.1Chained Searching And Sorting

FHIR chained searches allow for a search against a reference search parameter to 'chain' into the reference targets and search these targets for a given search criteria.

For example, consider the search: http://example.org/Encounter?patient.name=Simpson

This search returns any Encounter resources where the Encounter.patient reference points to a Patient resource satisfying the search name=Simpson.

In order to satisfy this search, a two-level SQL JOIN is required in order to satisfy both the reference and the string portions of the search. This search leverages two indexes created by the indexer:

• A reference index satisfying the subject search parameter, associated with the Encounter resource.
• A string index satisfying the name search parameter, associated with the Patient and Group resources.

Note that on this page we are talking about chains using normal resource references, as opposed to chains into contained resources. Chaining into contained resources is a powerful, but much less commonly used feature in the FHIR specification.

14.4.2Uplifted Refchains and Chaining Performance

If you are having performance issues when performing chained searches like the one above, a feature called Uplifted Refchains can be used to create a single index against the Encounter resource. Uplifted refchains promote chained search parameters to create a single index which includes both parts of the chain. In the example above this means:

• A string index satisfying the subject.name search parameter, associated with the Encounter resource.

This can be very good for search performance, especially in cases where the second part of the chain (.name) matches a very large number of resources.

14.4.2.1Drawbacks

Using Uplifted Refchains has several drawbacks however, and it is important to consider them before enabling this feature:

• Performance: while search and sort will be faster, write speed will be slower for the resource type containing the uplifted refchain. The target needs to be resolved, parsed, and the additional uplifted refchain index data must be written.
• Correctness: Changes to the target data are not automatically reflected in the uplifted index copy, and chained search/sort may use stale data. For example, using the Encounter?subject.name=Simpson example above, the value of Simpson will be written to the index using the Patient's name at the time that the Encounter resource is written. If the Patient resource's name is subsequently changed to Flanders in an update, the new name will not be reflected in the chained search unless the Encounter resource is reindexed.

14.4.2.2Defining Uplifted Refchains

In order to use Uplifed Refchains, you must first enable Index Uplifted Refchains in your FHIR Storage (RDBMS) module configuration.

Then, create one or more SearchParameter resources with the appropriate extensions to enable Uplifted Refchains. See FHIR Search: Uplifted Refchains for details on how these look.

14.4.3Chained Sorting

The FHIR specification allows _sort expressions to use a comma-separated list of search parameter names in order to influence the sorting on search results.

Smile CDR extends this by allowing single-chained expressions as well. So for example, you can request a list of Encounter resources and sort them by the family name of the subject/patient of the Encounter by using the search shown in the example below. In this search, we are looking for all Encounter resources (typically additional search parameters would be used to limit the included Encounter resources), and sorting them by the value of the family search parameter on the Patient resource, where the Patient is referenced from the Encounter via the patient search parameter. http://example.org/Encounter?_sort=patient.family

Like chained search expressions, the first step in the chain must be a reference SearchParameter (SearchParameter.type = 'reference'). Unlike chained search expressions, only certain search parameter types can be used in the second part of the chain:

• String
• Date
• Token

If the reference search parameter defines multiple target types, it must be qualified with the specific target type you want to use when sorting. For example, the Encounter:subject search parameter can refer to targets of type Patient or Group. The following expression will not work because the specific target type to use is not clear to the server. http://example.org/Encounter?_sort=subject.family

The following qualified expression adds a type qualifier and will work: http://example.org/Encounter?_sort=Patient:subject.family

14.4.3.1Chained Sort Performance

Because they involve sorting on an index that is only connected to the primary resource in the search by a two-level join, the performance of chained sort expressions can be highly variable.

In particular, this kind of sorting can be very slow if the search returns a large number of results (e.g. a search for Encounter?sort=patient.name where there is a very large number of Encounter resources and no additional search parameters are limiting the number of included resources).

In order to improve sorting performance when chained sorts are needed, an Uplifted Refchain can be defined on the SearchParameter. This index will be used for the sorting expression and can improve performance.