Support Related Context Retrieves

[cmoesel]

Related Context Retrieves allow CQL queries to cross contexts (for example, into another patient's context). A classic example of this is provided in the CQL documentation (slightly modified below):

library MyLibrary version '0.0.1'
using FHIR version '4.0.1'
include FHIRHelpers version '4.0.1' called FHIRHelpers

codesystem "RoleCode": 'http://terminology.hl7.org/CodeSystem/v3-RoleCode'
valueset "Estimated Due Date Exam": 'TBD'
code "Mother Relationship": 'MTH' from "RoleCode"

context Patient

define "Mother": singleton from ([RelatedPerson: "Mother Relationship"])

define "Estimated Due Date Observations":
    ["Mother" -> "Observation": "Estimated Due Date Exam"]

In the above CQL, the Observation query should be done in the context of the mother's medical records (not the patient's context).

Most of the magic here is contained in the ELM and the FHIR modelinfo. Here is a snippet of the resulting ELM:

{
  "name": "Estimated Due Date Observations",
  "context": "Patient",
  "accessLevel": "Public",
  "expression": {
    "dataType": "{http://hl7.org/fhir}Observation",
    "templateId": "http://hl7.org/fhir/StructureDefinition/Observation",
    "codeProperty": "code",
    "codeComparator": "in",
    "type": "Retrieve",
    "codes": {
      "name": "Estimated Due Date Exam",
      "preserve": true,
      "type": "ValueSetRef"
    },
    "context": {
      "name": "Mother",
      "type": "ExpressionRef"
    }
  }
}

The new property of interest is the context property in the Retrieve, which tells us to look at the Mother expression to get the context. The Mother expression is the standard ELM representation that results in a RelatedPerson:

{
  "name": "Mother",
  "context": "Patient",
  "accessLevel": "Public",
  "expression": {
    "type": "SingletonFrom",
    "operand": {
      "dataType": "{http://hl7.org/fhir}RelatedPerson",
      "templateId": "http://hl7.org/fhir/StructureDefinition/RelatedPerson",
      "codeProperty": "relationship",
      "codeComparator": "~",
      "type": "Retrieve",
      "codes": {
        "type": "ToList",
        "operand": {
          "name": "Mother Relationship",
          "type": "CodeRef"
        }
      }
    }
  }
}

Unfortunately, the ELM doesn't tell us how to get the mother's patient ID in order to establish a new context. For that, we must look at the RelatedPerson type in the FHIR modelinfo file:

<typeInfo xsi:type="ClassInfo" baseType="FHIR.DomainResource" namespace="FHIR" name="RelatedPerson" identifier="http://hl7.org/fhir/StructureDefinition/RelatedPerson" label="RelatedPerson" retrievable="true" primaryCodePath="relationship">
	<!-- bunch of elements removed for brevity -->
	<element name="patient" elementType="FHIR.Reference" description="The patient this person is related to" definition="The patient this person is related to."/>
	<!-- bunch more elements removed for brevity -->
	<contextRelationship context="Patient" relatedKeyElement="patient"/>
	<!-- searches removed for brevity -->
</typeInfo>

Note that the contextRelationship indicates that the element of interest is patient -- from which we can get the mother's patient ID to do the necessary contextual retrieve.

Supporting this will be difficult, as it requires:

1. That the CQL engine have access to the modelinfo file that was used to generate the ELM.
2. That the CQL engine have access to the related data (e.g., of the mother, but without necessarily assuming the other data is a patient that should be individually evaluated).