FHIR Search: Enforcing Uniqueness
This page outlines how to ensure that values are unique within a repository.
Unique combo search index parameters are Combo Search Parameters that are backed by a uniqueness constraint in the database. These search parameters enforce uniqueness for the combined values matched by the given search parameters across the entire repository.
Consider a repository that stores Encounter resources. These encounters have a subject (the Patient) and a date (the date of the encounter). This combination of parameters may be expressed using a search such as the following URL:
https://try.smilecdr.com:8000/baseR4/Encounter
Now, suppose you wish to enforce a business rule that a given Patient may only have one Encounter per day. A combo search index parameter can be used to enforce this uniqueness by declaring that combinations of the Encounter:date and Encounter:subject search parameters are globally unique.
Unique Combo Search Index Parameters enforce this uniqueness using a unique database index enforced by the RDBMS, so they are consistent even under high concurrency. They are declared using a SearchParameter resource. The following example shows a SearchParameter resource for this case (R4+ syntax shown below):
{
"resourceType": "SearchParameter",
"extension": [
{
"url": "http://hapifhir.io/fhir/StructureDefinition/sp-unique",
"valueBoolean": true
}
],
"status": "active",
"code": "subject-and-date",
"base": [
"Encounter"
],
"type": "composite",
"expression": "Encounter",
"component": [
{
"definition": "SearchParameter/clinical-patient",
"expression": "Encounter"
},
{
"definition": "SearchParameter/clinical-date",
"expression": "Encounter"
}
]
}
The combo search parameter above contains two references to other SearchParameter resources (in this case, Encounter:patient and Encounter:date, which are represented by the IDs SearchParameter/clinical-patient and SearchParameter/clinical-date respectively).
In order to create the composite search parameter, first the existing SearchParameter resources should be looked up to determine their respective IDs. This can be done using a query such as the following example:
http://example.com:8000/SearchParameter
This returns a result such as the following (most of the content has been removed for readability):
{
"resourceType": "Bundle",
"type": "searchset",
"entry": [
{
"resource": {
"resourceType": "SearchParameter",
"id": "clinical-patient",
"code": "patient"
}
},
{
"resource": {
"resourceType": "SearchParameter",
"id": "clinical-date",
"code": "date"
}
}
]
}
Note that it is not necessary for the parameter to have more than one component. If a single search parameter should be unique, the composite search parameter may have a single component.
The http://hapifhir.io/fhir/StructureDefinition/sp-unique extension must exist in a search parameter in order for it to be indexed as a unique search parameter, and this extension should have a boolean value of true as shown above.
On partitioned systems, uniqueness is currently enforced globally per database. This means that the same values will not be permitted even on different partitions.
In the case of MegaScale repositories, uniqueness is enforced globally on each MegaScale database. This means that two separate MegaScale databases can have the same unique value exactly once each.