FHIR Search: Custom Search Parameters
The FHIR specification includes a rich set of default Search Parameters. For example, see the Patient Resource Search Parameters.
However, the list of search parameters specified in the core FHIR specification is only the default. You can create your own Search Parameters in Smile CDR in order to index fields and extensions that are not indexed by default. You can also customize how Search Parameters behave, and remove search parameters you do not need.
In FHIR, a Search Parameter is defined using a special resource called SearchParameter. You can customize and update existing SearchParameters (which are automatically inserted into your database the first time the system starts up) and you can add new ones too.
What follows is an example of a search parameter on an extension. We'll suppose that in our system we've defined an extension for a given patient's eye colour. Patient resources stored in our database will have the eye colour extension set, and we want to be able to search on this extension, too.
1. Create the Search Parameter
First, define a search parameter and upload it to your server. The following shows the SearchParameter resource. Note the expression value, which is a FHIRPath expression.
{
"resourceType": "SearchParameter",
"title": "Eye Colour",
"base": [ "Patient" ],
"status": "active",
"code": "eyecolour",
"type": "token",
"expression": "Patient.extension('http://acme.org/eyecolour')",
"xpathUsage": "normal"
}
2. Upload Some Resources
Let's upload two Patient resources with different eye colours.
{
"resourceType": "Patient",
"extension": [
{
"url": "http://acme.org/eyecolour",
"valueCode": "blue"
}
],
"active": true
}
{
"resourceType": "Patient",
"extension": [
{
"url": "http://acme.org/eyecolour",
"valueCode": "green"
}
],
"active": true
}
3. Search!
Finally, let's try searching:
http://example.com:8000/Patient
This produces a search result that contains only the matching resource:
{
"resourceType": "Bundle",
"id": "bc89e883-b9f7-4745-8c2f-24bf9277664d",
"meta": {
"lastUpdated": "2017-02-07T20:30:05.445-05:00"
},
"type": "searchset",
"total": 1,
"link": [
{
"relation": "self",
"url": "http://example.com:8000/fhir/context/Patient?eyecolour=blue"
}
],
"entry": [
{
"fullUrl": "http://example.com:8000/fhir/context/Patient/2",
"resource": {
"resourceType": "Patient",
"id": "2",
"meta": {
"versionId": "1",
"lastUpdated": "2017-02-07T20:30:05.317-05:00"
},
"extension": [
{
"url": "http://acme.org/eyecolour",
"valueCode": "blue"
}
],
"active": true
},
"search": {
"mode": "match"
}
}
]
}
The SearchParameter.expression element determines the exact path within the resource that should be extracted and indexed when a target resource is being stored.
See FHIRPath Expressions for examples.
When a new search parameter is introduced, assuming the new parameter is valid and active, all resource changes (creates, updates, etc.) will be indexed by the new search parameter. These resources will then be searchable using the new search parameter as well.
However, new search parameters can cause an issue when data already exists in the repository because old data won't yet be indexed by the new search parameter. This can cause misleading or unexpected results since data which should be returned by the new search parameter may not be. In the case of Combo Search Parameters, previously working searches may even stop working since specific combinations of search parameters may be searched using the new and still incomplete combo index.
In order to avoid a search parameter being used for searching, it can be marked as not enabled for searching. This is accomplished by adding an extension to the root of the SearchParameter resource with the searchparameter-enabled-for-searching URL, and a boolean value.
The following example shows a SearchParameter resource declaring the standard Patient family parameter, with an extension declaring that it should not be enabled for searching.
{
"resourceType": "SearchParameter",
"id": "individual-family",
"extension": [ {
"url": "http://hapifhir.io/fhir/StructureDefinition/searchparameter-enabled-for-searching",
"valueBoolean": false
} ],
"url": "http://hl7.org/fhir/SearchParameter/individual-family",
"name": "family",
"status": "active",
"code": "family",
"base": [ "Patient" ],
"type": "string",
"expression": "Patient.name.family"
}
With the extension above in place, searches will not try to leverage this SearchParameter, and the server CapabilityStatement will not declare support for this parameter.
Once an appropriate $reindex operation has been run and completed, the SearchParameter resource can be manually updated to either remove the extension, or set its value to true (both of these options will yield the same result).