Search operations and parameters

Introduction

In this module you will learn more about search operations and search parameters. In the exercise we will run queries on our own Vonk server. The end-point of this server is http://vonk.fire.ly

The topics covered in this module are:

• Search operations
• Search parameters
• Customized search parameters
• Running your own search requests

Reading material

1. Search operations

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:

GET [base]/[type]?name=value&...{&_format=[mime-type]}}

The different parts of this operation are explained below:

• base - a link to a FHIR server to perform the search upon
• type - the name of the Resource type that is searched upon
• name - the name of a search parameter that applies to the selected Resource
• value - the value that you want to search upon (for example if you want to search for all female patients, the search parameter would be gender and the value to search upon would be female
• format - only used if you want to specify the format of the output (for example if you want the output to be formatted in JSON, you would write _format=json)

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.

Example 1

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.

GET https://vonk.fire.ly/Patient

Example 2

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 James from the Vonk server.

GET https://vonk.fire.ly/Patient?name=James

Example 3

You can add more than one search parameter by using the & character. In this example, we use the search parameters family and given to search for Patients named James Chalmers (given=James and family=Chalmers). We also include the _format parameter to get the output in JSON format. Run this example to get all Patients named James Chalmers from the Vonk server in JSON format.

GET https://vonk.fire.ly/Patient?family=Chalmers&given=James&_format=JSON

2. Search parameters

Each Resource can be searched by a couple of common parameters (e.g. _id, _lastUpdated and _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.

2.1 Search parameter types

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:

GET [base]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31

These are the defined search parameter types

2.1.1 Modifiers

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.

Example

Suppose you have three Patients in your database, one named James, one named Carola and one named Jim. You run the following search requests:

GET https://vonk.fire.ly/Patient?name:contains=Caro

GET https://vonk.fire.ly/Patient?name:exact=Caro

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.

2.1.2 Prefixes

For the parameter types of number, date, and 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:

Examples

Get all appointments that start after or on January 1st 2018 and until and including February 15th 2019

GET https://vonk.fire.ly/Appointment?date=ge2018-01-01&date=le2018-02-15

or

GET https://vonk.fire.ly/Appointment?date=gt2017-12-31&date=lt2018-02-16

More details about the prefixes, including extensive examples, can be found on the FHIR specification search spec

2.2 Parameters for all resources

This set of parameters works for all Resource types. In this section we will explain a couple of them:

1. The _id parameter 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 [base]/[type]?logical_id rather then [base]/[type]?_id=logical_id.
2. The _lastUpdated parameter can be used to search for Resources that are updated after a certain Date.
3. The _tag, _profile and _security parameters search on the equivalent parameters in the meta element. For example, tags could be used to mark that a Resource should still be reviewed.
4. The _profile parameter can be used to restrict the search to instances of a specific profile only.

2.3 Search result parameters

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.

3. Custom search parameters

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.

[base]/Patient?race=[system]|[value]

4. Running your own search requests

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.

Real-life examples

Here below is an examples of a customer that we helped building profiles.

Nictiz

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.

Below are a couple of examples of how to use this search parameter.

1. Search for MedicationRequests for medication use since 1st of January 2010

   https://vonk.test-nictiz.nl/MedicationRequest?periodofuse=ge2010-01-01

2. Search for MedicationDispenses for medication use between 1st of January 2010 and 31st of December 2011

   https://vonk.test-nictiz.nl/MedicationDispense?periodofuse=ge2010-01-01&periodofuse=le2011-12-31

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).

Exercise

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:

• FHIR search framework: https://www.hl7.org/fhir/search.html
• FHIR resource list: https://www.hl7.org/fhir/searchparameter-registry.html
• FHIRPath: http://hl7.org/fhirpath/
• Link to download Postman: https://www.getpostman.com/

Case description
Hospital X wants to receive patient data from general practitioners. The hospital has decided to build conform the FHIR standard, starting with administrative data of patients and their general practitioner. The hospital wants to be able to search for Patients on:
• Name
• Date of birth
• Gender
• Multiple birth
The hospital asks you to give some examples of how they can search on these parameters.

Steps to follow

1. Examples of search requests

1. Search for Patients named Jim Chalmers on the public Vonk server.
2. Search for Patients that are 18 years or older.
3. Search for Patients born in 1975.
4. Search for female Patients. Also search for Patients that are not male. Do the numbers match? Can you explain this?

2. Customized search parameter

1. 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.

2. 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/

   • url - provide the end-point of your search parameter, note that it should end with the name of your search parameter, e.g. http://hl7.org/fhir/SearchParameter/Patient-multiplebirth
   • name - provide a name for your search parameter, it is good practice to start it with the name of the base Resource followed by the code of the parameter e.g. Patient-multiplebirth
   • status - just keep it on draft for now
   • publisher - you can put your own name here
   • code - provide the code of your search parameter, this is the code that you will need to use the parameter in a search request, e.g. multiplebirth
   • base - provide the base Resource(s) that support(s) your search parameter, in this case Patient
   • type - provide the data type of your search parameter, for a Boolean you can use a token
   • description - provide a short description in natural language
   • expression - provide the expression used to extract the value from a Resource to define if it is a match or not, in this case you could use the expression Patient.multipleBirthBoolean | Patient.multipleBirthInteger.exists()

Feedback

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.

Get in touch

Start profiling

Most modules end with an exercise. Use Forge to start profiling yourself. Just contact us at simplifier@fire.ly if you need any help.

Learn more

Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.

Need help or advice?

Let us assist you with your FHIR use case. Visit our company website to know more about our services or get into contact with Rien Wertheim right away.