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. These search parameters are declared as consisting of one or more normal search parameters, and may be declared as unique or non-unique.

Combo Search Parameters have several related purposes:

  • Speeding up searches with a set of search parameters that are commonly used together (non-unique combo search parameter)
  • Enforce uniqueness (unique combo search parameter)
  • Or both of these things (unique combo search parameter)

Declaring Combo Search Parameters

 

A Combo Search Parameter uses a SearchParameter.type value of composite but must also have an extension with a URL of http://hapifhir.io/fhir/StructureDefinition/sp-unique to mark it as a combo search parameter. This extension must also have a value of type boolean. The value true indicates a unique parameter, and the value false indicates a non-unique 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.

See the Examples Page to see how this extension is used.

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.

The following date parameter modifiers are not supported by the combo search parameter, and their use will fall back to using the standard (non-combo) search parameter indexes: eb (ends before), sa (starts after), ap (approximately). This means that these searches can still be performed, but they will not get the performance advantage of using the combo index.

Filtering Combo Parameter Indexes

 

Combo Search Parameters do not enable any additional search capabilities, they only serve to speed up existing searches and/or enforce uniqueness on specific parameters or parameter combinations.

Within the Combo Search Parameter definition, it is possible to declare that only specific parameter values should actually be included in the index. This is achieved by adding an extension to a component within the parameter. This extension should have the URL http://hapifhir.io/fhir/StructureDefinition/sp-combo-component-filter-allowlist and should have a value containing the values to include in the index. This extension may be repeated multiple times on the same component to include multiple component values within the index.

Valid Values

Only specific datatypes can be used as values for the http://hapifhir.io/fhir/StructureDefinition/sp-combo-component-filter-allowlist extension.

Extension Value Type Search Parameter Type Usage
Identifier with Identifier.system and Identifier.value populated token Index will only include identifiers with the given system and value
Identifier with only Identifier.system populated token Index will only include identifiers with the given system and any value
Identifier with only Identifier.value populated token Index will only include identifiers with the given value (this is generally only useful for code elements such as Encounter.status).
Coding with Coding.system and/or Coding.code populated token This may be used in the same ways as Identifier above.
code token Index will only include codes with the given code value.
url uri Index will only include URLs matching the specified URL
uri uri Index will only include URLs matching the specified URL

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.

Containing composed SP / Contained SP TypeStringTokenDateQuantityUriNumberReference
Combo Unique✔✔✔✔✔✔✔
Combo Non-Unique✔✔✔✔✔✔✔
Composite with full text indexing✔✔✔✔✔✔
Composite without full text indexing✔✔✔✔

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.