FHIR search overview in Azure Health Data Services

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 FHIR search in Azure Health Data Services, including search parameters, modifiers, pagination, and chained searches. For complete details about the FHIR search API, refer to the HL7 FHIR Search documentation.

Throughout this article, the {{FHIR_URL}} placeholder represents the base URL of the FHIR service in example API calls that demonstrate FHIR search syntax. If the FHIR service is in Azure Health Data Services, this URL is https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.

You can perform FHIR searches 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, use the following request.

GET {{FHIR_URL}}/Patient

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

By using 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, the OperationOutcome response contains the error details.

In the following sections, you learn about the various aspects of querying resources in FHIR. When you finish reviewing these topics, see the FHIR search samples page, which features examples of different FHIR search methods.

Search parameters

When you search in FHIR, you search 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.

If search parameters positively match resource element values, the FHIR server returns a bundle of the matching resources.

For each search parameter, the FHIR specification defines the data type that you can use. The following table outlines support in the FHIR service for the various data types.

Common search parameters

Common search parameters apply to all resources in FHIR. The following table lists these parameters, 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. The following links list search parameters that aren't supported:

• STU3 Unsupported Search Parameters

• R4 Unsupported Search Parameters

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

GET {{FHIR_URL}}/metadata

To view the supported search parameters in the capability statement, go 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 treat element pairs as a single unit. For example, when you search for observations where a patient's height is over 60 inches, the height code and the value must come from the same observation. Without composite search, an observation with the height code and an arm length value over 60 inches could also match. Composite search parameters avoid this issue by requiring both values in a predefined element pair to satisfy the criteria.

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 and prefixes for FHIR search parameters

Modifiers let you qualify search parameters with extra conditions. The following table shows FHIR modifiers and their support in the FHIR service.

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

rhia

FHIR 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. The following table shows FHIR search result parameters and their support in the FHIR service.

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 wildcard searches with the _revinclude parameter. 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 setting means that the server ignores any unknown or unsupported parameters. If you want to use strict handling, include the Prefer header and set handling=strict.

_include and _revinclude searches

The FHIR service supports search queries that use the _include and _revinclude parameters. These parameters allow you to retrieve reference resources in the search results.

The _include search parameter enables the retrieval of a particular FHIR resource, and any other FHIR resources that it references. When used in a query, the _include parameter returns the specified resource and resources it references. The _revinclude search parameter operates in the reverse, allowing the retrieval of a resource, along with any other resources that reference it, providing a way to search for resources based on their relationships with other resources. For detailed information on include and _revinclude in search parameters, refer to the FHIR Search Documentation.

Request parameters

When you execute a search request with _include and _revinclude parameters, use the following optional parameters to control the count.

The response from _include and _revinclude searches includes up to 1,000 items. If there are more than 1,000 matched items, the response provides a link that you can use to navigate the complete result set.

In the following example, a search request for Observations is made for Patient with Identifier 123.

GET {{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10

The response has Observation data for Patient 123. The matched resources are provided 10 per page, with a link provided to navigate the complete result set.

{ 

  	"resourceType": "Bundle", 

 	 "id": "b5491e39-8f8f-4405-a4cf-2a6716755d73", 

  	"meta": { 

    	"lastUpdated": "2025-04-10T21:09:42.6517693+00:00" 

  	}, 

  	"type": "searchset", 

  "	link": [ 

    	{ 

      	"relation": "next", 

      	"url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10&ct=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGpSSwAAAD%2F%2Fw%3D%3D" 

    	}, 

   	 { 

    	  "relation": "related", 

      	"url": "{{FHIR_URL}}/Observation/$include?subject.identifier=123&_include=Observation:subject&_includesCount=10&includesCt=er97f5lRTbShgbGOqaGhgbGlsZGFmaWJiYWBgYGhAaaYqYmOqQUWYaNYAAAAAP%2F%2F" 

   	 }, 

    	{ 

    	  "relation": "self", 

     	 "url": "{{FHIR_URL}}/Observation?subject.identifier=123&_include=Observation:subject&_includesCount=10” 

    	} 

  	], 

  "entry": [….] 

}

Chained and reverse chained searching

A chained search lets you perform targeted queries for resources that reference 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 directs 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 parameter retrieves resource instances by specifying criteria on other resources that reference the resources of interest. For examples of chained and reverse chained search, see the FHIR search examples page.

Pagination

As previously mentioned, you can view the results from a FHIR search in paginated form at a link provided in the searchset bundle. By default, the FHIR service displays 10 search results per page, but you can change this number 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. The _count parameter value can't exceed 1,000.

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 resource-specific search parameters cover more than one data type, and the FHIR service in Azure Health Data Services might 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 operation isn't supported. The alternative approach is to use _count to restrict resources returned per page and _sort to provide results in descending order.

Next steps

To learn more about FHIR search, see the search samples page. You can find details about how to search by using search parameters, modifiers, and other FHIR search methods.