FHIR Chat · cql and library-evaluate operations

Stream: cql

Topic: cql and library-evaluate operations

Corey Sanders (Jun 09 2021 at 20:12):

I'm trying to implement the $cql and $library-evaluate operations per the CPG recommendations. The $library-evaluate operation always returns a Parameters resource and, for an expression where the result that is a list, the return Parameters resource should include multiple parameters with the same name corresponding to the expression for which the list that is returned. That works fine for all datatypes include lists of resources and lists of primitives. For the $cql operation, there will be a single result. In the return doc, it says that a list of resources should be returned as a bundle and other types should be returned as a Parameters resource. I'm struggling with that Parameters resource recommendation. The exact wording is as follows...

If the result is a List of resources, the result will be a Bundle. If the result is a CQL system-defined or FHIR-defined type, the result is returned as a Parameters resource

What would I do with a list of primitives as in the following expression?

 [Encounter: "Inpatient"] E
  return all E.lengthOfStay

I'm also curious why do the two operations behave differently for lists of resources? One creates duplicate parameter names and the other constructs a bundle.

JP (Jun 09 2021 at 20:24):

The difference in output is mainly due to the fact that $cql started life as an ad-hoc operation on the cqf-ruler to provide an execution service for CQL and thus was subject to fewer constraints than $evaluate. It was convenient to get a Bundle with a few resources when you were evaluating a single expression. On the other hand $evaluate evolved alongside the rest of the clinical reasoning and Parameters resource guidance. It'd be worth discussing whether or not to reconcile that difference.

JP (Jun 09 2021 at 20:33):

FHIR Parameters support primitives using the value[x]. For example:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "DefinitionName",
      "part": [
        {
          "name": "value",
          "valueBoolean": true
        }
      ]
    }
  ]
}

So you'd return a Parameters resource with multiple parameters each named "DefinitionName" with a value part that had "valueDuration" and whatever the duration is.

Corey Sanders (Jun 09 2021 at 20:38):

Thanks, @JP. Is "DefinitionName" just assumed as a constant at that point? Same question for the inner parts. Are each of those just named "value"?

JP (Jun 09 2021 at 20:43):

"DefinitionName" = Whatever the original definition name was in the CQL library

Sorry, the example I gave wasn't correct (was copy-pasting quicky...):

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "DefinitionName",
       "valueBoolean": true
    }
  ]
}

Corey Sanders (Jun 09 2021 at 20:44):

I'm was specifically asking for the ad-hoc $cql case where there isn't really a well-defined DefinitionName.

JP (Jun 09 2021 at 20:48):

Hmm... That seems like a gap in the spec. I've only implemented the Bundle side of that. I'd suggest "result" or similar. @Bryn Rhodes ?

Corey Sanders (Jun 09 2021 at 20:59):

Where do I find the HAPI implementation for these operations? It would help me to review the decisions that were made there.

JP (Jun 09 2021 at 21:08):

There’s no complete implementation of either for HAPI as far as I’m aware. The cqf-ruler (which is based on HAPI) has partial implementations based on an older, in-progress version of the cpg spec. Those implementations are here:

https://github.com/DBCG/cqf-ruler/blob/9f1a748cb1342bc4421404502eb53d6fa3383a85/r4/src/main/java/org/opencds/cqf/r4/providers/CqlExecutionProvider.java#L233

https://github.com/DBCG/cqf-ruler/blob/master/r4/src/main/java/org/opencds/cqf/r4/providers/LibraryOperationsProvider.java#L181

Both of those are being reworked to bring them up-to-date with the spec, but that effort is still a couple weeks out.

Bryn Rhodes (Jun 10 2021 at 21:08):

Yes, we should align the $cql and $evaluate operations there, I would think they should behave the same way. I would actually suggest "return" as the name of the expression though in the $cql case, aligning with the FHIR operation name: http://hl7.org/fhir/operations.html#response

Bryn Rhodes (Jun 10 2021 at 21:11):

I will say that one motivation for returning a list of resources as a Bundle rather than a Parameters, is that it provides a way to support paging.

JP (Jun 14 2021 at 14:36):

Another consideration is that you can't represent primitive data types with a Bundle.

Corey Sanders (Jun 21 2021 at 13:25):

I hit a couple things in my implementation of the Library/$evaluate response that I think could be made clearer / improved in the spec. The first was handling of null values and the second was empty lists. For both, I was simply leaving them out of the parameters response, but that was unsatisfying to the end user as it wasn't clear why they were missing. The cqf-ruler converts these to string representations "null" and "[]" and now I'm doing the same thing. This is necessary because the Parameter constraints require at least one of part, resource, or value. I'm not sure there is a better answer, but it rubs me the wrong way to convert an empty list into a string. Regardless, a note in the spec on how to deal with the situations would be useful.

JP (Jun 21 2021 at 18:29):

Because there's no collection/list type for the parameters we ended up needing to define an extension as a marker for something that should be an empty list. It's not yet in the cpg spec but should be arriving soon. Here's an example (this is on the input, but in principle you could do it for output as well):

https://github.com/DBCG/cql-evaluator/blob/master/evaluator.expression/src/test/java/org/opencds/cqf/cql/evaluator/expression/ExpressionEvaluatorTest.java#L264