Quality Measure Implementation Guide, published by HL7 International / Clinical Quality Information. This guide is not an authorized publication; it is the continuous build for version 2.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-cqm/ and changes regularly. See the Directory of published versions

Using CQL

This topic discusses the use of Clinical Quality Language (CQL) to provide computable and/or executable representation of the various criteria of a measure through the expression-valued elements of the Measure resource. The CQLMeasure and ELMMeasure profiles define the expectations for measures that make use of CQL and/or ELM. Support for the use of other expression languages is possible, but is out of scope for this implementation guide.

Measures that use CQL do so with libraries to contain the logic used to define the various criteria of the measure. CQL libraries are used in accordance with the Using CQL With FHIR (UCWF) implementation guide, as well as additional conformance requirements specific to the use of measures, as detailed in the following sections.

For the convenience of IG readers, the conformance requirements from the Using CQL with FHIR Implementation Guide are restated below; however, the Using CQL with FHIR IG remains the authoritative source.

The Conformance Summary Table lists the conformance sections in this implementation guide and indicates which of them further constrains the requirements defined by the UCWF IG. The table also provides direct links to the corresponding conformance statements.

Table 4-1: Conformance Summary Table

Libraries

Consistent with the UCWF IG, Measures that make use of CQL use Libraries.

Conformance Requirement 4.1 (Library Usage):

For example:

library EXM146 version '4.0.0'

Snippet 4-1: Library line from EXM146.cql

Library Versioning

Consistent with the UCWF IG, this IG recommends an approach to Library Versioning used within Measures to help track and manage dependencies. The approach recommended here is based on the Semantic Versioning Scheme.

Conformance Requirement 4.2 (Library Versioning):

For example:

library EXM146 version '3.0.0'

This would indicate the first major version of the EXM146 library. A minor change could be released by incrementing the minor version:

library EXM146 version '3.1.0'

And a major change could be released by incrementing the major version, and resetting the minor version: Minor changes are expected to retain backwards-compatibility, but may introduce new features and functionality, while patch changes are expected to retain forward and backwards-compatibility, and may only be used to fix issues.

library EXM146 version '4.0.0'

Snippet 4-2: Library line from EXM146.cql, the fourth major version.

Nested Libraries

Consistent with the UCWF IG, this IG allows measures to use Nested Libraries. However, this IG requires that all expressions referenced from a Measure be included in a single library to ensure that expression identifiers used in the Measure need not be qualified identifiers.

Conformance Requirement 4.3 (Nested Libraries):

For example:

include Common version '2.0.0' called Common

Snippet 4-3: Nested library within EXM146.cql

Library Namespaces

Consistent with the UCWF IG, this IG recommends the use of Library Namespaces.

Conformance Requirement 4.4 (Library Namespaces):

For example, the following library declaration illustrates the use of a namespace:

library CMS.Common version '2.0.0'

Snippet 4-4: Library namespace

Data Model

CQL can be used with any Data Model.

Conformance Requirement 4.5 (CQL Data Model):

For example:

using FHIR version '4.0.1'

Snippet 4-5: Data Model line from EXM146.cql

For additional information on conformance requirements for the use of Model Information as part of FHIR Knowledge Artifacts that make use of CQL, reference the Using CQL with FHIR IG's section on Using ModelInfo

Code Systems

Consistent with the UCWF IG, Code Systems referenced within CQL expressions make use of the codesystem declaration in CQL.

Conformance Requirement 4.6 (Code System Specification):

For example:

codesystem "SNOMED CT:20240901": 'http://snomed.info/sct'
  version 'http://snomed.info/sct/731000124108/version/20240901'

Snippet 4-6: codesystem definition line from Terminology.cql.

Representation in a Library

The representation of codesystem declarations in a Library is discussed in the Terminology topic of this IG.

Value Sets

Consistent with the UCWF IG, Value Sets referenced within CQL expressions make use of the valueset declaration in CQL.

Conformance Requirement 4.7 (Value Set Specification):

For example:

valueset "Acute Pharyngitis": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011'

Snippet 4-7: ValueSet reference from EXM146.cql

The canonical URL for a value set is typically defined by the value set author, though it may be provided by the publisher as well. For example, value sets defined in the Value Set Authority Center and exposed via the VSAC FHIR interface have a base URL of http://cts.nlm.nih.gov/fhir/. This base is then used to construct the canonical URL for the value set (in the same way as any FHIR URL) using the resource type (ValueSet in this case) and the id (the value set OID in this case). Note that the canonical URL is a globally unique, stable, version-independent identifier for the value set. See Canonical URLs in the base FHIR specification for more information.

The local identifier for the value set within CQL should be the same as the name of the value set in the Value Set Authority Center (VSAC). However, because the name of the value set is not guaranteed to be unique, it is possible to reference multiple value sets with the same name, but different identifiers. When this happens in a CQL library, the local identifier should be the name of the value set with a qualifying suffix to preserve the value set name as a human-readable artifact, but still allow unique reference within the CQL library.

For example:

valueset "Acute Pharyngitis (1)": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011.1'
valueset "Acute Pharyngitis (2)": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.102.12.1011.2'

Snippet 4-8: ValueSet declarations for different value sets with the same name

Note carefully that although this URL may be resolvable for some terminology implementations, this is not necessarily the case. This use of a canonical URL can be resolved as a search by the url element:

GET fhir/ValueSet?url=http%3A%2F%2Fcts.nlm.nih.gov%2Ffhir%2FValueSet%2F2.16.840.1.113883.3.464.1003.102.12.1011.1

