Defining custom search parameters for Azure API for FHIR

The Fast Healthcare Interoperability Resources (FHIR®) specification defines a set of search parameters for all resources and search parameters that are specific to a resource. However, there are scenarios where you might want to search against an element in a resource that isn’t defined as a standard search parameter by the FHIR specification. This article describes how you can define your own search parameters to be used in the Azure API for FHIR.

Create new search parameter

To create a new search parameter, you POST the SearchParameter resource to the database. The following code example shows how to add the US Core Race SearchParameter to the Patient resource.

POST {{FHIR_URL}}/SearchParameter

{
  "resourceType" : "SearchParameter",
  "id" : "us-core-race",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "Returns patients with a race extension matching the specified code.",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

Important elements of a SearchParameter include the following.

• url: A unique key to describe the search parameter. Many organizations, such as HL7, use a standard URL format for the search parameters that they define, as previously shown in the US Core race search parameter.

• code: The value stored in code is what you use when searching. For the preceding example, you would search with GET {FHIR_URL}/Patient?race=<code> to get all patients of a specific race. The code must be unique for the resource the search parameter applies to.

• base: Describes which resource the search parameter applies to. If the search parameter applies to all resources, you can use Resource; otherwise, you can list all the relevant resources.

• type: Describes the data type for the search parameter. Type is limited by the support for the Azure API for FHIR. This means that you can’t define a search parameter of type Special or define a composite search parameter unless it's a supported combination.

• expression: Describes how to calculate the value for the search. When describing a search parameter, you must include the expression, even though it isn't required by the specification. This is because you need either the expression or the xpath syntax, and the Azure API for FHIR ignores the xpath syntax.

Test search parameters

While you can’t use the search parameters in production until you run a reindex job, you can test your search parameters before reindexing the entire database.

First, you can test your new search parameter to see what values are returned. By running the following command against a specific resource instance (by inputting their ID), you get a list of value pairs with the search parameter name and the value stored for the specific patient. This includes all of the search parameters for the resource. You can scroll through the returned list to find the search parameter you created. Running this command won't change any behavior in your FHIR server.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOUCE_ID}}/$reindex

For example, to find all search parameters for a patient, use the following.

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

The result looks like the following.

{
  "resourceType": "Parameters",
  "id": "8be24e78-b333-49da-a861-523491c3437a",
  "meta": {
    "versionId": "1"
  },
  "parameter": [
    {
      "name": "deceased",
      "valueString": "http://hl7.org/fhir/special-values|false"
    },
    {
      "name": "language",
      "valueString": "urn:ietf:bcp:47|en-US"
    },
    {
      "name": "race",
      "valueString": "2028-9"
    },
...

Once you see that your search parameter is displaying as expected, you can reindex a single resource to test searching with the element. First you reindex a single resource:

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

Running this sets the indices for any search parameters for the specific resource that you defined for that resource type. This does make an update to the FHIR server. Now you can search and set the use partial indices header to true, which means that it returns results where any of the resources which have the search parameter indexed, even if not all resources of that type have it indexed.

Continuing with our example, you could index one patient to enable the US Core Race SearchParameter as follows.

POST https://{{FHIR_URL}/Patient/{{PATIENT_ID}}/$reindex

Then search for patients that have a specific race:

GET https://{{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

After you're satisfied that your search parameter is working as expected, run or schedule your reindex job so the search parameters can be used in the FHIR server for production use cases.

Update a search parameter

To update a search parameter, use PUT to create a new version of the search parameter. You must include the SearchParameter ID in the id element of the body of the PUT request and in the PUT call.

PUT {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

{
  "resourceType" : "SearchParameter",
  "id" : "SearchParameter ID",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "New Description!",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

The result is an updated SearchParameter and the version increments.

Delete a search parameter

If you need to delete a search parameter, use the following.

Delete {{FHIR_URL}}/SearchParameter/{SearchParameter ID}

Next steps

In this article, you learned how to create a search parameter. Next you can learn how to reindex your FHIR server.