On this page:

5.9Search Parameters

 

An important concept for setting up a FHIR repository is defining the search parameters that will be indexed and made available for searching by the system.

5.9.1Search Parameter Concepts

 

Search parameters are essentially named paths within resources that are indexed by the system so that they can be used to find resources that match a given criteria.

For example, the FHIR specification defines the gender search parameter on the Patient resource, giving it a path of Patient.gender. This means that every time a new Patient resource is created – or an existing one is updated – the value found at the path Patient.gender will be indexed. Clients may then use a URL search parameter named gender to find resources with a given gender.

Once these parameters have been defined in your database, clients can use them to find matching resources:

GET [base]/Patient?gender=male

5.9.2Default Search Parameters

 

The FHIR specification defines a set of built-in parameters that are wide ranging and broadly useful. For example, the FHIR definition for the Patient resource contains search parameters such as:

  • name (Search for patient by name)
  • birthdate (Search for patient by date of birth)
  • identifier (Search for patient by identifier)

For a general purpose repository, using the default search parameters is useful since these parameters represent a wide variety of use cases. Additionally, using the default parameters is good for interoperability since clients may expect standard parameters to be supported across different servers.

However, it is often useful to customize the supported search parameters. For example:

  • You may wish to add additional search parameters that will index fields that do not have a standard search parameter defined.
  • You may wish to add additional search parameters that will index extensions used by your clients.
  • You may wish to disable search parameters that are not used in order to improve performance and conserve space (disabling unnecessary search parameters can have a dramatic impact on write performance in some cases).

5.9.3Managing Search Parameters

 
Modifying search parameters requires the FHIR_MODIFY_SEARCH_PARAMETERS permission.

In a relational FHIR Storage module, each search parameter is represented by a SearchParameter resource in the database. When Smile CDR starts for the first time, the database will be preseeded with search parameter resources that correspond to the various default parameters.

If you want to customize the available search parameters, there are several ways to do so.

Using the Web Admin Console

To configure search parameters in the Web Admin Console, log into the console then select "Config Search Parameters".

You will be presented with a list of all available search parameters. You can create new ones, update existing ones, and disable ones you do not need.

Using the FHIR Endpoint

A new search parameter can also be created by simply uploading an appropriate SearchParameter resource. This is same process used to upload any other type of resource.

For example, POSTing the following resource to a server that supports custom search parameters will create a new search parameter on the Patient resource named eyecolour.

{
	"resourceType": "SearchParameter",
	"title": "Eye Colour",
	"base": [ "Patient" ],
	"status": "active",
	"code": "eyecolour",
	"type": "token",
	"expression": "Patient.extension('http://acme.org/eyecolour')",
	"xpathUsage": "normal"
}

5.9.4Search Parameter Statistics

 
The system gathers statistical information about search parameters using an algorithm that facilitates speedy collection; however, it is not always accurate or immediately up-to-date. Do not rely on these statistical values for any absolute calculations.

Smile CDR gathers statistics at runtime about the actual values indexed by a search parameter for resources in the database and the use of that search parameter by clients.

The following statistics are gathered:

  • Count: Refers to the total number of paths that are indexed by this parameter.
  • Resource Spread: Refers to the number of resources that contain values indexed by this parameter. A parameter with a low resource spread will only match a smaller number of resources, whereas a parameter with a high resource spread could potentially match a larger number.
  • Value Spread: Refers to the number of unique values indexed by this parameter. A parameter that matches a field bound to a ValueSet with a small number of codes (e.g. Patient.gender) will have a low value spread. A parameter that can contain many different values (e.g. Observation.value) could have a much higher value spread.
  • Last Used: Refers to how recently the parameter was actually used as a part of a search for resources.

5.9.5Filter Search Parameter

 

Smile CDR can be configured to enable the FHIR _filter search parameter, using the filter_search.enabled property.

The filter search parameter is extremely powerful, as it allows a level of expressiveness in searches that is not possible with standard REST URL search parameters. It also potentially allows clients to perform searches for which no appropriate database indexes exist, making it a potentially dangerous operation for public servers. As such it is disabled by default.

Users of the Filter Search Parameter are advised to examine the generated SQL (e.g. by enabling Performance Tracing and then examining the Transaction Log) and ensuring that the database has indexes to appropriately support the queries being performed.

