Search 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.
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
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:
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.
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"
}
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:
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.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.