Creating a SearchParameter in FHIR

In SQL we can write any search query we want to write.

In FHIR, not so much. We’re restricted by a resource’s predefined Search Parameters. This is a problem every real-world FHIR project faces at some point.

Most significant elements of a resource are searchable. But who defines significant? What’s significant to you and to your use case might not be significant to the wider FHIR community.

Let’s say you want to pull up a list of MedicationStatements for a Patient in a given year.

The patient has a varied assortment of medical issues. You only want MedicationStatements connected to a certain Condition, as referenced in the reasonReference element.

You can build a query that filters by Patient, because MedicationStatement.patient is a search parameter.

You can filter by effective date, because MedicationStatement.effective is a search parameter.

But you can’t filter by Condition, because MedicationStatement.reasonReference is NOT a search parameter.

So you end up writing a query that returns too many results which you then filter in code. Far from ideal.

The solution is to create a custom search parameter. Here’s how:

– Create a SearchParameter resource with a unique name and url
– Set base = MedicationStatement
– Set target = Condition
– Set expression = “MedicationStatement.reasonReference”
– POST the resource to your FHIR server
– Where necessary, trigger a re-index of the underlying database

Of course, this assumes that you or someone on your team has the access rights to create a SearchParameter resource to begin with.

It assumes your FHIR server can handle the creation of custom SearchParameters.

And it assumes that you can trigger a re-indexing of the underlying database — the mechanism to do this differs by FHIR server provider.

Lots of assumptions.

SearchParameter resource:

JSON example:



Sign up to “The Tuesday FHIR Sessions” and receive an email every Tuesday where I go deep on a single FHIR topic.