Using CQL With FHIR
3.0.0-ballot - STU 3 Ballot

Using CQL With FHIR - Downloaded Version null See the Directory of published versions

## Operations

Page standards status: Trial-use | Highlight text changes?

### Index

Operation | Description
--- | ---
CQL CQL | The $cql operation evaluates a CQL expression and returns the result. The operation has a single return parameter that can be of any type to accommodate the possible result types of a CQL expression.
CQL Group Evaluate | Evaluates the membership criteria of a group definition returns the results as an actual Group resource. The Group is expected to use the characteristicsExpression extension to define membership criteria.
CQL Library Evaluate | Evaluates the contents of a library and returns the results as a Parameters resource. Results are returned as described in the FHIR Type Mapping section of the conformance page of this implementation guide. Unless specific expressions are named, the operation will provide the results for all public top-level expression declarations in the library. Use the includePrivate parameter to indicate that private expressions should be included as well.
CQL Resolve Namespace | Resolves the given namespace name to a namespace uri. For libraries published in FHIR NPM packages, the namespace name corresponds to the FHIR NPM packageId (and the `packageId` element of the ImplementationGuide resource), and the uri corresponds to the base canonical for the FHIR NPM package. For example, the namespace name for the Using CQL With FHIR implementation guide (this IG) is `hl7.fhir.uv.cql`, and the namespace uri is `http://hl7.org/fhir/uv/cql`. A package feed is one way to populate this mapping of namespace names to namespace URIs, but it is not the only way. A repository could potentially provide other ways to create this mapping.

### Examples

#### $cql

##### Simple Expression

This example just evaluates the expression `2 + 2`:

    POST [base]/$cql

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "expression",
        "valueString": "2 + 2"
      }]
    }

The expected response for this operation is:

    HTTP/1.1 200 OK

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "return",
        "valueInteger": 4
      }]
    }

##### Expression With Parameters

This example evaluates the expression `2 + X` where `X` is a parameter passed in the `parameters` parameter with the value of 2:

    POST [base]/$cql

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "expression",
        "valueString": "2 + X"
      }, {
        "name": "parameters",
        "resource": {
          "resourceType": "Parameters",
          "parameter": [{
            "name": "X",
            "valueInteger": 2
          }]
        }
      }]
    }

The expected response for this operation is:

    HTTP/1.1 200 OK

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "return",
        "valueInteger": 4
      }]
    }

##### Expression Referencing a Library

This example evaluates the expression `Count(PE."Blood Glucose Observations")`, where `"Blood Glucose Observations"` is defined in the `ParameterExample` library and made available to the expression through the `library` parameter:

    POST [base]/$cql

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "expression",
        "valueString": "Count(PE.\"Blood Glucose Observations\")"
      }, {
        "name": "subject",
        "valueString": "Patient/example"
      }, {
        "name": "parameters",
        "resource": {
          "resourceType": "Parameters",
          "parameter": [{
            "name": "GlucoseThreshold",
            "valueQuantity": {
              "value": 8.0,
              "code": "mg/dL",
              "system": "http://unitsofmeasure.org"
            }
          }]
        }
      }, {
        "name": "library",
        "part": [{
          "name": "url",
          "valueCanonical": "http://hl7.org/fhir/uv/cql/Library/ParameterExample"
        }, {
          "name": "name",
          "valueString": "PE"
        }]
      }]
    }

The expected response for this operation is (assuming a Patient with id `example` and 4 Blood Glucose Observations over 8.0 'mg/dL'):

    HTTP/1.1 200 OK

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "return",
        "valueInteger": 4
      }]
    }

NOTE: The parameter name may be qualified by the identifier used for the library to explicitly indicate that the parameter value should only be bound to the parameter in that library, for example:

      }, {
        "name": "parameters",
        "resource": {
          "resourceType": "Parameters",
          "parameter": [{
            "name": "PE.GlucoseThreshold",
            "valueQuantity": {
              "value": 8.0,
              "code": "mg/dL",
              "system": "http://unitsofmeasure.org"
            }
          }]
        }
      }, {

The local identifier `PE` is specified by the `library.name` part.

#### Library/$evaluate

This example evaluates the `ParameterExample` library

    POST [base]/Library/ParameterExample/$evaluate

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "subject",
        "valueString": "Patient/example"
      }, {
        "name": "parameters",
        "resource": {
          "resourceType": "Parameters",
          "parameter": [{
            "name": "GlucoseThreshold",
            "valueQuantity": {
              "value": 8.0,
              "code": "mg/dL",
              "system": "http://unitsofmeasure.org"
            }
          }]
        }
      }]
    }

The expected response for this operation is (assuming a Patient with id `example` and 4 Blood Glucose Observations over 8.0 'mg/dL'):

    HTTP/1.1 200 OK

    {
      "resourceType": "Parameters",
      "parameter": [{
        "name": "Blood Glucose Observations",
        "resource": {
          "resourceType": "Observation",
          "id": "observation-1",
          ...
        }
      }, {
        "name": "Blood Glucose Observations",
        "resource": {
          "resourceType": "Observation",
          "id": "observation-2",
          ...
        }
      }, {
        "name": "Blood Glucose Observations",
        "resource": {
          "resourceType": "Observation",
          "id": "observation-3",
          ...
        }
      }, {
        "name": "Blood Glucose Observations",
        "resource": {
          "resourceType": "Observation",
          "id": "observation-4",
          ...
        }
      }]
    }

NOTE: The parameter name may be qualified by the library name to explicitly indicate that the parameter value should only be bound to the parameter in that library, for example:

      }, {
        "name": "parameters",
        "resource": {
          "resourceType": "Parameters",
          "parameter": [{
            "name": "ParameterExample.GlucoseThreshold",
            "valueQuantity": {
              "value": 8.0,
              "code": "mg/dL",
              "system": "http://unitsofmeasure.org"
            }
          }]
        }
      }, {