Chained Search
Chained search is supported for FHIR® R4 only.
A chained search allows a search to traverse references within the context of a query. The following is an example of the basic syntax for a chained search.
/[BaseResource]?[ReferenceParameter].[InnerSearchParameter]=[InnerValue]
In this example syntax, PractitionerRole has the reference search parameter practitioner.
To find PractitionerRole resources that have a practitioner reference, for example, a Practitioner resource with the name John, you can submit a search request similar to the following.
PractitionerRole?practitioner.name=John
If the query has multiple chained parameters, each chain is evaluated independently.
For example, Patient?general-practitioner.name=Joe&general-practitioner.address-state=MA matches a Patient that had two general-practitioner references: one named Joe and the with an address in Massachusetts. There is no syntax to group these clauses together to match only Joe from Massachusetts without independent queries.
1up FHIR R4 APIs support single-level chained searches. You can't do a chained search using more than one level of chaining.
Inner Query limit
1up APIs have limited support for chained searches. The inner query must match no more than 1000 results or the search returns an error. This functionality is suitable for queries with an inner query that is highly selective.
For example, Observation?subject.identifier=123456 is likely to select a small number of Patient records and succeed, but PractitionerRole?practitioner.gender=male is not selective enough and is likely to be rejected.
Chain search exampleWhen you attempt a chain search, you might receive an inner query limit error message similar to the following message.
If you receive a similar error, you can separate your search into component searches, similar to the following example.
The following example returns all of the Practitioner resource IDs with the gender of female.
You can combine these parameters to search for Patient resources using the Practitioner resource IDs.
