Combo Search Index Parameters

HAPI FHIR and Smile CDR define a special type of SearchParameter called a Combo Search Index Parameter that is used to index a combination of parameters together in a single database table. For example, consider the following search: http://localhost:8000/Patient?family=smith&gender=http://hl7.org/fhir/administrative-gender|male&birthdate=2021-01-01

By default, the search above relies on separate index tables to manage the family name, gender, and birthdate parameters. This generally works well, but can lead to performance issues if each of these parameters individually returns a large number of records (as would likely be the case for the family and gender parameters above in a large FHIR repository).

Using a Combo Search Index Parameter avoids unnecessary database joining by combining (denormalizing) all of the above values into a single database table for indexing and searching. Optionally, Smile CDR can also enforce uniqueness for the values of the parameters. See Unique Combo Search Index Parameters below for more information.

Composite vs Combo Search Index Parameters

Note that Combo Search Index Parameters are a different concept from the FHIR Composite Search Parameter type.

FHIR Composite Search Index Parameters use a single parameter in a REST search URL to express multiple values where the values are closely related within the resource (e.g. the component code and component value within an Observation).

HAPI FHIR / Smile CDR Combo Index Search Parameters use multiple parameters in a REST search URL to express unrelated search parameters that are intended to be used together.

Both of these concepts are defined using a SearchParameter resource with a type of composite, however the latter uses an sp-unique extension to mark it as a combo search parameter.

There are limited number of Search Parameter types that can be used in composite and combo Search Parameters. For more details see Support for Component Types.

Example

The following example shows a sample Non-unique Combo Index Search parameter, and it assumes that you have already created the 3 individual SearchParameter resources based on the Patient resource's properties being used here (family, gender and birthdate).

{
  "resourceType": "SearchParameter",
  "extension": [
    {
      "url": "http://hapifhir.io/fhir/StructureDefinition/sp-unique",
      "valueBoolean": false
    }
  ],
  "status": "active",
  "code": "family-gender-birthdate",
  "base": [
    "Patient"
  ],
  "type": "composite",
  "expression": "Patient",
  "component": [
    {
      "definition": "SearchParameter/individual-family",
      "expression": "Patient"
    },
    {
      "definition": "SearchParameter/individual-gender",
      "expression": "Patient"
    },
    {
      "definition": "SearchParameter/individual-birthdate",
      "expression": "Patient"
    }
  ]
}

Indexing Dates in Combo Search Parameters

When using a Combo Search Parameter which contains a date SearchParameter component, the behaviour varies depending on whether the Search Parameter is marked as unique or not.

• For Unique Combo Search Parameters: An index value will only be stored if the date has DAY precision. This means that uniqueness can currently only be enforced for a given day value. There are no currently known use cases for this behavior, so feedback which will guide future development is welcome.
• For Non-Unique Combo Search Parameters: An index value will only be stored if the element being indexed has precision of at least DAY. This means that an Observation with an Observation.effectiveDateTime value of 2021-01 will not be indexed by the combo Search Parameter. Values such as 2021-01-01 and 2021-01-01T12:22:33-04:00 will be indexed by the combo Search Parameter.

When performing a search which includes a parameter with a date value supported by the combo index, the combo index will be used as long as the query parameter value has a precision of at least DAY (e.g. ?date=2021-01-01). If the URL query parameter has a precision greater than DAY (e.g. ?date=2021-01-01T12:22:33-04:00) the search will use the Combo Search Parameter index, but will additionally use the standard date SearchParameter index to verify the additional precision. This can result in a performance impact at scale, so it may be preferable to use only DAY precision in query parameters when possible.

Ranged Date Searches

Combo Search Parameter indexes typically require an exact match between the URL parameter and the value in the resources being indexed. However, a common pattern in large scale FHIR infrastructure is to search for resources matching some combination of attributes (e.g. Observations with a specific subject and code) as well as a date range (e.g. having a date value within the last 2 years).

Non-unique combo search parameters can be used to support this pattern, by marking your date component as a "ranged" date component. This is done by adding the http://hapifhir.io/fhir/StructureDefinition/sp-combo-date-ranged extension to the date component you wish to support date range searches on. Note that this feature is not available on Unique Combo Search Parameters, and only one component of a given Combo Search Parameter may be marked with this extension. SearchParameter resources will be rejected by the server if they try to add multiple ranged date components.

