Search Parameter Features
This page outlines optional features that can be enabled or disabled for optimizing how searching works on your server.
Note that every search feature that is enabled comes with a cost in terms of the amount of space that indexes consume, the time it takes to write new data, etc. We have tried to provide sensible defaults but it always makes sense to review these settings and optimize as much as possible.
This feature defaults to: Disabled. Configuration is described here.
If Nickname search is enabled on a storage module, then names can be searched using the :nickname search parameter extension.
E.g. Patient/?given:nickname=Kenneth will match patients with given name Kenny. Similarly,
Patient/?given:nickname=Kenny will match patients with given name Kenneth.
Currently, only English nicknames are supported. But a custom set of nicknames can be provided.
By default, nickname matching service uses a list of names as provided by a third party library.
However, if this is insufficient, or inadequate, a custom file can be provided.
This configuration is described here
Any custom nickname file must be formatted as a list of rows with comma separated names and nicknames.
Eg:
robert,bob,bobby,rob,robbie
beatrix,trixie,bea
NB: If provided, this custom nickname file will override the default nickname map.
This feature defaults to: Disabled. Configuration is described here.
When enabled, the :missing modifier can be used on a SearchParameter to find resources where that search parameter has found (or not found) any data in the given resource.
For example, take the Patient:birthdate search parameter, which indexes the value of Patient.birthDate. The following URL finds all patients having a birthdate:
https://try.smilecdr.com/baseR4/Patient
The following URL finds all patients who do not have a birthdate:
https://try.smilecdr.com/baseR4/Patient
Indexing for missing search parameters can add a great deal of extra index space, and slow down write operations on servers with many enabled search parameters. This feature is therefore disabled by default and must be specifically enabled if it is needed.
This feature defaults to: Disabled. Configuration is described here.
SearchParameters of type token are generally used to index identifiers and coded fields. For example, a FHIR Body Height Observation can be found using its LOINC code by using the following query:
https://try.smilecdr.com/baseR4/Observation
By default, it is also possible to search by the display name of the code ("body height") using the following query:
https://try.smiledigitalhealth.com/baseR4/Observation
This can be helpful if you are building a system that allows such free-text searching, but this can also consume a large amount of extra index space on servers with large numbers of coded fields because a string index is required for every token index. Servers with large numbers of Observations are particularly prone to "index bloat" if token-text indexing is enabled.
It can also be disabled for an individual search parameter using an extension on the search parameter:
{
"resourceType": "SearchParameter",
"id": "observation-code",
"extension": [ {
"url": "http://hapifhir.io/fhir/StructureDefinition/searchparameter-token-suppress-text-index",
"valueBoolean": true
} ],
"status": "active",
"code": "code",
"base": [ "Observation" ],
"type": "token",
"expression": "Observation.code"
}
This feature defaults to: Disabled. Configuration is described here.
FHIR search parameters of type reference support a concept called chaining. Consider the following resources:
Patient resource:
{
"resourceType": "Patient",
"id": "1",
"name": [{
"family": "Smith"
}]
}
Observation resource with reference to Patient:
{
"resourceType": "Observation",
"id": "2",
"subject": { "reference": "Patient/1" }
}
With these resources stored in your repository, the following search will return the Observation resource.
http://localhost:8000/Observation
This works because of the chain, which is the dot notation followed by a second search parameter. This syntax means "find me any Observation resources where the subject reference links to a target resource where a search for name=Smith would match."
By default, chained searches only consider top-level resources. Consider the following Observation resource with a reference to a contained Patient.
{
"resourceType": "Observation",
"id": "3",
"contained": [
{
"resourceType": "Patient",
"id": "contained-patient",
"name": [{
"family": "Smith"
}]
}
],
"subject": { "reference": "#contained-patient" }
}
The search given above will not return this Observation, because the contained resource has not been included in the search indexes. If the Index Contained Resources feature is enabled, indexes will be generated for the contained resources, and Observation/3 would be included in the search results.
For a more complicated example, where contained resources refer to other contained resources, as shown below, it is necessary to enable both the Index Contained Resources feature and the Index Contained Resources Recursively feature, described here.
{
"resourceType": "Observation",
"id": "4",
"contained": [
{
"resourceType": "Patient",
"id": "contained-patient",
"generalPractitioner": [{
"reference": "#contained-practitioner"
}]
},
{
"resourceType": "Practitioner",
"id": "contained-practitioner",
"name": {
"family": "Jones"
}
}
],
"subject": { "reference": "#contained-patient" }
}
Note: After enabling either of these features, it is necessary to reindex your repository.
Note: These features have an associated performance cost. We do not recommend enabling them unless you have a business need to search into contained resources.