Chain Search (R4 only)

Chain Search (R4 only)
A chained search allows a search to traverse references within the context of a query. The basic syntax for a chained search is:
/[BaseResource]?[ReferenceParameter].[InnerSearchParameter]=[InnerValue]
For example, PractitionerRole has a reference search parameter practitioner. To find PractitionerRole resources that have a practitioner reference which is a Practitioner resource having a name "John", you can search 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 would match a Patient that had two general-practitioner references, one named "Joe" and the other having 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
Warning: 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 where the inner query 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.
You may receive an inner query limit error message like the following when attempting a chain search:
GET Patient?general-practitioner.address-city=Boston&general-practitioner.gender=female
Practitioner references with address-city=Boston,gender=female have exceeded inner query limit 1000
If you receive this error you can break the search into its component searches, for example:
GET Practitioner?address-city=Boston
This would give you all the Practitioner resource IDs from Boston (e.g. ID1, ID2) and 
GET Practitioner?gender=female
would give you all the Practitioner resource IDs with gender of female (e.g., ID3, ID4)
You can then search for Patient resources referencing either set of providers
GET Patient?general-practitioner=ID1,ID2,ID3,ID4
Sort
_include & _revinclude (R4 only)
Last modified 1yr ago