Ranged Date Search Example

Consider the common scenario for a document repository, where you want to search for document Bundle resources for a given subject and date range. This example could easily be expanded to include additional parameters such as the document type or category.

First, a SearchParameter is created for the document subject:

{
  "resourceType": "SearchParameter",
  "id": "Bundle-composition-subject",
  "url": "http://example.org/SearchParameter/Bundle-composition-subject",
  "name": "composition.subject",
  "status": "active",
  "code": "composition.subject",
  "base": [ "Bundle" ],
  "type": "reference",
  "expression": "Bundle.where(type = 'document').entry[0].resource.as(Composition).subject"
}

Then, a SearchParameter is created for the document date:

{
  "resourceType": "SearchParameter",
  "id": "Bundle-composition-date",
  "url": "http://example.org/SearchParameter/Bundle-composition-date",
  "name": "composition.date",
  "status": "active",
  "code": "composition.date",
  "base": [ "Bundle" ],
  "type": "date",
  "expression": "Bundle.where(type = 'document').entry[0].resource.as(Composition).date"
}

Finally, a non-unique Combo Search Parameter is created for the subject and date. Note the sp-combo-date-ranged extension on the date component:

{
  "resourceType": "SearchParameter",
  "id": "Bundle-composition-subject-and-date",
  "extension": [ {
    "url": "http://hapifhir.io/fhir/StructureDefinition/sp-unique",
    "valueBoolean": false
  } ],
  "status": "active",
  "code": "bundle-composition-subject-and-type",
  "base": [ "Bundle" ],
  "type": "composite",
  "expression": "Bundle",
  "component": [ {
    "definition": "SearchParameter/Bundle-composition-subject",
    "expression": "Bundle"
  }, {
    "extension": [ {
      "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-date-ranged",
      "valueBoolean": true
    } ],
    "definition": "SearchParameter/Bundle-composition-date",
    "expression": "Bundle"
  } ]
}

The following searches would be supported by this Combo Search Parameter, and would be expected to perform well at scale:

• Bundle?composition.date=2022-01-02&composition.subject=Patient/PAT-0
• Bundle?composition.date=ge2022-01-01&composition.subject=Patient/PAT-0
• Bundle?composition.date=gt2022-01-01&composition.subject=Patient/PAT-0
• Bundle?composition.date=lt2022-01-03&composition.subject=Patient/PAT-0
• Bundle?composition.date=le2022-01-03&composition.subject=Patient/PAT-0

Multiple date parameters can also be combined in order to construct a range search:

• Bundle?composition.date=ge2022-01-01&composition.date=le2022-01-03&composition.subject=Patient/PAT-0

If the parameter value has a precision greater than DAY, the search will use the Combo Search Parameter index, but it will also use the standard date SearchParameter index to verify the additional precision. This can result in a performance impact at scale.

• Bundle?composition.date=ge2022-01-01T12:00:00Z&composition.subject=Patient/PAT-0

The following date parameter modifiers are not supported: eb (ends before), sa (starts after), ap (approximately).

Support for Component Types

Composite and Combo Search Parameters are composed of other SearchParameters which are listed under the component element of the SearchParameter. Smile CDR and HAPI FHIR support subsets of SearchParameterTypes for composed SearchParameters which will differ based on the containing SearchParameter definition (see sp_unique extension) and whether Indexing of Search Parameters is enabled.

The following table lists supported Types for contained SearchParameters based on the containing composed SearchParameter. Note the limitations described in the following section as well.

Limitations

• Partitioning: Unique Combo search parameters are not partition-aware. This means that uniqueness will be enforced globally (i.e. not on a per-partition basis) and the uniqueness constraint on the HFJ_IDX_CMP_STRING_UNIQ table does not incorporate the partition ID.
• Token: Tokens will only be indexed if the element value includes both a system and a value, except in cases where the system is implicit because the element is of type code and has a required terminology binding (e.g. Patient.gender).
• Date/Time:
  • For Combo Non-Unique search parameters, Date and DateTime types will only be indexed if the date has DAY precision (i.e. yyyy-MM-dd).
  • Combo Unique search index is not used during the search if one of the component search parameters has a Date or DateTime type; in this case, index is only used to enforce uniqueness.
• Reference: References will only be indexed if the element value is exactly in the form [resourceType]/[id]. Searches will only leverage the index if the search URL is also in this exact form.