For those who are only beginning to work with the FHIR standard, many of its aspects sound easy in theory but can be confusing in application. FHIR provides unmatched interoperability possibilities, so in the end, the effort put into understanding and working with it makes everything worthwhile.
In this short FAQ post we’ve gathered the most common issues raised when onboarding new-to-FHIR analysts and developers. We hope it will be useful and clear up some things for you as well.
1. How do the FHIR search parameters work?
Search in FHIR is realized through declarative search, meaning we add specific search parameters to the search string for it to work. There’s no need to change all of the code for the search to work.
Search uses resources from the field ”base” and looks through the fields’ expressions.
Any resource that corresponds to those paths will be returned in response. How the server should run the search is specified in the field type. The Kodjin FHIR Server offers unique functionality that allows you to quickly add new search parameters.
You can read more about different types of search parameters here.
2. What are the different methods of search in FHIR?
The most commonly used search is via the GET verb. This type of search needs to be run through an encryption layer, as it may contain sensitive data in the search parameters.
Example:
curl --location --request GET 'https://{host}/Organization?_id=027af446-ac35-4119-96f8-c2d0d3d7891a' \
--header 'content-type: application/json' \
--data-raw ''Another option is running a search via the POST verb. This method allows you to submit query parameters as a form body.
Example:
curl --location --request POST 'https://{host}/Organization/_search?_id=027af446-ac35-4119-96f8-c2d0d3d7891a'You could also search via Bundle transaction. For example:
curl --location --request POST 'https://{host}' \
--header 'Content-Type: application/json' \
--data-raw '{
"resourceType": "Bundle",
"id": "760f3984-7118-42aa-8b98-cbe158d39acd",
"type": "transaction",
"entry": [
{
"request": {
"method": "GET",
"url": "Organization?_id=68c32231-0587-4148-bd42-cdc8b6d118ac"
}
},
{
"request": {
"method": "GET",
"url": "Patient?_id=126388ba-dd14-4cc9-8669-53c441c1442e"
}
}
]
}'Or search via Bundle batch. For example:
curl --location --request POST 'https://{host}' \
--header 'Content-Type: application/json' \
--data-raw '{
"resourceType": "Bundle",
"id": "760f3984-7118-42aa-8b98-cbe158d39acd",
"type": "batch",
"entry": [
{
"request": {
"method": "GET",
"url": "Organization?_id=68c32231-0587-4148-bd42-cdc8b6d118ac"
}
},
{
"request": {
"method": "GET",
"url": "Patient?_id=126388ba-dd14-4cc9-8669-53c441c1442e"
}
}
]
}'4. What type of search is better to use for string searches?
There are two types of parameters we can use for string searches. One is token, which provides a 100% string match. The other is string, which can be set to strict, not strict, or only the start of the string.Let’s illustrate this with an example. Imagine we have an organization with the name “Memorial Hospital of Veterans.”
{
"resourceType": "Organization",
"id": "d41aaa61-66ba-46b5-9790-eed9706e2f0b",
"name": "Memorial Hospital of Veterans",
"telecom": [
{
"system": "phone",
"value": "(+1) 734-677-7777"
}
],
"address": [
{
"line": [
"3300 Washtenaw Avenue, Suite 227"
],
"city": "Ann Arbor",
"state": "MI",
"postalCode": "48104",
"country": "USA"
}
]
}For organization.name with the search parameter type: token, we can search it, but only in one way:
```
GET/ {{host}}/fhir/Organization?name=Memorial Hospital of Veterans
```With the search parameter type: string, we can search the same organization with all prefixes that use the string type in FHIR.
```
GET/ {{host}}/fhir/Organization?name=Name
GET/ {{host}}/fhir/Organization?name:contains=of
GET/ {{host}}/fhir/Organization?name:exact=Name of Organization
```Here’s how the token search parameter and string search parameter would work inside the Kodjin FHIR Server.
5. How do I search with _include and _revinclude?
We can use _include and _revinclude to include in the search parameter any resource we reference or that references us. You can find a list of all the search parameters in FHIR here.
We’ll illustrate it with the Patient and Coverage resources.
Let’s search Coverage by patient.
Example with _include:
`/Coverage?patient=Patient/{id}&_include=Coverage:patient`In response, the direct match will return:
"search": {
"mode": "match"
}And match _include and _revinclude:
"search": {
"mode": "include"
}For another example, let’s search Patient with the _id parameter.
Example with _revinclude:
`/Patient?_id={{fhir_patient_id}}&_revinclude=Condition:patient`Or we can _revinclude (as well as _include) several resources:
`/Patient?_id={{fhir_patient_id}}&_revinclude=Coverage:patient&_revinclude=Observation:patient`6. The search parameter does not work, and I see more data in the results than necessary.
If a search parameter is not available in FHIR, it’s ignored. As a result, you may see more results than necessary. In order to check whether a parameter exists, you need to add a header, and then FHIR will return the error if the parameter doesn’t exist. Headers are available for those parameters that are not set.
The header will look like this:
prefer: handling=strict.7. Can I search two fields at once?
Yes, we use a composite search parameter to search by two parameters. It’s rarely used, and more often the question is how to create this parameter.
We will demonstrate with the Observation search parameter. In order to create a search parameter that consists of two others, first we need to create two separate search parameters: Observation-combo-code and Observation-combo-value-quantity.
Then, in the field “component,” we mention these two parameters:
"component": [
{
"definition": "http://hl7.org/fhir/SearchParameter/Observation-combo-code",
"expression": "code"
},
{
"definition": "http://hl7.org/fhir/SearchParameter/Observation-combo-value-quantity",
"expression": "value.as(Quantity)"
}
],For the expression, we mention the parent element for both search parameters in the component. For expressions in the component, we use the remaining fhirpath.
When searching by this search parameter, we mention both values divided by “$.”
/Observation?component-code-value-quantity=http://loinc.org|8480-6$lt608. Can I search by logical reference?
Yes. When a reference is an identifier, we can use the type reference as well as the type token to search it. The difference will be in the search parameter and in the request we should send to FHIR. For example:
9. Do I always need to add a search parameter for a new resource?
No. Some search parameters are used for all resources.
For example: _id, _lastUpdated, _profile, _sort, _after, _count, _include, _revinclude.
So, if a new resource was added, and you need to run an _id search, there’s no need to create a new parameter, for example.
FHIR Search options, realized in the Kodjin FHIR Server
The Kodjin FHIR Server (a part of Kodjin’s Interoperability Suite) is a scalable solution for storing and processing healthcare data through a FHIR-compliant RESTful API.
We have implemented two types of search pagination in the Kodjin Server, which can be changed using different values in the header. This doesn’t require you to manually change the code itself; as a result, it makes our solution universal and flexible. If you want a demo, let us know.
Conclusion
The search functionality in FHIR was designed in such a way as to support both simple and complex queries depending on the data needed. We hope our FAQ guide helped you solve some of the issues you may have encountered when working with FHIR search.
If you are interested in delving deeper into FHIR, perhaps setting up your own FHIR server or making your data FHIR-compliant, our engineers and analysts are ready to help. Schedule a free consultation with our team.
Written by
Sveta Vedmed
Business Analyst at Edenlab
