Searching by System and Value

Some fields in FHIR, such as identifiers, codeable concepts and coded values, include both a system and a code. To query this effectively, FHIR provides options to search using both parts together.

In this tutorial we will look at,

• Searching by code
• Searching by system
• Searching by system and code together
• URL encoding for queries

Searching by code

The simplest case, is to search by code value directly.

For example, to find all Observation resources that record heart rate by its LOINC code, 8867-4, the search query will look like this,

GET /Observation?code=8867-4

This returns only Observations where the Observation.code.coding.code is 8867-4.

More generally, this can be written as,

GET /Observation?code={code}

where {code} must be replaced by the code you wish to search for.

Searching by system

It is also possible to fetch all resources that use a particular coding system, regardless of which code is chosen. For examle, to return all Observations coded in LOINC:

GET /Observation?code=http://loinc.org|

Note the | pipe character placed after the URL to indicate that it is a system.

This query retrieves all Observations that have LOINC codes.

A user executes: GET /Observation?code=8867-4. Which of these is a risk with this query?

• It won't return anything unless the code is in SNOMED CT.
• It may return Observations using 8867-4 from non-LOINC systems.
• It will only match if the Observation has no system defined.
• It’s invalid unless the system is also included.

Submit

Searching by system and code

For precise searches, it is possible to combine both system and code. This avoids ambiguity in cases if the same code is reused across different coding systems.

The general format used is system|code.

For ecample, to search for Observations that have the LOINC code 8867-4 for Heart Rate,

GET /Observation?code=http://loinc.org|8867-4

URL encoding for queries

While making queries directly in a browser, or in code that doesn’t automatically encode parameters, special characters like : and | must be URL encoded.

Here are some examples of the encoding key,

• space(” ”): %20
• colon(”:”): %3A
• forward slash(”/”): %2F

For example, this is the query before encoding,

GET /Observation?code=http://loinc.org|8867-4

And this is the full encoded query,

GET /Observation?code=http%3A%2F%2Floinc.org%7C8667-4

Most FHIR client libraries and tools like Postman take care of encoding automatically. However, in case you run into errors, you can manually encode the URL.

You run this query: GET /Observation?code=http://loinc.org|. What kind of match will this return?

• Only Observations where the code equals 'http://loinc.org'.
• Observations that have any system but a code of 'http://loinc.org'.
• Only Observations where the code is 8867-4 and the system is LOINC.
• Observations with any LOINC-coded value, regardless of the actual code.

Submit

Custom Search Parameters

FHIR has built-in search parameters, but sometimes that is not enough for your use case. For example, searching patients by phone number works as an exact match. If you want partial phone number search, you may need to create a custom search parameter.

In FHIR, SearchParameter is itself a resource. That means you can define a new search by specifying things like:

• the code used in the URL
• the resource it applies to, such as Patient
• the type of search, such as string or token
• the expression that tells the server what part of the resource to search

Creating a custom search parameter does not always mean the server will use it immediately. All FHIR servers may not fully support indexing or searching on custom parameters in the same way.

Summary

In this lesson, we learnt to query system and code values in FHIR, exploring code-only, system-only and combined system+code searches. Additionally, we looked at URL encoding when working with special characters in queries.

These techniques are demonstrated using the Observation resource but are applicable to others including Patient.identifier and Condition.code.