4.8.1FHIR Search: Uplifted Refchains

If a search is often performed with a chained value, it can add a lot of overhead to the database to perform the search. For example, consider the following query: http://base/Encounter?subject.gender=male&code=http://loinc.org%7C12345-6

Internally the search above is translated into a query for Patient resources with a gender of male and then a query for Observation resources with a subject matching any of these Patient resources and a code of 12345-6.

A HAPI FHIR / Smile CDR server can optimize this query by indexing the subject.gender value directly against the Observation resource, reducing the number of SQL Joins to be performed. This is called an Uplifted Refchain.

To create an uplifted refchain, an extension is added to the base search parameter.

Continuing the example above, this means updating the Observation:subject search parameter, creating it if it does not exist. Be careful not to create a second search parameter if you already have one defined for Encounter:subject. In this case, you must update the existing search parameter and add the new extension to it.

The extension has the following URL: https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain

This extension has the following children:

• code - Contains a code with the name of the chained search parameter to uplift.

An example follows:

{
   "resourceType": "SearchParameter",
   "id": "Observation-subject",
   "extension": [
      {
         "url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
         "extension": [
            {
               "url": "code",
               "valueCode": "name"
            }
         ]
      }
   ],
   "url": "http://hl7.org/fhir/SearchParameter/Observation-subject",
   "name": "subject",
   "status": "active",
   "code": "subject",
   "base": [
      "Observation"
   ],
   "type": "reference",
   "expression": "Observation.subject",
   "target": [
      "Group",
      "Patient"
   ]
}

4.8.2Document and Message Search Parameters

The FHIR standard defines several search parameters on the Bundle resource that are intended to be used for specialized Bundle types.

Unlike any other search parameters in the FHIR specification, these parameters use a FHIRPath expression that resolves to an embedded Resource (all other search parameters in the FHIR specification resolve to a datatype).

These parameters are only intended to be used as a part of a chained search expression, since it would not be meaningful to use them otherwise. For example, the following query could be used in order to use the composition search parameter to locate FHIR Documents stored on the server that are an International Patient Summary. In other words, this searches for Bundle resources where the first resource in the Bundle is a Composition, and that Composition has a Composition.type using LOINC code 60591-5. http://localhost:8000/Bundle?composition.type=http://loinc.org%7C60591-5

In order to use these search parameters, you must create a search parameter that includes the fully chained parameter value as the name and code values. In the example above, composition is the search parameter name, and type is the chain name. The fully chained parameter value is composition.type. A search parameter to support the query above would be:

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

You can also create search parameters that support a chained search against other resources in the Bundle. For example: http://localhost:8000/Bundle?composition.patient.identifier=http://example.org/mrn%7C12345

To support such a query, you should use a FHIRPath expression that fully resolves the intended value within the Bundle resource. You may use the resolve() function to resolve resources that are contained within the same Bundle. Note that when used in a SearchParameter expression, the resolve() function is not able to resolve resources outside of the resource being stored. A search parameter to support the query above would be:

{
  "resourceType": "SearchParameter",
  "id": "Bundle-composition-patient-identifier",
  "url": "http://example.org/SearchParameter/Bundle-composition-patient-identifier",
  "name": "composition.patient.identifier",
  "status": "active",
  "code": "composition.patient.identifier",
  "base": [ "Bundle" ],
  "type": "token",
  "expression": "Bundle.entry[0].resource.as(Composition).subject.resolve().as(Patient).identifier"
}

4.8.3Combo Search Parameters on Uplifted Refchains

It is possible to combine Uplifted Refchains with Combo Search Parameters. If a complex combination of chained search parameters is frequently used, this can dramatically reduce the query speed, at the expense of additional write overhead (and the risk of stale chained data, as discussed above).

For example, consider the following query: http://base/Coverage?patient.family=Simpson&patient.given=Homer&patient.birthdate=1967-02-25&patient.gender=male&patient.address-postalcode=93514

This query can be combined into a single Combo Search Parameter which can be searched very efficiently by creating the following Search Parameter to define the uplift:

{
	"resourceType": "SearchParameter",
	"id": "Coverage-patient",
	"extension": [
		{
			"url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
			"extension": [
				{
					"url": "code",
					"valueCode": "family"
				}
			]
		},
		{
			"url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
			"extension": [
				{
					"url": "code",
					"valueCode": "given"
				}
			]
		},
		{
			"url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
			"extension": [
				{
					"url": "code",
					"valueCode": "gender"
				}
			]
		},
		{
			"url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
			"extension": [
				{
					"url": "code",
					"valueCode": "address-postalcode"
				}
			]
		},
		{
			"url": "https://smilecdr.com/fhir/ns/StructureDefinition/searchparameter-uplift-refchain",
			"extension": [
				{
					"url": "code",
					"valueCode": "birthdate"
				}
			]
		}
	],
	"url": "http://hl7.org/fhir/SearchParameter/clinical-patient",
	"name": "patient",
	"status": "active",
	"description": "The patient for this coverage",
	"code": "patient",
	"base": [
		"Coverage"
	],
	"type": "reference",
	"expression": "Coverage.beneficiary",
	"processingMode": "normal",
	"target": [
		"Patient"
	]
}

The following Combo Search Parameter can then be used to index the combination.

{
  "resourceType": "SearchParameter",
  "id": "Coverage-patient-combo",
  "extension": [
    {
      "url": "http://hapifhir.io/fhir/StructureDefinition/sp-unique",
      "valueBoolean": false
    }
  ],
  "status": "active",
  "base": [
    "Coverage"
  ],
  "type": "composite",
  "component": [
    {
      "extension": [
        {
          "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-uplift-chain",
          "valueCode": "family"
        }
      ],
      "definition": "SearchParameter/Coverage-patient",
      "expression": "Coverage"
    },
    {
      "extension": [
        {
          "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-uplift-chain",
          "valueCode": "given"
        }
      ],
      "definition": "SearchParameter/Coverage-patient",
      "expression": "Coverage"
    },
    {
      "extension": [
        {
          "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-uplift-chain",
          "valueCode": "gender"
        }
      ],
      "definition": "SearchParameter/Coverage-patient",
      "expression": "Coverage"
    },
    {
      "extension": [
        {
          "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-uplift-chain",
          "valueCode": "address-postalcode"
        }
      ],
      "definition": "SearchParameter/Coverage-patient",
      "expression": "Coverage"
    },
    {
      "extension": [
        {
          "url": "http://hapifhir.io/fhir/StructureDefinition/sp-combo-uplift-chain",
          "valueCode": "birthdate"
        }
      ],
      "definition": "SearchParameter/Coverage-patient",
      "expression": "Coverage"
    }
  ]
}