5.9.6Manual Reindexing

 
This method requires the ROLE_FHIR_CLIENT_SUPERUSER permission.

It is possible to trigger a manual reindexing of data in the repository. This is generally done for one of the following reasons:

  • In cases where Search Parameters have been changed in some way and the Mark Resources for Reindexing After SearchParameter Change property is not enabled, a reindex may be required in order to force data that was created prior to SearchParameter changes to be indexed. This setting is disabled by default. When reindexing because of a SearchParameter change, it is a good idea to include the type parameter shown below.

  • If Enforce Referential Integrity on Write is not enabled, it is possible to create resources with references that are not valid at the time that the resource is created. In that case, the reference will not be indexed even if the target resource is later created. A manual reindex is then required in order to correct this.

5.9.7$reindex Operation (since 2021.08)

 

The $reindex operation has similar syntax to the $delete-expunge operation and offers more fine-grained control over the reindex operation over the legacy $mark-all-resources-for-reindexing operation. The $reindex operation can be called in one of two ways, either with a list of urls to be reindexed or with everything=true. If everything=true then the urls parameter is ignored and all resources will be reindexed. Otherwise, only the resources matching the urls are reindexed.

Parameters

  • urls(optional) If supplied, an ordered list of resource search urls to be reindexed.
  • everything(optional) If set to true the urls parameter is ignored and all resource types are reindexed.
  • batchSize(optional) If not supplied, defaults to the Reindex Batch Size configured on the Persistence module. This batch size determines how many resources are read at a time and submitted to the reindex processor for reindexing.

Here is the step-by-step process for how batchSize and threadCount interact with reindex processing:

  • The $reindex batchSize parameter determines how many resource ids are loaded at a time when searching for resources to reindex. These are loaded in a single thread, one batch at a time, similar to how a _count parameter determines how many resources are returned by a FHIR search.
  • Once we have a batchSize group of resources to be reindexed, they are passed to the reindex processor. The reindex processor chunks this batch up based on the "Reindex Batch Size" and "Reindex Thread Count" values configured on the Persistence Module and reindexes those chunks in parallel across those threads.

For example, if the $reindex batchSize is 1000, the Persistence Reindex Batch Size is 200 and the Persistence Reindex Thread Count is 4, then 1000 resources will passed to the Reindex Processor at a time. The reindex Processor will then split them into 5 chunks of 200 and process the chunks in parallel in 4 threads. When the first thread completes, it will start processing the final chunk of 200.

Examples

To reindex a specific set of URLs in order, call:

POST /$reindex
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "url",
    "valueString": "Patient?active=true"
  }, {
    "name": "url",
    "valueString": "Observation?subject.active=true"
  }, {
    "name": "batchSize",
    "valueDecimal": 1000
  } ]
}

To reindex all Practitioner and all Patient resources, call:

POST /$reindex
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "url",
    "valueString": "Practitioner?"
  }, {
    "name": "url",
    "valueString": "Patient?"
  }, {
    "name": "batchSize",
    "valueDecimal": 1000
  } ]
}

To reindex all resources call:

POST /$reindex
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "everything",
    "valueBoolean": "true"
  }, {
    "name": "batchSize",
    "valueDecimal": 1000
  } ]
}

Reindex Batch Job

The $reindex operation creates a batch job that can be stopped and restarted on the Batch Job Management page.

Reindex and Partitions

The $reindex operation is partition aware. The operation is performed only on the partition that was included in the request and the job is only started if the user is allowed to access that partition. In order to perform a $reindex everything=true, the user must have access to all resource types on that partition.

5.9.8Legacy Manual Reindex Operation

 

The following documentation is provided for the old reindexing operation. Users are encouraged to use the new operation as it provides better control of what's indexed and a user-interface to view, stop, and restart the reindexing job.

Parameters

The following arguments are supported for this operation:

  • type(optional) If supplied, specifies the specific resource type to reindex. If not specified, all resource types will be reindexed.

Example

To perform a manual reindex, the following operation can be invoked at the server (root) level of the FHIR Endpoint module (i.e. the base URL of the FHIR endpoint). To specifiy parameters, a resource of type Parameters must be included as the body of a POST request. See the following examples for more details.

-- DEPRECATED --

GET /$mark-all-resources-for-reindexing
POST /$mark-all-resources-for-reindexing
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [ {
    "name": "type",
    "valueString": "Patient"
  } ]
}