The topics covered in this module are:
Search operations traverse through an existing set of resources filtering by parameters supplied to the search operation. The FHIR search framework is described here: https://www.hl7.org/fhir/search.html
In the simplest case, a search is executed by performing a
GET operation in the RESTful framework, which has the following format:
The different parts of this operation are explained below:
Below are a couple of examples of searches on the Vonk server. Note that you can also test these examples by copy-pasting the link (without
GET) in your browser.
In this example no search parameter is used. By using only base and type you can retrieve all instances of a specific Resource type. Run this example to get all Patients from the Vonk server.
When adding one or more search parameters to your query, start with a question mark behind type. In this example the search parameter
name of the Patient Resource is used. This search parameter can be used to find matches on any of the String fields in HumanName, including family, given, prefix, suffix, suffix, and/or text. Run this example to get all Patients named Caro from the Vonk server.
You can add more than one search parameter by using the
& character. In this example, we use the search parameters
given to search for Patients named Caro Emerald (given=Caro and family=Emerald). We also include the
_format parameter to get the output in JSON format. Run this example to get all Patients named Caro Emerald from the Vonk server in JSON format.
Each Resource can be searched by a couple of common parameters (e.g.
_tag) and the additional search parameters that are specified for this Resource. When you scroll down in the Content tab of the documentation of a Resource, you find the search parameters defined for that Resource. You can also find a list of all search parameters here: https://www.hl7.org/fhir/searchparameter-registry.html
The table below shows the search parameter types, common search parameters for all resources and the search result parameters.
Each search parameter has a certain type (e.g. a String or a Number), which specifies the type of data that is searched upon. For the ordered parameter types of number, date, and quantity, a prefix to the parameter value may be used to control the nature of the matching. For example, if you want to search within a specific date range, you would use the prefixes
ge (greater or equal) and
le (less or equal). For example:
These are the defined search parameter types
|number||Search parameter SHALL be a number (a whole number, or a decimal).||
|date||Search parameter is on a date/time. The date format is the standard XML format.||
|string||Search parameter is a simple string, like a name part. Search is case-insensitive and accent-insensitive. May match just the start of a string. String parameters may contain spaces.||
|token||Search parameter on a coded element or identifier. May be used to search through the text, displayname, code and code/codesystem (for codes) and label, system and key (for identifier). Its value is either a string or a pair of namespace and value, separated by a
|reference||A reference to another resource.||
|composite||A composite search parameter that combines a search on two values together.||
|quantity||A search parameter that searches on a quantity.||
|uri||A search parameter that searches on a URI (RFC 3986).||
Depending on the type of the search parameters, modifiers can sometimes be used. For example, a search on a String can be altered by the
:exact modifier to match the exact String value or the
:contains modifier to search for String values that match partly match the value.
Suppose you have three Patients in your database, one named Caro, one named Carola and one named Jim. You run the following search requests:
The first request would return both Caro and Carola, as Carola contains the String value Caro. The second request would only return Caro, as you're asking the server for an exact match of both String values.
For the parameter types of
quantity, a prefix to the value may be used to control the nature of the matching. If no prefix is present, the prefix
eq is assumed. The following prefixes can be used:
|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|
|ap||the value for the parameter in the resource is approximately the same to the provided value. Note that the recommended value for the approximation is 10% of the stated value (or for a date, 10% of the gap between now and the date), but systems may choose other values where appropriate|
Get all appointments that start after or on January 1st 2018 and until and including February 15th 2019
More details about the prefixes, including extensive examples, can be found on the FHIR specification search spec
This set of parameters works for all Resource types. In this section we will explain a couple of them:
_idparameter refers to the logical ID of the Resource and can be used to search for a specific instance of the Resource. Note however that a search operation always returns a Bundle, even if the number of matches is 1. To go to an instance directly you would need to use
_lastUpdatedparameter can be used to search for Resources that are updated after a certain Date.
_securityparameters search on the equivalent parameters in the meta element. For example, tags could be used to mark that a Resource should still be reviewed.
_profileparameter can be used to restrict the search to instances of a specific profile only.
The search result parameters can be used to manage the returned Resources. For example the
_sort parameter can be used to order the returned Resources alphabetically by name. Another example is the
_count parameter, which allows you to define the maximum number of search results you want to show on a page. For example, suppose your search results in 15 Patients and you have set the
_count to 10. In this case, the first page of the Bundle would show the first 10 Patients and the second page would show the remaining 5 Patients.
Here is a list of all parameters that can be used to manage the returned results.
|_sort||Order to sort results in (can repeat for inner sort orders)||Name of a valid search parameter||
|_count||Number of results per page||Whole number||
|_include||Other resources to include in the search results that search matches point to||SourceType:searchParam(:targetType)||
|_revinclude||Other resources to include in the search results when they refer to search matches||SourceType:searchParam(:targetType)||
|_summary||Just return the summary elements (for resources where this is defined)||
|_contained||Whether to return resources contained in other resources in the search matches||
|_containedType||If returning contained resources, whether to return the contained or container resources||
|_elements||return a specific set of elements as part of a resource||Name of resource elements||
Some FHIR servers allow you to add custom search parameters. For example, if you are running your own Vonk implementation, you can choose to add custom search parameters by either posting them to the administration database or you can configure the settings to automatically load them from a local folder on your machine when starting your server.
Below is an example of a custom search parameter that was created for the US to search on race. This search parameter is not part of the core specification, but as it is common to include race in the US, they provide this search parameter at a national level.
|Published by||US Realm Steering Committee|
|Status||Draft (since 2016-12-22)|
Returns patients with a race extension matching the specified code.
|Patient||race||token||f:Patient/f:extension[@url='http://hl7.org/fhir/us/core/StructureDefinition/us-core-race']/f:extension[@url='ombCategory' or @url='detailed']|
You can run search requests in your browser, but if you are running them more frequently, we would advice you to download a REST client. One that we like to use is Postman. Postman is free to use and allows you to save requests to collections and share them with others. If you want to learn more about running your own requests, a nice starting point is the free tutorial of the Australian Digital Health Agency.
Here below is an examples of a customer that we helped building profiles.
Nictiz is the centre of expertise for standardization and eHealth in The Netherlands. HL7 Netherlands core and MedMij profiles are published on Simplifier. MedMij is a national project that aims to give Dutch citizens integrated access to all their health data in one personal health environment. FHIR is used as a standard to exchange health information between the involved parties. The profiles are based on standardized clinical building blocks called Health and Care Information Models (HCIM).
Nictiz has defined a couple of search parameters for The Netherlands. One of them is the Medications-periodofuse, which can be used to search on medication use in the past, present or future within the specified time period. The code of this search parameter is
periodofuse and it can be used for the following types of Resources: MedicationRequest and MedicationDispense, provided they include the zib-Medication-PeriodOfUse extension.
|Status||Draft (since 2017-11-28T14:26:13.365+00:00)|
Multiple Resources: * MedicationRequest: Searches MedicationRequests resources based on the period of use, provided in the value of the 'http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse' extension. * MedicationDispense: Searches MedicationDispense resources based on the period of use, provided in the value of the 'http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse' extension.
To select the MedicationRequest and MedicationDispense resources based on the date/time of the period of use. The period of use is defined in an extension and used in the profiles for the Health and Care Information models (HCIM) Medication Agreement and Administration Agreement.
|MedicationRequest, MedicationDispense||periodofuse||date||MedicationRequest.extension('http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse') | MedicationDispense.extension('http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse')||f:MedicationRequest/f:extension[@url='http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse'] | f:MedicationDispense/f:extension[@url='http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse']|
Below are a couple of examples of how to use this search parameter.
Search for MedicationRequests for medication use since 1st of January 2010
Search for MedicationDispenses for medication use between 1st of January 2010 and 31st of December 2011
In the XML code of the search parameter, you can see the code (periodofuse), base Resources (MedicationRequest and MedicationDispense), data type (date), the search expression and the comparators that are allowed (eq, le, ge).
<SearchParameter> <url value="http://nictiz.nl/fhir/SearchParameter/Medications-periodofuse" /> <version value="1.0" /> <name value="Medications-periodofuse" /> <status value="draft" /> <date value="2017-11-28T14:26:13.365+00:00" /> <publisher value="Nictiz" /> <contact> <name value="Nictiz" /> <telecom> <system value="email" /> <value value="email@example.com" /> <use value="work" /> </telecom> </contact> <purpose value="To select the MedicationRequest and MedicationDispense resources based on the date/time of the period of use. The period of use is defined in an extension and used in the profiles for the Health and Care Information models (HCIM) Medication Agreement and Administration Agreement." /> <code value="periodofuse" /> <base value="MedicationRequest" /> <base value="MedicationDispense" /> <type value="date" /> <description value="Multiple Resources: * [MedicationRequest](http://hl7.org/fhirmedicationrequest.html): Searches MedicationRequests resources based on the period of use, provided in the value of the 'http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse' extension. * [MedicationDispense](http://hl7.org/fhirmedicationdispense.html): Searches MedicationDispense resources based on the period of use, provided in the value of the 'http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse' extension." /> <expression value="MedicationRequest.extension('http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse') | MedicationDispense.extension('http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse')" /> <xpath value="f:MedicationRequest/f:extension[@url='http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse'] | f:MedicationDispense/f:extension[@url='http://nictiz.nl/fhir/StructureDefinition/zib-Medication-PeriodOfUse']" /> <xpathUsage value="normal" /> <comparator value="eq" /> <comparator value="le" /> <comparator value="ge" /> </SearchParameter>
In this exercise you will run some search requests and define your own search parameter. You may either use a REST client like Postman to run your requests or paste them directly in your browser. Start by reading the case description. Here below are a couple of links that you may find useful during this exercise:
To search for Patients that are part of multiple birth you will need to create a customized search parameter. Before you do so, always check if there's no existing parameter that you can reuse.
Open a XML-editor (or NotePad) and create your own SearchParameter. Hint: take a look at the XML code of the SearchParameter
periodofuse in the Nictiz example above. At least include the following elements: url, name, status, publisher, code, base, type, description and expression.
Here below are some details on adding these elements. Stop reading if you want to try it yourself first. If you wish to learn more about FHIRPath to create expressions, please follow the module on this topic (not yet available) or visit http://hl7.org/fhirpath/
Patient.multipleBirthBoolean | Patient.multipleBirthInteger.exists()
We are always looking for ways to improve our products. The Profiling Academy was built using our own IG-editor in Simplifier. If you have any feedback on this module or on our Profiling Academy in general, please leave a comment in the Issue Tracker of the project.
Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.
Powered by SIMPLIFIER.NET