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 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:
_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
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.
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/ |
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.
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 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
This set of parameters works for all Resource types. In this section we will explain a couple of them:
_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
._lastUpdated
parameter can be used to search for Resources that are updated after a certain Date._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._profile
parameter 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.
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 |
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.
Format URL | http://hl7.org/fhir/SearchParameter/us-core-Patient-race |
Status |
Returns patients with a race extension matching the specified code.
[base]/Patient?race=[system]|[value]
Resource | Name | Type | Paths |
Patient | race | token | f:Patient/f:extension[@url='http://hl7.org/fhir/StructureDefinition/us-core-race'] |
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.
Below are a couple of examples of how to use this search parameter.
Search for MedicationRequests for medication use since 1st of January 2010
https://vonk.test-nictiz.nl/MedicationRequest?periodofuse=ge2010-01-01
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).
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.
Most modules end with an exercise. Use Forge to start profiling yourself. Just contact us at simplifier@fire.ly if you need any help.
Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.
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.
Powered by SIMPLIFIER.NET