# Chained Searches

Chaining search parameters allows you to filter your searches based on the parameters of another resource which is related to the target resource through one or more references. This can reduce what might otherwise be a series of searches into just a single action.

Chained searches are similar to using [`_include` or `_revinclude` parameters](/content/docs/search/includes/index.html), but it will not return the referenced resources, only filter based on their parameters. The primary benefit of this is it allows for easy pagination since you know you will only receive results of one resource type. See the [paginated search docs](/content/docs/search/paginated-search/index.html) for more details.

## Chained Search Availability

Chained search is only available when using the FHIR Rest API as described here. If you are using GraphQL, chained search functionality is not supported.

## Forward Chained Search [​](/content/docs/search/chained-search#forward-chained-search "Direct link to Forward Chained Search"/index.html)

[Search parameters](/content/docs/search/basic-search/index.html) with the `reference` type can be chained together to search on the elements of the referenced resource.

In the below example we search for all [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources that are linked to a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) with the name of 'homer' using the syntax `patient.name=homer`. The way to read this is "search for all [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources that reference a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) (using the `patient` search parameter) and has a name of 'homer'.

### Example: Search for any [`Observations`](/content/docs/api/fhir/resources/observation/index.html) about a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) with the name 'homer'

```ts
await medplum.searchResources('Observation', {
  'patient.name': 'homer',
});
```

```bash
medplum get 'Observation?patient.name=homer'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Observation?patient.name=homer' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```

The target resource for every link in the chain must be unambiguous. If a search parameter can reference multiple resource types, you must specify the resource type in your search.

Just like the example above, the below example searches for all [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources linked to a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) with a name of 'homer', this time using the syntax `subject:Patient.name=homer`. The way to read this is "search for all [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources whose `subject` parameter is of type [`Patient`](/content/docs/api/fhir/resources/patient/index.html) and has a name 'homer'."

### Example: Search for any [`Observations`](/content/docs/api/fhir/resources/observation/index.html) about a subject that is a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) with the name 'homer'

```ts
await medplum.searchResources('Observation', {
  'subject:Patient.name': 'homer',
});
```

```bash
medplum get 'Observation?subject:Patient.name=homer'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Observation?subject:Patient.name=homer' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```

You can include more than one link in your chained search. In the below example, we search for [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources that are linked to an [`Encounter`](/content/docs/api/fhir/resources/encounter/index.html) done by a service-provider with the name of 'Kaiser'.

### Example: A chained search that chains multiple parameters

```ts
await medplum.searchResources('Observation', {
  'encounter:Encounter.service-provider.name': 'Kaiser',
});
```

```bash
medplum get 'Observation?encounter:Encounter.service-provider.name=Kaiser'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Observation?encounter:Encounter.service-provider.name=Kaiser' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```

## Reverse Chained Search [​](/content/docs/search/chained-search#reverse-chained-search "Direct link to Reverse Chained Search"/index.html)

Chained references can also be constructed in reverse, filtering on other resources that reference your target search resource. This is done using the `_has` parameter, which has a special syntax: `_has:<next resource type>:<link parameter>:<next parameter>`.

For example, `Patient?_has:Observation:subject:status=preliminary` would select [`Patient`](/content/docs/api/fhir/resources/patient/index.html) resources that have an [`Observation`](/content/docs/api/fhir/resources/observation/index.html) pointing to them as the `subject` and are also in preliminary status.

### Example: Search for any [`Patients`](/content/docs/api/fhir/resources/patient/index.html) that have had an observed heart rate above 150

```ts
await medplum.searchResources('Patient', {
  '_has:Observation:subject:code': '8867-4',
});
```

```bash
medplum get 'Patient?_has:Observation:subject:code=8867-4'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Patient?_has:Observation:subject:code=8867-4' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```

In the above example `_has:Observation` filters for [`Patient`](/content/docs/api/fhir/resources/patient/index.html) resources that have an [`Observation`](/content/docs/api/fhir/resources/observation/index.html). The `:subject` filters for [`Observation`](/content/docs/api/fhir/resources/observation/index.html) resources that reference a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) in the subject field. This is based on our initial search for a [`Patient`](/content/docs/api/fhir/resources/patient/index.html). Finally, `:code=8867-4` filters for that specific code on the [`Observation`](/content/docs/api/fhir/resources/observation/index.html).

### Nesting reverse chained searches [​](/content/docs/search/chained-search#nesting-reverse-chained-searches "Direct link to Nesting reverse chained searches"/index.html)

It is also possible to nest the `_has` parameter.

In this example we search for a [`Specimen`](/content/docs/api/fhir/resources/specimen/index.html) that is referenced by a [`DiagnosticReport`](/content/docs/api/fhir/resources/diagnosticreport/index.html) that originated from a [`Procedure`](/content/docs/api/fhir/resources/procedure/index.html) on the date of `2023-11-12`.

### Example: Nested reversed chained search

```ts
await medplum.searchResources('Specimen', {
  '_has:DiagnosticReport:specimen:_has:Procedure:reason-reference:date': '2023-11-12',
});
```

```bash
medplum get 'Specimen?_has:DiagnosticReport:specimen:_has:Procedure:reason-reference:date=2023-11-12'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Specimen?_has:DiagnosticReport:specimen:_has:Procedure:reason-reference:date=2023-11-12' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```

### Combining forward and reverse chained search [​](/content/docs/search/chained-search#combining-forward-and-reverse-chained-search "Direct link to Combining forward and reverse chained search"/index.html)

You can mix and match chained parameters by combining a forward chained search with the `_has` parameter.

In the below example, we search for a [`Patient`](/content/docs/api/fhir/resources/patient/index.html) with an [`Observation`](/content/docs/api/fhir/resources/observation/index.html) that was performed by a [`CareTeam`](/content/docs/api/fhir/resources/careteam/index.html) that has a member with the name of 'bob'.

### Example: Combining reverse and forward chained search

```ts
await medplum.searchResources('Patient', {
  '_has:Observation:subject:performer:CareTeam.participant:Practitioner.name': 'bob',
});
```

```bash
medplum get 'Patient?_has:Observation:subject:performer:CareTeam.participant:Practitioner.name=bob'
```

```bash
curl 'https://api.medplum.com/fhir/R4/Patient?_has:Observation:subject:performer:CareTeam.participant:Practitioner.name=bob' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
```