CQL Translator 3.3.0 Engine Impact Note

Issue Summary:

In some cases, function overloads may not be able to be correctly determined at runtime

Executive Summary:

When using CQL with FHIR, there are some cases where CQL engines may not be able to determine which overload of a function an author intended if the default translator options are used. This issue does not occur with QDM-based CQL, and the issue has not yet been encountered in FHIR-based measures, though other projects using FHIR and CQL have encountered the issue and it should be addressed. The next version of the translator (3.3.0) will include a warning to indicate when ELM with this potential is being produced. An update to the recommended translator options for using CQL with FHIR is being prepared.

Detailed Description:

The CQL specification supports defining function overloads, which allows functions with the same name to be used with different types of arguments. This capability is used in the system-defined functions, to support the same operation on different types, for example, addition can be invoked on both Integer and Decimal arguments.

When overloaded functions appear in ELM and they are using the system-defined types, engines can determine the correct overload to run because each system-defined type has a unique runtime representation.

However, when overloads are defined on types that are defined in Models, it’s not always the case that the types have a unique run-time representation.

By default, the ELM translator does not include invocation signatures in function calls. This means that for overloads that involve types that do not have a unique run-time representation, the function invocation may be ambiguous. In other words, the run-time engine does not have enough information to determine the correct overload of a function to call.

The ELM translator has a Signature Level option that controls whether invocation signatures are included in ELM output. The default is None, but there are also Differing, Overloads, and All options that provide control over how much invocation information is included.

The Overloads option instructs the translator to include invocation signature information whenever the function being called has overloads, to ensure that run-time engines have enough information to correctly determine the overload to call

Resolution:

The 3.3.0 version of the translator includes a new warning that will be output whenever a function is invoked that has the potential to be ambiguous at runtime and the Signature Level setting is such that insufficient information will be included in the ELM output.

This warning is a signal to make sure that any library is produced with enough information for run-time engines to be able to correctly determine the specific overload of a function being called.

The SignatureLevel setting specifically controls whether the signature element of a FunctionRef will be populated.

We have confirmed through regression translation of the 2023AU eCQMs that this issue does not occur with QDM.

Typically, this issue does not impact FHIR measures because most of the overloaded functions have the same implementation (ToString, for example, is usually just value.value). However, there are cases where this issue surfaced, and it is likely to surface in FHIR-based measures.

As a result, we recommend that the default translator options be updated to use the Overloads option for Signature Level (https://jira.hl7.org/browse/FHIR-42922) and (https://jira.hl7.org/browse/FHIR-42921)

Engine Impact:

If engines are already using the FunctionRef.signature element to determine which function overload to call, then there is no impact on engine behavior.

For engines that do not yet make use of this capability, there is the potential for engines to select the wrong overload at runtime.

Engines should use the signature element to determine the function overload to be called for a given FunctionRef.

Engines should throw an error if signature information is not present and the function being called has overloads.

Test case to ensure correct engine behavior: https://github.com/cqframework/clinical_quality_language/blob/7b1f7ab5c88fd70b7a7db1b4be7b7c1e8e0d0df5/Src/java/cql-to-elm/src/test/resources/org/cqframework/cql/cql2elm/fhir/r401/TestOverload.cql