Search with _include

_include returns resources that are referenced by your primary matches — essentially the forward side of _revinclude.

For example, to get all Observations for a code and include the Patient referenced in each Observation:

curl 'http://localhost/fhir/acme/Observation?code=http%3A%2F%2Floinc.org%7C82810-3&_include=Observation%3Asubject'

Response (200 OK) — abbreviated:

{
    "resourceType": "Bundle",
    "id": "f35787bc-b1e1-4552-b825-8db5a3e107b7",
    "meta": {
        "lastUpdated": "2025-10-10T14:32:27.774-07:00"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "http://localhost:8080/fhir/acme/Observation?_include=Observation%3Asubject&code=http%3A%2F%2Floinc.org%7C82810-3"
        }
    ],
    "entry": [
        {
            "fullUrl": "http://localhost:8080/fhir/acme/Observation/pregnancy-status",
            "resource": {
                "resourceType": "Observation",
                "id": "pregnancy-status",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-10-08T17:49:58.299+00:00",
 ...
         {
            "fullUrl": "http://localhost:8080/fhir/acme/Patient/example",
            "resource": {
                "resourceType": "Patient",
                "id": "example",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-10-08T17:49:58.037+00:00",
...
            },
            "search": {
                "mode": "include"
            }
        }
    ]
}

How it works

• FHIR first finds Observation resources matching the search parameters.
• It inspects each Observation’s subject.reference field.
• It fetches the Patient resources referenced there.
• The resulting Bundle contains:
  • Observations with "search": { "mode": "match" }
  • Patients with "search": { "mode": "include" }
• You can specify multiple _include parameters:
  • ?_include=Observation:subject&_include=Observation:performer

Tip: _include can be used with any reference field listed in the FHIR Search Parameters definition for that resource type.

Search with Chain

Chained parameters let you filter resources by properties of a referenced resource. In other words: “Find Observations whose Patient’s name is Baxter.”

curl 'http://localhost/fhir/acme/Observation?subject.name=Baxter'

Response (200 OK) — abbreviated:

{
    "resourceType": "Bundle",
    "id": "c303f2ee-6c9a-43f1-86dd-34ec6855b84f",
    "meta": {
        "lastUpdated": "2025-10-10T14:40:03.700-07:00"
    },
    "type": "searchset",
    "total": 46,
    "link": [
        {
            "relation": "self",
            "url": "http://localhost:8080/fhir/acme/Observation?patient.name=Baxter"
        }
    ],
    "entry": [
        {
            "fullUrl": "http://localhost:8080/fhir/acme/Observation/pregnancy-status",
            "resource": {
                "resourceType": "Observation",
                "id": "pregnancy-status",
                "meta": {
                    "versionId": "1",
                    "lastUpdated": "2025-10-08T17:49:58.299+00:00",
...
            },
            "search": {
                "mode": "match"
            }
        }
    ]
}

How it works

• subject is a reference field on Observation.
• The server performs a subquery on the referenced type (Patient), finding all Patients with name=Baxter.
• Then, it filters Observations whose subject.reference matches those Patient IDs.
• This allows expressive queries such as:
  • Observation?subject.identifier=http://hospital.smarthealthit.org|1032702&Encounter?patient.birthdate=lt1990-01-01&DocumentReference?patient.name=Smith

Under the Hood

• Chaining uses a two-phase lookup:
  • FTS query on the referenced type (e.g., Patient) using the chained condition.
  • Use resulting IDs to constrain the primary type (e.g., Observation).
• _include works similarly to _revinclude, but in reverse:
  • Collect reference fields from primary results (e.g., Observation.subject.reference).
  • Gather referenced resource keys.
• Batch-fetch via KV to build the combined Bundle.
• Both phases are read-committed; all resources are fetched as committed documents.
• All keys are de-duplicated before KV retrieval.

Notes & Best Practices

• _include and _revinclude can be combined in the same query.
• _count, _summary, and _elements apply only to primary results in this release.
• Includes and chained lookups can be expensive — use narrow filters (like identifiers) for best performance.