Overview of FHIR search

The Fast Healthcare Interoperability Resources (FHIR®) specification defines an API for querying resources in a FHIR server database. This article guides you through key aspects of querying data in FHIR. For complete details about the FHIR search API, refer to the HL7 FHIR Search documentation.

Throughout this article, we demonstrate FHIR search syntax in example API calls with the {{FHIR_URL}} placeholder to represent the FHIR server URL. If the FHIR service is in Azure Health Data Services, this URL would be https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.

FHIR searches can be against a specific resource type, a specified compartment, or all resources in the FHIR server database. The simplest way to execute a search in FHIR is to use a GET request. For example, if you want to pull all Patient resources in the database, you could use the following request.

GET {{FHIR_URL}}/Patient

You can also search using POST. To search using POST, the search parameters are delivered in the body of the request. This makes it easier to send queries with longer, more complex series of parameters.

With either POST or GET, if the search request is successful, you receive a FHIR searchset bundle containing the resource instances returned from the search. If the search fails, you’ll find the error details in an OperationOutcome response.

In the following sections, we cover the various aspects of querying resources in FHIR. Once you’ve reviewed these topics, refer to the FHIR search samples page, which features examples of different FHIR search methods.

Search parameters

When you do a search in FHIR, you're searching the database for resources that match certain criteria. The FHIR API specifies a rich set of search parameters for fine-tuning search criteria. Each resource in FHIR carries information as a set of elements, and search parameters work to query the information in these elements. In a FHIR search API call, if a positive match is found between the request's search parameters and corresponding element values stored in a resource instance, then the FHIR server returns a bundle containing the resource instances whose elements satisfied the search criteria.

For each search parameter, the FHIR specification defines the data type that can be used. Support in the FHIR service for the various data types is outlined below.

Common search parameters

There are common search parameters that apply to all resources in FHIR. These are listed as follows, along with their support in the FHIR service.

Resource-specific parameters

The FHIR service in Azure Health Data Services supports almost all resource-specific search parameters defined in the FHIR specification. Search parameters that aren't supported are listed in the links below:

• STU3 Unsupported Search Parameters

• R4 Unsupported Search Parameters

You can also see the current support for search parameters in the FHIR Capability Statement with the following request:

GET {{FHIR_URL}}/metadata

To view the supported search parameters in the capability statement, navigate to CapabilityStatement.rest.resource.searchParam for the resource-specific search parameters and CapabilityStatement.rest.searchParam for search parameters that apply to all resources.

Composite search parameters

Composite searches in FHIR allow you to search against element pairs as logically connected units. For example, if you were searching for observations where the height of the patient was over 60 inches, you would want to make sure that a single property of the observation contained the height code and a value greater than 60 inches (the value should only pertain to height). For example, you wouldn't want a positive match on an observation with the height code and an arm length code over 60 inches. Composite search parameters prevent this problem by searching against pre-specified pairs of elements whose values must both meet the search criteria for a positive match to occur.

The FHIR service in Azure Health Data Services supports the following search parameter type pairings for composite searches.

• Reference, Token
• Token, Date
• Token, Number, Number
• Token, Quantity
• Token, String
• Token, Token

For more information, see the HL7 Composite Search Parameters documentation.

Modifiers & prefixes

Modifiers allow you to qualify search parameters with additional conditions. Below is a table of FHIR modifiers and their support in the FHIR service.

For search parameters that have a specific order (numbers, dates, and quantities), you can use a prefix before the parameter value to refine the search criteria (for example, Patient?_lastUpdated=gt2022-08-01 where the prefix gt means "greater than"). The FHIR service in Azure Health Data Services supports all prefixes defined in the FHIR standard.

Search result parameters

FHIR specifies a set of search result parameters to help manage the information returned from a search. For details on how to use search result parameters in FHIR, refer to the HL7 website. Following is a table of FHIR search result parameters and their support in the FHIR service.

Note:

1. By default, _sort arranges records in ascending order. You can also use the prefix - to sort in descending order. The FHIR service only allows you to sort on a single field at a time.
2. FHIR service supports wild card searches with revinclude. Adding a "." query parameter in a revinclude query directs the FHIR service to reference all the resources mapped to the source resource.

By default, the FHIR service in Azure Health Data Services is set to lenient handling. This means that the server ignores any unknown or unsupported parameters. If you want to use strict handling, you can include the Prefer header and set handling=strict.

Chained & reverse chained searching

A chained search allows you to perform fine-targeted queries for resources that have a reference to another resource. For example, if you want to find encounters where the patient’s name is Jane, use:

GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane

The . in the preceding request steers the path of the chained search to the target parameter (name in this case).

Similarly, you can do a reverse chained search with the _has parameter. This allows you to retrieve resource instances by specifying criteria on other resources that reference the resources of interest. For examples of chained and reverse chained search, refer to the FHIR search examples page.

Pagination

As previously mentioned, the results from a FHIR search are available in paginated form at a link provided in the searchset bundle. By default, the FHIR service displays 10 search results per page, but this can be increased (or decreased) by setting the _count parameter. If there are more matches than fit on one page, the bundle includes a next link. Repeatedly fetching from the next link yields the subsequent pages of results. Note that the _count parameter value can't exceed 1000.

Currently, the FHIR service in Azure Health Data Services only supports the next link and doesn’t support first, last, or previous links in bundles returned from a search.

FAQ

What does "partial support" mean in R4 Unsupported Search Parameters?

Some of the resource-specific search parameters cover more than one data type, and the FHIR service in Azure Health Data Services may only support that search parameter on one of those data types. For example, Condition-abatement-age and Condition-onset-age cover two different data types, Age and Range; however, the FHIR service in Azure Health Data Services supports those two search parameters on Range, but not on Age.

Is the $lastn operation for Observations supported?

This is not supported. The alternative approach would be to use _count to restrict resources returned per page and _sort to provide results in descending order.

Next steps

Now that you've learned about the basics of FHIR search, see the search samples page for details about how to search using search parameters, modifiers, and other FHIR search methods.