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 http://vonk.furore.com/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 Caro from the Vonk server.

GET http://vonk.furore.com/Patient?name=Caro

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

GET http://vonk.furore.com/Patient?family=Emerald&given=Caro&_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

type description example
number Search parameter SHALL be a number (a whole number, or a decimal). length=27
date Search parameter is on a date/time. The date format is the standard XML format. birthdate=1964-12-10
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. name=John
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 "|", depending on the modifier used. gender=http://hl7.org/fhir/v3/AdministrativeGender|female
reference A reference to another resource. subject:Patient=23
composite A composite search parameter that combines a search on two values together. state-on-date=new$2013-05-04
quantity A search parameter that searches on a quantity. value=5.4|http://unitsofmeasure.org|mg
uri A search parameter that searches on a URI (RFC 3986). uri=http://acme.org/fhir/
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 Caro, one named Carola and one named Jim. You run the following search requests:

GET http://vonk.furore.com/Patient?name:contains=Caro

GET http://vonk.furore.com/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:

prefix 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
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

Examples

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

GET http://vonk.furore.com/Appointment?date=ge2018-01-01&date=le2018-02-15

or

GET http://vonk.furore.com/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.

name description allowable content example
_sort Order to sort results in (can repeat for inner sort orders) Name of a valid search parameter _sort=date
_count Number of results per page Whole number _count=50
_include Other resources to include in the search results that search matches point to SourceType:searchParam(:targetType) _include=Patient:general-practitioner
_revinclude Other resources to include in the search results when they refer to search matches SourceType:searchParam(:targetType) _revinclude=Provenance:target
_summary Just return the summary elements (for resources where this is defined) true | false (false is default) _summary=true
_contained Whether to return resources contained in other resources in the search matches true | false | both (false is default) _contained = true
_containedType If returning contained resources, whether to return the contained or container resources container | contained containedType = container
_elements return a specific set of elements as part of a resource Name of resource elements _elements=identifier,active,link

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.

SearchParameter 'USCoreRace'

Canonical URLhttp://hl7.org/fhir/us/core/SearchParameter/us-core-race
Published byUS Realm Steering Committee
StatusDraft (since 2016-12-22)

Returns patients with a race extension matching the specified code.

Contact Information

Other: http://www.healthit.gov/

Invocations

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

Details

ResourceCodeTypeFhirPathXpath (Normal)
Patientracetokenf:Patient/f:extension[@url='http://hl7.org/fhir/us/core/StructureDefinition/us-core-race']/f:extension[@url='ombCategory' or @url='detailed']

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.

SearchParameter 'Medications-periodofuse'

Canonical URLhttp://nictiz.nl/fhir/SearchParameter/Medications-periodofuse
Version1.0
Published byNictiz
StatusDraft (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.

Purpose

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.

Contact Information

Nictiz
Email: info@nictiz.nl

Invocations

[base]/MedicationRequest?periodofuse=(comparator)[date]

[base]/MedicationDispense?periodofuse=(comparator)[date]

Details

ResourceCodeTypeFhirPathXpath (Normal)
MedicationRequest, MedicationDispenseperiodofusedateMedicationRequest.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.

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

<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="info@nictiz.nl" />
            <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>


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:

    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.