# FHIR R4 search parameters for HealthLake
Use FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search) interaction to search a set of FHIR resources in a HealthLake data store based on some filter criteria. The `search` interaction can be performed using either a `GET` or `POST` request. For searches that involve personally identifiable information (PII) or protected health information (PHI), it's recommended to use `POST` requests, as PII and PHI is added as part of the request body and is encrypted in transit.
**Note**
The FHIR `search` interaction described in this chapter is built in conformance to the HL7 FHIR R4 standard for health care data exchange. Because it is a representation of a HL7 FHIR service, it is not offered through AWS CLI and AWS SDKs. For more information, see [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search) in the **FHIR R4 RESTful API documentation**.
You can also query HealthLake data stores with SQL using Amazon Athena. For more information, see Integrating.
HealthLake supports the following subset of FHIR R4 search parameters. For more information, see [FHIR R4 search parameters for HealthLake](#reference-fhir-search-parameters).
## Supported search parameter types
The following table shows the supported search parameter types in HealthLake.
**Supported search parameters types**
| Search parameter | Description |
| --- | --- |
| \$1id | Resource id (not a full URL) |
| \$1lastUpdated | Date last updated. Server has discretion on the boundary precision. |
| \$1tag | Search by a resource tag. |
| \$1profile | Search for all resources tagged with a profile. |
| \$1security | Search on security labels applied to this resource. |
| \$1source | Search on where the resource comes from. |
| \$1text | Search on the narrative of the resource. |
| createdAt | Search on custom extension createdAt. |
**Note**
The following search parameters are only supported for datastores created after December 09, 2023 : \$1security, \$1source, \$1text, createdAt.
The following table shows examples of how to modify query strings based on specified data types for a given resource type. For clarity, special characters in the examples column have not been encoded. To make a successful query, ensure that the query string has been properly encoded.
**Search parameter examples**
| Search Parameter Types | Details | Examples |
| --- | --- | --- |
| Number | Searches for a numerical value in a specified resource. Significant figures are observed. The number of significant digits are specific in by search parameter value, excluding leading zeros. Comparison prefixes are allowed. | `[parameter]=100` `[parameter]=1e2` `[parameter]=lt100` |
| Date/DateTime | Searches for a specific date or time. The expected format is `yyyy-mm-ddThh:mm:ss[Z\|(+\|-)hh:mm]` but can vary. Accepts the following data types: `date`, `dateTime`, `instant`, `Period`, and `Timing`. For more details using these data types in searches, see [date](https://www.hl7.org/fhir/search.html#date) in the **FHIR R4 RESTful API documentation**. Comparison prefixes are allowed. | `[parameter]=eq2013-01-14` `[parameter]=gt2013-01-14T10:00` `[parameter]=ne2013-01-14` |
| String | Searches for a sequence of characters in a case-sensitive manner. Supports both `HumanName` and `Address` types. For more details, see the [HumanName data type](https://www.hl7.org/fhir/datatypes.html#HumanName) entry and the [`Address` data type](https://www.hl7.org/fhir/datatypes.html#Address) entries in the **FHIR R4 documentation**. Advanced search is supported using `:text` modifiers. | `[base]/Patient?given=eve` `[base]/Patient?given:contains=eve` |
| Token | Searches for a close-to-exact match against a string of characters, often compared to a pair of medical code values. Case sensitivity is linked to the code system used when creating a query.Subsumption-based queries can help reduce issues linked to case sensitivity. For clarity the `\|` has not been encoded. | `[parameter]=[system]\|[code]`: Here `[system]` refers a coding system, and `[code]` refers to code value found within that specific system. `[parameter]=[code]`: Here your input will match either a code or a system. `[parameter]=\|[code]`: Here your input will match a code, and the system property has no identifier. |
| Composite | Searches for multiple parameters within a single resource type, using the modifiers`$` and `,` operation. Comparison prefixes are allowed. | `/Patient?language=FR,NL&language=EN` `Observation?component-code-value-quantity=http://loinc.org\|8480-6$lt60` `[base]/Group?characteristic-value=gender$mixed` |
| Quantity | Searches for a number, system, and code as values. A number is required, but system and code are optional. Based on the Quantity data type. For more details, see [Quantity](https://www.hl7.org/fhir/datatypes.html#Quantity) in the **FHIR R4 documentation**. Uses the following assumed syntax `[parameter]=[prefix][number]\|[system]\|[code]` | `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=le5.4\|http://unitsofmeasure.org\|mg` |
| Reference | Searches for references to other resources. | `[base]/Observation?subject=Patient/23` `test` |
| URI | Searches for a string of characters that unambiguously identifies a particular resource. | `[base]/ValueSet?url=http://acme.org/fhir/ValueSet/123` |
| Special | Searches based on integrated medical NLP extensions. |
## Advanced search parameters supported by HealthLake
HealthLake supports the following advanced search parameters.
| Name | Description | Example | Capability |
| --- | --- | --- | --- |
| \$1include | Used to request that additional resources be returned in a search request. It returns resources which are referenced by the target resource instance. | Encounter?\$1include=Encounter:subject | |
| \$1revinclude | Used to request that additional resources be returned in a search request. It returns resources that reference the primary resource instance. | Patient?\$1id=patient-identifier&\$1revinclude=Encounter:patient | |
| \$1summary | Summary can be used to request a subset of the resource. | Patient?\$1summary=text | The following summary parameters are supported: \$1summary=true, \$1summary=false, \$1summary=text, \$1summary=data. |
| \$1elements | Request a specific set of elements to be returned as part of a resource in the search results. | Patient?\$1elements=identifier,active,link | |
| \$1total | Returns the number of resources that match the search parameters. | Patient?\$1total=accurate | Support \$1total=accurate, \$1total=none. |
| \$1sort | Indicate the sort order of the returned search results using a comma-separated list. The - prefix can be used for any sort rule in the comma-separated list to indicate descending order. | Observation?\$1sort=status,-date | Support sort by fields with types Number, String, Quantity, Token, URI, Reference. Sort by Date is only supported for data stores created after December 09, 2023. Support up to 5 sort rules. |
| \$1count | Control how many resources are returned per page of the search bundle. | Patient?\$1count=100 | Maximum page size is 100. |
| chaining | Search elements of referenced resources. The . directs the chained search to the element within the referenced resource. | DiagnosticReport?subject:Patient.name=peter | |
| reverse chaining (\$1has) | Search for a resource based on the elements of resources that refer to them. | Patient?\$1has:Observation:patient:code=1234-5 | |
`_include`
Using `_include` in a search query allows for additional specified FHIR resources to also be returned. Use `_include` to include resources that are linked forward.
**Example – To use `_include` to find the patients or the group of patients who have been diagnosed with a cough**
You would search on the `Condition` resource type specifying the diagnostic code for cough, and then using `_include` specify that you want the `subject` of that diagnosis returned too. In the `Condition` resource type `subject` refers to either the patient resource type or the group resource type.
For clarity, special characters in the example have not been encoded. To make a successful query ensure that the query string has been properly encoded.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Condition?code=49727002&_include=Condition:subject
```
`_include:iterate` Modifier
The `_include:iterate` modifier enables recursive inclusion of referenced resources across two levels. For example,
```
GET /ServiceRequest?identifier=025C0931195&_include=ServiceRequest:requester&_include:iterate=PractitionerRole:practitioner
```
will return the ServiceRequest, its associated PractitionerRole (via the requester reference), and then recursively include the Practitioner referenced by that PractitionerRole. This modifier is available for all resource types in HealthLake.
`_include=*` Modifier
The `_include=*` modifier is a wildcard that automatically includes all resources directly referenced by the search results. For example,
```
GET /ServiceRequest?specimen.accession=12345&_include=*
```
will return the matching ServiceRequest along with all resources it references (such as Patient, Practitioner, Specimen, etc.) without needing to specify each reference path individually. This modifier is available for all resource types in HealthLake.
`_revinclude`
Using `_revinclude` in a search query allows for additional specified FHIR resources to also be returned. Use `_revinclude` to include resources that are linked backwards.
**Example – To use `_revinclude` to include related Encounter and Observation resource types linked to a specific Patient**
To make this search, you would first define the individual `Patient` by specifying their identifier in the `_id` search parameter. Then you would specify additional FHIR resources using the structure `Encounter:patient` and `Observation:patient`.
For clarity, special characters in the example have not been encoded. To make a successful query ensure that the query string has been properly encoded.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Patient?_id=patient-identifier&_revinclude=Encounter:patient&_revinclude=Observation:patient
```
`_summary`
Using `_summary` in a search query allows user to request a subset of the FHIR resource. It can contain one of the following values: `true, text, data, false`. Any other values will be treated as invalid. The returned resources will be marked with `'SUBSETTED'` in meta.tag, to indicate that resources are incomplete.
+ `true`: Return all supported elements that are marked as 'summary' in the base definition of the resource(s).
+ `text`: Return only the 'text', 'id', 'meta' elements, and only top-level mandatory elements.
+ `data`: Return all parts except the 'text' element.
+ `false`: Return all parts of the resource(s)
In a single search request, `_summary=text` cannot be combined with `_include` or `_revinclude` search parameters.
**Example – Get “text” element of Patient resources in a data store.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_summary=text
```
`_elements`
Using `_elements` in a search query allows for specific FHIR resource elements to be requested. The returned resources will be marked with `'SUBSETTED'` in meta.tag, to indicate that resources are incomplete.
The `_elements` parameter consists of a comma-separated list of base element names such as elements defined at the root level in the resource. Only elements that are listed are to be returned. If `_elements` parameter values contain invalid elements, server will ignore them and return mandatory elements and valid elements.
`_elements` will not be applicable to included resources(returned resources whose search mode is `include`).
In a single search request, `_elements` cannot be combined with `_summary` search parameters.
**Example – Get “identifier”, “active”, “link” elements of Patient resources in your HealthLake data store.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_elements=identifier,active,link
```
`_total`
Using `_total` in a search query will return number of resources that match the requested search parameters. HealthLake will return the total number of matched resources(returned resources whose search mode is `match`) in the `Bundle.total` of search response.
`_total` supports the `accurate`, `none` parameter values. `_total=estimate` is not supported. Any other values will be treated as invalid. `_total` is not applicable to the included resources(returned resources whose search mode is `include`).
**Example – Get the total number of Patient resources in a data store:**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_total=accurate
```
`_sort`
Using `_sort` in the search query arranges the results in a specific order. The results are ordered based on the comma-separated list of sort rules in priority order. The sort rules should be valid search parameters. Any other values will be treated as invalid.
In a single search request, you can use up to 5 sort search parameters. You can optionally use a `-` prefix to indicate descending order. Server will sort on ascending order by default.
The supported sort search parameter types are: `Number, String, Date, Quantity, Token, URI, Reference`. If a search parameter refers to an element that is nested, this search parameter is not supported for sort. For example, search on 'name' of resource type Patient refers to Patient.name element with HumanName data type is considered as nested. Thus, sort on Patient resources by 'name' is not supported.
**Example – Get Patient resources in a data store and sort them by birthdate in ascending order:**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_sort=birthdate
```
`_count`
The parameter `_count` is defined as an instruction to the server regarding how many resources should be returned in a single page.
The maximum page size is 100. Any values greater than 100 is invalid. `_count=0` is not supported.
**Example – Search for the Patient resource and set search page size to 25:**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_count=25
```
`Chaining and Reverse Chaining(_has)`
Chaining and reverse chaining in FHIR provide a more efficient and compact way to obtain interconnected data, reducing the need for multiple separate queries and making data retrieval more convenient for developers and users.
If any level of recursion return more than 100 results, HealthLake will return 4xx to protect data store from being overloaded and causing multiple paginations.
**Example – Chaining - Gets all DiagnosticReport which refer to a Patient where Patient name is peter.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DiagnosticReport?subject:Patient.name=peter
```
**Example – Reverse Chaining - Get Patient resources, where the patient resource is referred to by at least one Observation where the observation has a code of 1234, and where the Observation refers to the patient resource in the patient search parameter.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_has:Observation:patient:code=1234
```
## Supported search modifiers
Search modifiers are used with string-based fields. All search modifiers in HealthLake use Boolean-based logic. For example, you could specify `:contains` to specify that larger string field should include a small string in order for it to be included in your search results.
**Supported search modifiers**
| Search modifier | Type |
| --- | --- |
| :missing | All parameters except Composite |
| :exact | String |
| :contains | String |
| :not | Token |
| :text | Token |
| :identifier | Reference |
| :below | URI |
## Supported search comparators
You can use search comparators to control the nature of the matching in a search. You can use comparators when searching on number, date, and quantity fields. The following table lists search comparators and their definitions that are supported by HealthLake.
**Supported search comparators**
| Search comparator | Description |
| --- | --- |
| eq | The value for the parameter in the resource is equal to the provided value. |
| ne | The value for the parameter in the resource is not equal to the provided value. |
| gt | The value for the parameter in the resource is greater than the provided value. |
| lt | The value for the parameter in the resource is less than the provided value. |
| ge | The value for the parameter in the resource is greater or equal to the provided value. |
| le | The value for the parameter in the resource is less or equal to the provided value. |
| sa | The value for the parameter in the resource starts after the provided value. |
| eb | The value for the parameter in the resource ends before the provided value. |
## FHIR search parameters not supported by HealthLake
HealthLake supports all FHIR search parameters with the exception of those listed in the following table. For a full list of FHIR search parameters, see the [FHIR search parameter registry.](https://hl7.org/fhir/R4/searchparameter-registry.html)
**Unsupported search parameters**
| | |
| --- |--- |
| Bundle-composition | Location-near |
| Bundle-identifier | Consent-source-reference |
| Bundle-message | Contract-patient |
| Bundle-type | Resource-content |
| Bundle-timestamp | Resource-query |