by: Amos Kippi Bordowitz; Posted: 9-Nov-2023

If you haven’t done so yet, we recommend you first read our post on search in FHIR.

In the dynamic world of FHIR®, efficient data retrieval is paramount. One of the key tools at our disposal is the SearchParameter resource. SearchParameters are defined in the FHIR specification and can be used to search for any resource in FHIR. Each resource has its own set of SearchParameters, which are specific to the data that the resource contains. In addition, every FHIR server should include, as part of its CapabilityStatement resource, what SearchParameters it supports.

Custom SearchParameters are SearchParameter resources that are created by users to extend the functionality of the FHIR search functionality. They can be used to search for resources based on criteria that is not supported by the standard FHIR search parameters.

Why are custom SearchParameters important?

There are obvsouly many reasons that custom SearchParameters in FHIR could be useful and important. We will name a few here:

1. Specificity: Custom search parameters enable the definition of domain-specific criteria that standard parameters may not cover. This allows for more targeted and precise searches.
2. Data Modeling: They make it easier to extend FHIR resources to gather more information unique to a use case or implementation. The variety of data models found in various healthcare scenarios is reflected in the custom search parameters.
3. Interoperability: Organizations can ensure that data can be efficiently queried and exchanged between systems, improving interoperability, by tailoring search parameters to match their unique data structures with FHIR resources.
4. Workflow Support: Custom parameters can be created to support specific workflow requirements, improving the ability to filter and retrieve relevant data based on the specific requirements of healthcare processes and applications.
5. Compliance: Custom search parameters can be designed to align with regulatory or organizational requirements, ensuring that the information critical to compliance is readily accessible through standardized queries.

Understanding SearchParameters

At its core, a SearchParameter defines a set of criteria that can be used to query resources in a FHIR server. It serves as a bridge between clients seeking specific information and servers capable of delivering it. Let's break down its essential components:

• code: Describes what the search parameter represents, often aligned with standard FHIR resource elements.
• type: Specifies the resource type to which the search parameter applies.
• expression: Defines the expression used to extract the value from the resource.
• target: Indicates which part of the resource the search parameter targets.
• comparator: Enables comparisons like equals, not equals, etc.
• modifier: Modifies the search behavior, for instance, case-sensitive matching.

Let’s look at some practical examples of a couple of custom SearchParameters. We will see the JSON of each one and some useful examples of queries that make use of them.

Name based queries

Here's a basic example of a SearchParameter for searching patients by name:

  Usage examples:

• GET [base]/Patient?name=John - Retrieve patients with the exact name "John."
• GET [base]/Patient?name:contains=doe - Discover patients with names containing "doe."
• GET [base]/Patient?name:missing=true - Identify records where the patient name is missing.

Let's consider a scenario where a healthcare provider needs to retrieve a list of patients with a specific condition. Using a SearchParameter, the client can craft a targeted query like:

GET [base]/Patient?condition=1234

This simple query instructs the FHIR server to return all patients associated with the given condition.

Temporal Queries for Observations

Navigating temporal dimensions to locate observations within specific date ranges. Note that this SearchParmeter is a standard one. We peek under the hood to understand the nuts and bolts of how it would be created if it hadn't existed.

Usage examples:

GET [base]/Observation?date=2023-01-01 - Retrieve observations on January 1, 2023.

GET [base]/Observation?date:gt=2022-01-01 - Fetch observations after January 1, 2022.

GET [base]/Observation?date:missing=false - Identify observations with recorded dates.

Comparators

That last SearchParmeter has a number of comparators we can explore. Let’s see a few more queries cases that make use of them.

1. Equal (eq):

Search for observations with an effective date equal to a specific date.

GET [base]/Observation?date=eq2023-01-15

2. Not Equal (ne):

Search for observations with an effective date not equal to a specific date.

GET [base]/Observation?date=ne2023-01-15

3. Greater Than (gt):

Search for observations with an effective date greater than a specific date.

GET [base]/Observation?date=gt2023-01-15

4. Less Than (lt):

Search for observations with an effective date less than a specific date.

GET [base]/Observation?date=lt2023-01-15

5. Greater Than or Equal (ge):

Search for observations with an effective date greater than or equal to a specific date.

GET [base]/Observation?date=ge2023-01-15

6. Less Than or Equal (le):

Search for observations with an effective date less than or equal to a specific date.

GET [base]/Observation?date=le2023-01-15

Modifiers

Finally, let’s see a couple of examples of the modifier in the same SearchParameter:

Search for observations where the effective date is missing.

GET [base]/Observation?date:missing=true

Search for observations where the effective date is not missing.

GET [base]/Observation?date:missing=false

Naturally, these are only a handful of examples, and there are many more options to examine. For more information on SearchParameters and on the search capabilities in FHIR, please visit the FHIR search page. Before creating your own custom SearchParameters. Make sure to visit the SearchParameter registry, as well as the SearchParmeter profiles page, as what you want to create might already be part of the standard!

In conclusion

Custom SearchParameters are another way that the FHIR® standard allows organizations to customize the abilities to make use of the profiles in the organization. They should be considered a natural part of the profiling process.