Snippet 4-9: FHIR API query to retrieve a value set by its canonical identifier using the url search parameter

Value Set Version

Consistent with the UCWF IG, Value Set Version information is not required to be included. As a best-practice, terminology versioning information is specified externally using a version manifest. However, if versioning information is included, it must be done in accordance with terminology usage specified by FHIR.

Conformance Requirement 4.8 (Value Set Specification By Version):

For example:

valueset "Encounter Inpatient SNOMEDCT Value Set":
   'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.666.5.307|20260210'

Snippet 4-10: ValueSet definition from Terminology.cql.

This is a version-specific value set reference, and can be resolved as a search by the url and version elements:

GET fhir/ValueSet?url=http%3A%2F%2Fcts.nlm.nih.gov%2Ffhir%2FValueSet%2F2.16.840.1.113883.3.666.7.307&version=20160929

Snippet 4-11: FHIR API query to retrieve a value set by its url and version

Value Set Expansion

Measures that make use of CQL must do so in accordance with Value Set Expansion as described in the UCWF IG.

Conformance Requirement 4.9 (Value Set Expansion):

Representation in a Library

The representation of valueset declarations in a Library is discussed in the Terminology topic of this IG, consistent with the Representation in Narrative topic in the UCWF IG.

String-based Membership Testing

Consistent with the UCWF IG, this implementation guide recommends against the use of string-based membership testing.

Conformance Requirement 4.10 (String-based Membership Testing):

Codes

Consistent with the UCWF IG, CQL used with Measures can make use of direct-reference codes.

Conformance Requirement 4.11 (Direct-reference Codes):

For example:

code "Venous foot pump, device (physical object)": '442023007' from "SNOMED CT"

Snippet 4-12: code definition from Terminology.cql.

Representation in a Library

The representation of code declarations in a Library is discussed in Terminology of this IG, consistent with the Representation in Narrative topic in the UCWF IG.

UCUM Best Practices

This implementation guide recommends the UCUM Best Practices found in the UCWF IG.

Concepts

Consistent with the UCWF IG, CQL used with Measures may make use of the CQL concept declaration, but care must be taken to ensure that it is not used as a surrogate for proper value set definition.

Conformance Requirement 4.12 (Concepts):

Library-level Identifiers

Consistent with the UCWF IG, CQL used by Measures should use descriptive and meaningful library-level identifiers, as discussed in the Library-level Identifiers topic

Conformance Requirement 4.13 (Library-level Identifiers):

Data Type Names

Consistent with the UCWF IG, CQL used by Measures must refer to Data Type Names as dictated by the CQL specification, as well as the Data Models in use. For FHIR-based quality measures using QI-Core profiles, these will be the author-friendly identifiers for the QI-Core profiles.

Conformance Requirement 4.14 (Data Type Names):

For example:

define "Flexible Sigmoidoscopy Performed":
  [Procedure: "Flexible Sigmoidoscopy"] FlexibleSigmoidoscopy
    where FlexibleSigmoidoscopy.status = 'completed'
      and FlexibleSigmoidoscopy.performed ends 5 years or less on or before end of "Measurement Period"

Snippet 4-13: Expression definition from EXM130.cql

Procedure is the name of the model data type (FHIR resource type) in this example.

Element Names

Consistent with the UCWF IG, CQL used by Measures must refer to Element Names as dictated by the CQL specification, as well as the Data Models in use.

Note that when FHIR and FHIR IGs are used as the data model, the term "element" is synonymous with "attribute". Some data models, such as QDM, use the "attribute".

Conformance Requirement 4.15 (Element Names):

Examples of elements (i.e. attributes) conforming to Conformance Requirement 4.15 are given below. For a full list of valid names of attributes for a data model, refer to an appropriate data model specification such as QI-Core.

period
authoredOn
result

Snippet 4-14: Example element names

Aliases and Argument Names

Consistent with the UCWF IG, CQL used by Measures must follow conventions for naming of Aliases and Arguments. In addition, note that aliases should not be the same as any other identifiers in scope to avoid potential confusion.

Conformance Requirement 4.16 (Aliases and Argument Names):

For example:

define "Encounters During Measurement Period":
    "Valid Encounters" QualifyingEncounter
        where QualifyingEncounter.period during "Measurement Period"

define function "ED Stay Time"(Encounter "Encounter"):
    duration in minutes of Encounter.period

Snippet 4-15: Example alias and argument names

QualifyingEncounter is the alias in this example, while Encounter is the argument name.

Library Resources

Inclusion of CQL content used within quality measures is accomplished through the use of Library Resources as described by the Using CQL With FHIR implementation guide. These libraries are then referenced from Measure resources using the library element. The content of the CQL library is included using the content element of the Library. Conformance requirements for Library resources included with Measure content are discussed in the Related Documents topic of this IG.

Patterns

Additional guidance and best-practices for the use of CQL in measures can be found in the Patterns topic of the Using CQL With FHIR implementation guide, including guidance on:

• Profile-informed authoring
• Use of terminologies
• Time-valued quantities
• Missing information
• Negation in FHIR

Translation to ELM

The use of Expression Logical Model (ELM) as a basis for sharing logic is discussed in the Using ELM topic of the Using CQL With FHIR implementation guide, including guidance on:

• Inclusion of ELM content in measure packages
• Recommended translator options
• Specifying and exchanging translator options
• Determining ELM suitability based on context