Search Included Resources

You can include the _include and _revinclude parameters in your search query that include additional resources that are directly related to the primary results of your query. Using these parameters is more efficient than making a series of requests to retrieve these additional resources separately.

_include adds resources and resource versions to your query results that are referenced by the primary results that the query returns (forward inclusion).

_revinclude adds resources that reference the primary results (reverse inclusion).

Examples:

  • MedicationRequest?_include=MedicationRequest:subject

    This query searches over MedicationRequest resources and for each resource returned, it also returns the target of the subject reference, which might be a Group or Patient as defined in the FHIR specification.

  • MedicationRequest?_include=MedicationRequest:subject:Patient

    This query is similar but only returns subject references to Patient resources.

  • MedicationRequest?_revinclude=Provenance:target

    This query searches over MedicationRequest resources and for each resource returned, it also returns any Provenance resources with a target reference in the Provenance that refers to the matching resource.

Included resources do not count toward the page size. They won’t be counted in Bundle.total and they might cause the number of returned resources to be larger than a specified _count parameter.

1up APIs have limited support for _revinclude searches. The primary query must match no more than 1000 results or the search returns the following error. Resource references within a _revinclude query have exceeded inner query limit.

Wildcards with Include

When you include a wild card (*) with _include, all references available as search parameters are included in the results.

You can use the * wild card as the first and only argument in _include, or you can replace the search parameter name from the standard _include syntax, where the optional third value limits the resource type to a single type, as in the original behavior.

This example uses a wildcard to search over Observation resources and returns all referenced resources for each resource.

Observation?_include=*