Selectable search parameters

Searching for resources is fundamental to the FHIR® service. Each resource in the FHIR service carries information as a set of elements. Search parameters work to query the information in these elements. When you deploy the FHIR service, it enables inbuilt search parameters by default. The FHIR service performs efficient searches by extracting and indexing specific properties from FHIR resources during the ingestion of data.

Selectable search parameters help you query FHIR® resources more efficiently in Azure Health Data Services. This article explains how to enable or disable inbuilt search parameters to save storage space and improve search performance.

To perform status updates on search parameters, follow these steps:

1. Get the status of search parameters.
2. Update the status of search parameters.
3. Execute a reindex job.

In this article, the example API calls demonstrate FHIR search syntax by using the {{FHIR_URL}} placeholder to represent the FHIR server URL.

Get the status of search parameters

An API endpoint ($status) is available to view the status of search parameters. The response includes four statuses:

To get the status across all search parameters, use the following request. It returns a list of all the search parameters and their status. Scroll through the list to find the search parameter you need.

GET {{FHIR_URL}}/SearchParameter/$status

To identify the status of individual or a subset of search parameters, use the following filters.

• Name. To identify search parameter status by name, use this request.

   GET {{FHIR_URL}}/SearchParameter/$status?code=<name of search parameter/ sub string>

• URL. To identify search parameter status by its canonical identifier, use this request.

GET {{FHIR_URL}}/SearchParameter/$status?url=<SearchParameter url>

• Resource type. In FHIR, you enable search parameters at the individual resource level to allow filtering and retrieving of a specific subset of resources. To identify the status of all the search parameters mapped to a resource, use this request.

GET {{FHIR_URL}}/SearchParameter/$status?resourcetype=<ResourceType name>

In response to the GET request to $status endpoint, the parameters resource type is returned with the status of the search parameter. Here's an example response.

{
  "resourceType" : "Parameters",
  "parameter" : [
    "name" : "searchParameterStatus",
    "part" : {
        {
        "name" : "url",
        "valueString" : "http://hl7.org/fhir/SearchParameter/Account-identifier"
        },
        {
        "name" : "status",
        "valueString" : "supported"
        }
    }
  ]
}

Update the status of search parameters

After you get the status of search parameters, update the status to Supported or Disabled.

You can update the search parameter status for a single search parameter or in bulk.

Update a single search parameter status

To update the status of a single search parameter, use the following API request.

PUT {{FHIR_URL}}/SearchParameter/$status
{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "searchParameterStatus",
            "part": [
                {
                    "name": "url",
                    "valueUrl": "http://hl7.org/fhir/SearchParameter/Resource-test-id"
                },
                {
                    "name": "status",
                    "valueString": "Supported"
                }
            ]
        }
    ]
}

Depending on your use case, keep the status state value as either Supported or Disabled for a search parameter. When you send the state Disabled in the request, the response returns as PendingDisable because a reindex job must run to fully remove associations.

If you receive a 400 HTTP status code in the response, it means there's no unique match for the identified search parameter. Check the search parameter ID.

Update search parameter status in bulk

To update the status of search parameters in bulk, include the Parameters resource list in the request body of the PUT request. The list needs to contain the individual search parameters that you want to update.

PUT {{FHIR_URL}}/SearchParameter/$status
{
  "resourceType" : "Parameters",
  "parameter" : [
    {
     "name" : "searchParameterStatus",
     "part" :[
			{
				"name" : "url",
				"valueString" : "http://hl7.org/fhir/SearchParameter/Endpoint-name"
			},
			{ 
				"name" : "status",
				"valueString" : "Supported"
			}
		]
    },
	{
     "name" : "searchParameterStatus",
     "part" :[
		 {
			"name" : "url",
			"valueString" : "http://hl7.org/fhir/SearchParameter/HealthcareService-name"
		 },
		 { 
			"name" : "status",
			"valueString" : "Supported"
		 }
	 ]
    },
    ...
  ]
}

Execute a reindex job

After you update the search parameter status to Supported or Disabled, the next step is to execute a reindex job.

Until the search parameter is indexed, the Enabled and Disabled status of the search parameters aren't activated. Reindex job execution updates the status from Supported to Enabled or PendingDisable to Disabled.

A reindex job can be executed against the entire FHIR service database or against specific search parameters. A reindex job can be performance intensive. For more information, see Run a reindex job.

Frequently asked questions

What is the behavior if the query includes a search parameter with status 'Supported'?

The search parameter in the 'Supported' state needs to be reindexed. Until then, the search parameter isn't activated. If a query is executed on a non-active search parameter, the FHIR service renders a response without considering that search parameter. In the response, there is a warning message indicating that the search parameter wasn't indexed and not used in the query. To render an error in such situations, use the 'Prefer: handling' header with the value 'strict'. By setting this header, warnings are reported as errors.

Next steps

Define custom search parameters