Back to top

Clinical Quality Language (CQL) Qs&As

Why CQL?

How does Clinical Quality Language (CQL) simplify more than other traditional query languages?

CQL has dedicated constructs for the clinical domain, native support for intervals, and high-level phrasing around temporal relationships. This allows for as close to natural language expressions as possible without ambiguity.

What is the driving benefit of Clinical Quality Language (CQL) in electronic clinical quality measures (eCQMs) and does it justify extensive vendor resources to re-write parsing tools?

CQL implementation is designed to address many of the issues encountered with previous eCQM specifications, using Quality Data Model (QDM)-based logic. It allows for increased precision (reduced ambiguities) and improved specificity, provides the ability to share between decision support rules and quality measures, and improves the ease of building language processing applications. CQL-based eCQMs are intended to provide as much opportunity for automated interpretation as possible. QDM-based logic measures have often been manually translated for implementation, which results in ongoing costs as measure specifications are updated annually. While programmatic implementation and interpretation of CQL-based eCQMs has an initial cost, that cost is then significantly reduced for ongoing maintenance, as systems will only have to ingest any updated specifications.

To learn more, refer to the Benefits of CQL.

Reusability was part of the goal, but also for ease in implementation. CQL's use of libraries enables sharing of logic expressions, definitions, functions, and other declarations between different measures and clinical decision support rules and provides the same language for data from different models.

Reusability was part of the goal, but also for ease in implementation. CQL's use of libraries enables sharing of logic expressions, definitions, functions, and other declarations between different measures and clinical decision support rules and provides the same language for data from different models.

Is Clinical Quality Language (CQL) just another way to express measure functions, or does it run somewhere? How do we actually use it against a database to generate results?

CQL is designed to enable the description and distribution of electronic clinical quality measures (eCQMs), but it also can be a basis for evaluation. There are at least two open source engine implementations of CQL that evaluate the measures and supporting logic. Refer to the CQL for Implementers presentation for additional guidance.

JavaScript Open Source Engine

Java Open Source Engine

What is CQL?

How does Clinical Quality Language (CQL) compare to Drools and is there any sample available for CQL to Drools conversion?

Drools is a production rule language, whereas CQL is a functional language designed for expressing queries. Translators have been written to translate CQL to Drools, but they are not open source. Tooling exists to aid the translation of CQL to any target format in both the Java and .NET platforms. There are no publicly available examples. However, a pilot in the Clinical Quality Framework (CQF) initiative built a translator from CQL to Drools.

Is the Clinical Quality Language (CQL) Author's guide part of the Health Level Seven International (HL7) documentation? Or where can this be accessed?

Yes, it's part of the CQL specification available on the HL7  website.

Libraries in CQL

What is a library? Does it import something from another measure?

A Clinical Quality Language (CQL) library is text document (.cql, .xml, and .json) that contains CQL expressions, definitions, functions and other declarations that can be used across measures. Each electronic clinical quality measure (eCQM) contains a primary library that defines the criteria used by the populations of the measure. The Health Quality Measure Format (HQMF) document references this library and defines the populations by identifying which expressions in the CQL library define each population (e.g., Inpatient Encounter, terminologies). Measures may include references to a shared library, which can be either referenced throughout a single measure or across different measures (and even clinical decision support rules) to share definitions and functions like "Hospitalization". This library sharing minimizes efforts both with measure implementation and development.

For more information on libraries, refer to the Using Libraries to Shared Logic section of the CQL Implementation Guide.

What's the purpose of the library02? Is this something you're creating for reuse in other measures?

Measures may include references to a shared library, which can be either referenced throughout a single measure or across different measures (and even clinical decision support rules) to share definitions and functions like "Hospitalization". This library sharing minimizes efforts both with measure implementation and development.

For more information on libraries, refer to the Using Libraries to Shared Logic section of the Clinical Quality Language (CQL) Implementation Guide and the Clinical Quality Language (CQL) Style Guide.

There are also at least two open source engine implementations of CQL that evaluate the measures and supporting logic.

JavaScript Open Source Engine

Java Open Source Engine

CQL Implementation

Do you see Clinical Quality Language (CQL) implementation impacting how vendors write their code to extract the data elements?

It depends on the degree to which vendor’s existing code evaluates logic. In Quality Data Model (QDM), the data elements and the logic to write queries with them are specified together, making a clean separation between those two functions difficult, and preventing them from evolving at different rates. A primary design goal of CQL is to enable that separation at the specification level, and the reason for the approach taken of moving only the logic portion to CQL while retaining the QDM data model representation was to allow vendors to pivot their architectures as well. If a given architecture already drew a line between the data access layer and the logic evaluation, that architecture will be less impacted by this change than one that implemented the logic and retrieval together.

What data set is sitting behind your Clinical Quality Language (CQL) execution? Is it hitting a relational database, JavaScript Object Notation (JSON) flat file?

CQL is designed to allow logic to be written against any data model. The specification defines an abstract data access layer that is responsible for retrieving data from the underlying systems and that layer can provide access via a traditional relational database system or JSON flat files, whatever is appropriate for the environment. For more information, refer to the CQL presentation Training for Measure Implementers about the implementation and design of CQL, and how it enables use of the same language across different models and platforms.

Referring to the example that uses the code of each component within a Diagnostic Study to identify different results, would this mean an additional setup/implementation will be required for healthcare systems to 'map' to these additional codes around a newly created component 1 or component 2?

If there is a need to distinguish different results that have the same types of values, then yes, there would need to be some way to map that content from the source system. However, for cases that do not need to distinguish different results (e.g., because the result values are pre-coordinated, so no two components could have the same result value), then the code layer can be ignored. It depends on the use case. The structure and logic support both approaches. You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

Is blood pressure identified as an observation or as a component of an observation?

For blood pressure, there is a physical exam result or components result and the challenge depends on what you're looking for. It is a single observation, but it depends on how it is recorded.

Temporal Operators

Where can I find more detailed description on the temporal operators used by Clinical Quality Language (CQL)?

CQL Specification, available from Health Level Seven International (HL7), has a complete description of all the operations and functions available in CQL. Temporal Operators are listed in the Table of Contents under the Operations section.

In the example of the QDM documentation illustrating the Cumulative Medication Duration calculation, what if the first date is only at the day level but the second level precision is at the time level, do you still end up with an indecision?

The engines do all the calculations so the lowest value of the less precise to the highest possible value of the less precise and they do the duration calculation between those and that gives them the result as an interval. In the example below, it would calculate from the earliest possible time, midnight, and the latest possible time, 11:59 PM, on the first date, giving you the same result. In general, it is okay for the format to be different between the two days. The actual result will be an uncertainty.

Date Calculations

To estimate due date, do you take the return of a record, within physical exam performed estimated due date codes that would have access to all the actual fields and cast it to datetime?

Yes. You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

When define “gestational age at birth”: 280 – (days between “Estimated Due Date” and “Time of Delivery”) div 7 is entered into the Measure Authoring Tool (MAT), is it entered as a function or a definition?

In this expression, it is entered as a definition, but you could also define a gestational age at birth function.

define "Estimated Due Date":
  Last( ["Physical Exam, Performed": "Estimated Due Date"] Exam sort by start of        
  ).result as DateTime 

define "Gestational Age in Days at Birth":
  (280 - (duration in days between "Estimated Due Date" and "Birth Date")) div 7 

You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

If the Enc1 is in June, the previous one is still in the measurement period. Could you move the age to separate statement instead of a where?

Yes, the age criteria is independent of the other conditions here, so it could be moved to a separate definition, especially if the intent was to reuse that component in other definitions.

Review the full expression in the Clinical Quality Language (CQL) Formatting and Usage Wiki.

When using 'within' to make a date range clearer, does that mean the 60 days, for example, can be counted on either side?

Yes, within 60 days can be before or after.

For the glucocorticoid dosage expression, is using Date appropriate in place of DateTime?

Glucocorticoid dosage expression:
define function "Glucocorticoids Dosage Per Day"(glucocorticoids List<Tuple {
  code Code,
  daysInPeriod List<DateTime>,
  dailyDosage Quantity

Yes, in version Clinical Quality Language (CQL) version 1.3, the Date type can be used for the daysInPeriod argument (i.e. List<Date> instead of List<DateTime>).

Regarding estimated due date definition – how can we be sure it’s the last physical exam we’re interested in. Mothers can have multiple babies over a period of time so how do we know which baby it is associated with on the mother’s record? For example, if a mother has 3 pregnancies but we want to reference the 2nd pregnancy, how do we link this last due date in the second pregnancy to the mother's record?

This is a case of retrospective data. It might be possible to indicate a one-year time period prior to the delivery date of the referenced pregnancy. One might need to seek guidance from the American College of Obstetrics and Gynecology (ACOG) to get a definition of due date. Regardless, if the expectation is to perform a context-based query, the patient record and the related person might have to exist at the same time.

CQL logic calculates an interval using both days and months. The specific line of code in question refers to: FirstIndexAssessment.authorDatetime where we can use a combination of months and days. For this line of code, are leap years accounted for if you use 14 months?

No, because months are still by calendar year too. If you had gone through February in 2012, you would have gotten 29 days. In order to avoid the issue with leap years, you should not combine months and days and only use days to avoid this variability.

In the example of the QDM documentation illustrating the Cumulative Medication Duration calculation, if the second date is prior to the first date, does that always get to negative? Does this uncertainty play into that calculation?

Yes, if the second date is before the first date then you will get a negative number out of it. You will still get the same number. It would just be in the other direction.

Using the DifferenceInDays example below: Is this the same as calendar days? Would the DurationInDays give you the uncertainty result or would it be different in this situation?

define DifferenceInDays: difference in days between @2017-01-01T22:00:00 and @2017-01-02T02:00:00 // 1; define DifferenceInDays: duration in days between @2017-01-01T22:00:00 and @2017-01-02T02:00:00 // 0

The distinction between Difference and Duration is that Difference is counting the boundaries. You can still get uncertainty in Difference calculations but note that Difference is counting the number of boundaries crossed. In this example, DifferenceInDays is 1 because midnight was crossed once but DurationInDays is 0 because 24 hours have not passed. Note that both Difference and Duration calculations can give you uncertainty but Difference is less sensitive to the time than Duration.

Time Calculations

To compare a timestamp and relevant Period, is the comparison based on the start or end of the period?

It depends whether you are asking for a before or after relationship. If you say, “timestamp before period”, then it’s based on the start of the period, but if you say, “timestamp after period”, then it’s based on the end of the period.

How are time durations calculated in Clinical Quality Language (CQL)?

Time durations in CQL are always in terms of a single duration. If it was necessary to say 32 weeks and one day, you would define it in days (or use addition to add 32 weeks + one day). Refer to the Electronic Clinical Quality Measure (eCQM) Logic and Implementation Guidance document for more details.

Explain why, if the timing is less than 30 days, 29 days is used in the Clinical Quality Language (CQL) expression?

Because the timing phrase in CQL 1.1 doesn’t have a way to say, “less than 30 days”, only “29 days or less”. As of CQL 1.2 the timing phrase supports exclusive comparison, so the comparison can be "less than 30 days."

For an encounter with lab test performed during the encounter, is &lt;during&gt; the appropriate comparator?

Potentially no. A more clinically relevant example can use <ordered during> the encounter relevant period if that element is available.

Referring to CMS52v7, does the laboratory test always have a relevant period?

It does. It also has a resultDatetime, the time the result was actually reported. The authorDatetime is used to provide the negation time when representing a laboratory test not performed, but resultDatetime is used to indicate when it became available or posted and the relevantDatetime is used for the physiologic time, when it was drawn. There are some specimens that are obtained over a period of time.

With regard to authorDatetime, if that’s the time it’s entered into the clinical software then what happens when someone goes back to edit it? Is it the last modified time or the original creation time and do we have a way of handling that?

We’re not sure as that has not come up before. There’s an amended time, which would still be the recorded time, so it may depend on your use case. The relevantDatetime would still be the dispense time. Quality Data Model (QDM) doesn’t say how to handle it, but we may want to specify if it was the original time or amended time – we’d likely have to define it.

Expression Logical Model (ELM)

For execution, what is the advantage of using Expression Logical Model (ELM) versus the ANother Tool for Language Recognition (ANTLR) parse tree?

The ANTLR parse tree will be a direct representation of the input Clinical Quality Language (CQL). You will have to do type verification and type inference and operator resolution in order to support that type verification. You would also have to do the implicit conversions and generic type extension. There are a lot of things that CQL supports, higher level constructs like timing phrases that are translated into a representation in ELM that is focused on implementation so that you don’t have to worry about those pieces within ELM. There is nothing that says you couldn’t do all that yourself but for implementation, using ELM takes each of those pieces off an implementer’s plate. Individually each of those aren’t terribly difficult but when you put them all together and add them all up, together with the fact that it’s maintained as a part of this whole infrastructure, it’s a significant advantage to be able to use the ELM directly rather than have to start directly from a parser. Refer to the CQL for Measure Developers presentation for additional guidance.

If both Clinical Quality Language (CQL) and Expression Logical Model (ELM) are available, is it possible to build parsing logic around the CQL instead of the ELM? Is that not recommended?

Yes, it is possible and we do provide a CQL ANother Tool for Language Recognition (ANTLR) grammar. The ANTLR tooling is great. It provides easy to use generated visitor and/or listener code depending on which mode you use it in. In fact the CQL-ELM translator is implemented using a generated ANTLR visitor. The advantage is that the ELM representation is focused on implementation and machine processing, as opposed to the CQL representation, which is focused on high level, human readable, and natural language expression of timing, and clinical concepts. Rather than CQL representation, which is focused on high level representation that’s human readable and natural language expression of timing, and clinical concepts. Refer to the CQL for Measure Developers presentation for additional guidance.

Do you imagine that Expression Logical Model (ELM) would be used to exchange electronic clinical quality measure (eCQM) data between organizations, or Clinical Quality Language (CQL) which is more human readable?

That depends on the target of the sharing. I agree that if your intent is to share between clinicians or human readers or even eventually integrators, if the readers are human, CQL would be a better way to share that, but if the intent is to automate sharing of that measure definition, then CQL introduces another level of functionality and the ELM that is underneath provides an easy way to get to that more machine friendly representation. There is nothing that says you couldn’t share at the CQL level even for integration, it’s a formal language and it supports accurate and computable representation of the measure logic. It’s just that the CQL to ELM translator and that representation provides an easy way to get past all of those traditional hurdles of building a new compiler or interpreter.

Can you speak to the relationship between the Expression Logical Model (ELM) and Health Quality Measure Format (HQMF)?&nbsp; Will ELM be nested inside of an HQMF?

HQMF 1.2 extended the standard in a very simple way to be able to reference an external document. And the way that the CQL-based HQMF Implementation Guide then uses that extension for HQMF is to specify that the logic for the criteria expressed within the HQMF is actually specified in the ELM document. That document is a library just like the example ELM library that actually contains the logic and then the HQMF will be the criteria that will actually point to an expression to find in that ELM document. So no, it won’t be nested inside the HQMF, it will just be referenced as a separate document and then each criterion will point to specific expressions within the ELM.

Functions in CQL

Does the logic shown in the example cover a scenario where the patient goes from outpatient status directly to inpatient?

Hospitalization with observation function


Yes, because there would be no observation or Emergency Department (ED) visit. The outpatient visit can be compared to the start of the encounter’s relevant period.

Can the ‘define function’ pattern be used to customize measures where an outpatient visit is not to be considered as an episode of care?

Yes, in that case, you would use the Hospitalization with Observation function rather than the Hospitalization with Outpatient function. In addition, measures that did not consider observation status to be part of the episode of care would continue to use the current Hospitalization function.

What unit is returned in the example provided? Define function 'Arrival and Departure Time' (Encounter 'Encounter, Performed'):

         First(Encounter.facilityLocations Location
                Return start of Location.locationPeriod sort ascending),
         Last(Encounter.facilityLocations location
                Return end of Location.locationPeriod sort ascending)

The interval would return a full Datetime, e.g., the first return would be locationPeriod: 10:30..11:21.

What does the hospitalization function mean?

The Hospitalization function has been considered as an approach to identifying an encounter plus the time immediately prior in the Emergency Department (ED) visit. In a lot of the current hospital measures, they are looking for that pattern because there is an inpatient encounter with an immediately prior ED visit. In previous logic, those cases had to be considered independently. The Hospitalization function gives us the duration, the interval from the start to the end of either the encounter or the immediately prior ED visit. It collapses that logic for determining what the overall duration of the hospitalization is, and by using this function, then we pass an encounter and it tells us from admission to discharge. Note, to determine arrival time within the Hospitalization function requires use of the Encounter, Performed location attribute. Refer to the Clinical Quality Language (CQL) Style Guide for additional guidance.

In the Hospitalization function where it says, “if null,” does it mean that if there is no Emergency Department (ED) encounter, it will start counting from the inpatient encounter?


Using the Hospitalization function, how and where is the encounter defined?

The encounter is passed as an argument to the function, so the logic operates on whatever encounter is passed in.

What is function? What does it do and when should it be used in a measure?

Functions take arguments passed to them and return a value. The Clinical Quality Language (CQL) Style Guide provides more information about best practices and standards for functions. For example, in the case of a Hospitalization function: define “Hospitalization” (Encounter “Encounter, Performed”) singleton from ( [“Encounter, Performed”: “Emergency Department Visit SNOMEDCT Value Set”] EDVisit where EDVisit ends 1 hour or less before start of Encounter ) X  return if X is null then Encounter.relevantPeriod else Interval[start of X.relevantPeriod, end of Encounter.relevantPeriod]

Computation is done with a value of type encounter to find an encounter that ends before the Emergency Department (ED) visit and if it’s not there, return the encounter as a relevant period; otherwise return an interval constructed from the start of the emergency department period to the end of the encounter’s relevant period.

How is hospital arrival time defined?

The definition is included in the Measure Authoring Tool (MAT) Global Common Functions, it’s the start of the first location period for the locations in the encounter, or the immediately prior emergency department encounter if one exists.

There is significant logic involved with looking at dosages and number of doses per day. Is that part of the global library yet?

Not yet. The global library is based on what measure developers identify as being used in enough measures to warrant including in the library.

For the interval function of the example of the QDM documentation illustrating the Cumulative Medication Duration calculation, is it required that the first parameter has to be less than or equal to the second parameter?

Yes, that is true of intervals. In the example below, that would be an error because it’s not a valid interval.

Does Clinical Quality Language (CQL) support a mechanism for randomly picking an item from a list?

The short answer is no. CQL is purposely a deterministic language, so we don't have functions like Random(). This was a design decision in the very earliest phases of language development to ensure that systems could reliably cache intermediate results. Even functions like Today() and Now() are defined deterministically so that they return the same value within any given evaluation session. However, CQL 1.3 introduced the ability to define external libraries. From the perspective of the translator, external definitions are just function signatures; it's up to the engine to resolve external definitions and provide the run-time implementation for them. For engines, this would be fairly straightforward to support, but

• It would tie the CQL that uses the external definitions to engines that understood those externals (reducing portability)
• The Java-based open source engine does support external libraries, but it's not a feature that has been well-tested.

Measure Logic in CQL

When using “with” in the “such that” expression, do you have to put it before all the such that’s or is there a significance to the order?

Each “with” needs a “such that” to describe the relationship of the “with” source to the “primary” source.

You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

What value is returned in risk adjustment? Is it different between Eligible Professional (EP) measures vs. Eligible Hospital (EH) measures?

No, risk adjustment variables can return any value. They are presented in the context of the patient and can return anything. For example, consider this risk adjustment variable definition from the TestRiskAdj_CQL example measure from the Clinical Quality Language (CQL)-based Health Quality Measure Format (HQMF) Implementation Guide (IG)

define "Bilirubin Test": ["Laboratory Test, Performed": "Bilirubin"] L
    with "CABG_Open and Endoscopic During Encounter" C
      such that L.relevantPeriod starts before start of C.relevantPeriod
    with "Encounter Inpatient 365" 
      such that L.relevantPeriod starts during E.relevantPeriod
    where L.result as Quantity > 2 'mg/dL' 

The expression provided will return different types of contraceptives including counseling. Do they need to be listed independently or can a definition be used in the supplemental element?

"Most or Moderately Effective Contraception Provided" Contraception
                Return Contraception.code

Answer: The supplemental data element definition returns the code even though it will, in general, return multiple different types of contraceptives. For each actual instance, the specific code in the reporting system will be returned. In a summary report, these would be aggregated by code. In an individual report, the data for this individual would be returned.

In the Encounter Diagnoses example provided, can 'or' be changed to 'and' and still provide the two diagnoses?

define 'Single Live Birth Encounter or Gestational Diabetes':
    'Inpatient-Encounter” Encounter
           where exists (Encounter.diagnoses Diagnosis
                 where Diagnosis in 'Single Live Birth'
                       or Diagnosis in Gestational Diabetes'

No, because it indicates you want any diagnosis in the inpatient encounter that has a diagnosis code of “Single Live Birth” and “Gestational Diabetes”. The single code cannot satisfy both those requirements at the same time.

For the follow-up Human Immunodeficiency Virus (HIV) visit logic, explain why the not equivalent comparison is not needed and when it could be needed.

It is needed when using the ‘on’ and after’. When using only ‘after’ it would not be needed.

Can the age-based risk factors example be plugged into the Measure Authoring Tool (MAT) or tested with Bonnie? The way Clinical Quality Language (CQL) is structured, the ‘defines’ are listed programmatically.

Yes, the way that 'defines' are listed in CQL allows them to be forward referenced anywhere in the library.

Is flattening part of Clinical Quality Language (CQL)?

Yes. The 'flatten' operator takes a ‘list of lists’ and returns a single list with all the elements of the lists in the input.

What is the best way to specify in Clinical Quality Language (CQL) that a medication was present on admission for an inpatient encounter? There have been conversations recently about a ''presentOnAdmissionIndicator'' for diagnoses in Quality Data Model (QDM) 5.5, but not something equivalent for medications.

This will be documented as "Medication Active at Admission". The Medication, Active must have a relevant period that includes the start date of the encounter. Note also that this is only addressing the simplest case of an inpatient admission. It may need to be expanded to account for an immediately preceding emergency department visit, depending on measure intent. Also note that the Quality Data Model (QDM) specifies relevant period start for a Medication, Active as the time when the patient is first known to have been taking the medication. Whether this is captured by the electronic health records is a question for investigation.

How do you represent Structured Query Language (SQL) joins in Clinical Quality Language (CQL)?

In Structured Query Language (SQL), joins are used to combine data from multiple tables. In Clinical Quality Language (CQL), the focus is on simplest possible expression of single-source queries. But multi-source queries are possible as well. Some examples:

CQL code

Note, there is an open source project that allows you to translate CQL to SQL. It was a pilot project in the Healthe-Decisions initiative. It is available on the Clinical Quality Framework Repository. It’s a little outdated, but the structure is there.

You can have a native environment that runs SQL directly. There are vendor systems that can do this and three open source implementations of a SQL engine that runs SQL directly. On the GitHub Wiki, there is a community projects page that has links to all of those open source implementations.

In discussing CLONE Hospital Harm – Pressure Injury Draft 0.00, the measure assesses the proportion of inpatient encounters for patients 18 years and older upon admission and the presence of stage 2, 3, or 4 deep tissue pressure injury or unstageable deep tissue pressure injury. This measure documents deep tissue pressure injury upon arrival or 24 hours after admission. (May be a need to create value sets for anatomical sites to support this measure.) The measure code will be written (continued in the answer):

The measure code will be written:

CQL Code

The primary issue seems to be a need to relate a diagnosis that is indicated as present upon arrival with an active Diagnosis record and be able to reliably ensure they are the “same” diagnosis. How do you accomplish this?

Answer: This is done by comparing the codes of the diagnosis to the diagnosis as seen upon arrival. The diagnosis code is written as:

CQL Code

In the example measure on Pressure Injury, how would the code for diagnosis display the information if the diagnosis appears in both the Encounter diagnosis and in the Present on Admission indicator and a diagnosis record? It seems that you would say there is a diagnosis record and it has the same code as the diagnosis code in the encounter diagnosis.

When you’re talking about a pressure ulcer like this, the anatomical location is not necessarily in a pre-coordinated SNOMED CT term, it’s just pressure ulcer, but there are some International Classification of Diseases (ICD)-10 codes that have an anatomical location attached. The Encounter diagnosis attribute includes some components, but it doesn’t specify anatomical location as a component.  However, the Clinical Quality Language (CQL) expression could reference a diagnosis with anatomical location = right (or left) and that could be used to reference the Encounter diagnosis. Thus, the CQL can allow further definition of the Encounter diagnosis to address laterality, as needed, for this measure. Alternatively, you could use the pre-coordinated code (i.e., ICD-10 with location attached).

You can incorporate a definition for Pressure Injury Diagnosis and would name the anatomical location site with Pressure Injury Diagnosis as part of the New Pressure Injury measure.

CQL Code

CMS826v0 - Hospital Harm - Pressure Injury – How would you express an encounter with a new harmful pressure injury?

Paraphrased description of the measure: This measure assesses the proportion of inpatient encounters of patients 18 years of age or older at admission, who have a pressure ulcer present on admission (POA) and suffer the harm of developing a new pressure injury (stage 2, stage 3, stage 4, deep tissue pressure injury, or nonstageable pressure injury) subsequent to admission. The measure does not consider the number of new pressure injuries per encounter, it is only concerned about a new pressure injury in patients admitted with an existing pressure injury. Thus, the measure must identify a pressure injury that is POA and a new pressure injury in a different anatomical location identified at least 24 hours after arrival. This new harmful pressure injury’s prevalence period overlaps, but starts after an existing pressure ulcer.

For this particular encounter, the measure is looking for the presence of an Encounter diagnosis consistent with codes in a specific value set ‘diagnosis: Pressure Ulcer Stage’ with a ‘Pressure injury stage’ (e.g., containing values: stage 2, stage 3, stage 4, nonstageable pressure ulcer, pressure injury of deep tissue). This approach will set up an alias for pressure injury POA where that diagnosis (harmful pressure injury) has a POA indicator. Next, we are looking for a ‘harmful pressure injury’ during the hospitalization period where the anatomical location site is not the same as the one that was POA and it starts more than 24 hours after the start of hospitalization.

Option 1 (using ‘let’):

Option 1 (using ‘let’)

Option 2 (using a ‘with’ statement in place of the ‘let’ and include a ‘such that’ statement, only if there is one condition):

Option 2 (using ‘with’ and ‘such that’)

The difference between the ‘with’ and ‘let’ is that the ‘let’ introduces “PressureInjuryPOA” so you can talk about it in multiple places throughout the query, whereas the ‘with’ only lets you talk about it within ‘such that’. If you need to talk about it in a subsequent ‘with’ or ‘where’ then the ‘let’ permits you to repeatedly talk about the same expression. The ‘with’ only references the Pressure Injury POA within the ‘such that’ condition. The scope of the ‘let’ variable goes on after the initial ‘where’ or filtering that is done. As far as performance, expressing it as a ‘with’ or a ‘let’ depends on how the underlying implementation decides to deal with it because it might translate into a ‘join’ in a structured query language database environment vs. an ‘apply’. It is up to the optimizer of the target system to determine how best to run it.

Regardless of whether the expression uses ‘let’ or ‘with’, the following issue may represent a challenge in testing and evaluating this measure. A potential challenge with this approach is the terminology used when recording an anatomical site. For example, if the anatomical location site is recorded as hip ulcer, but didn’t specify laterality (right or left) and then a new hip ulcer developed on the other hip, the straight code comparison here wouldn’t differentiate the two. Conversely, if the existing ulcer code indicates “greater trochanter,” and a separate reference to the same pressure ulcer used the code “hip,” the result might suggest there are two pressure ulcers when only one exists. Thus coding variation could lead to missing a new pressure ulcer or over-counting an existing pressure ulcer as newly developed. A possible solution would be to develop very specific value sets that distinguish the encounter.

For the measure CMS646, Bladder Cancer (, how do you express specific references for bladder cancer and combine several definitions into one?

The clinical workflow presented by the measure developer is that bladder cancer is diagnosed and then the tumor is staged and coded with either Ta HG (noninvasive papillary carcinoma – high grade), Tis (carcinoma in situ), or T1 (tumor has spread to the connective tissue). Bacillus Calmette-Guerin (BCG) is the standard immunotherapy drug (regardless of tumor stage) for bladder cancer and will be administered up to six times, but for this measure we are only interested in the first administration. The intent of this measure is to assure that staging occurs prior to the first BCG administration. The measure only looks at the first BCG administration, not at BCG dose/frequency/etc., even if the staging occurred up to six months prior; we are interested in the first encounter after the bladder cancer diagnosis within the measurement period. Note, the diagnosis must overlap the measurement period. The first BCG given is associated with the staging and obviously the encounter. We are specifically checking that the BCG administered happened after the staging.

The suggested approach is to look for any qualifying encounter that occurred during the submission period and we define Qualifying Encounter, Initial Population, Bladder Cancer Staging, Bladder Cancer Diagnosis, and First BCG Administered as:

Qualifying Encounter:

Qualifying Encounter Expression

Initial Population:

Initial Population Expression

Bladder Cancer Staging:

Bladder Cancer Staging Expression

Bladder Cancer Diagnosis:

Bladder Cancer Diagnosis Expression

First BCG Administered:

First BCG Administered Expression


  1. Use exists() function to provide Boolean (true/false) results for Initial Population definitions.
  2. Remove singleton from office visit expression since timing requirements addressed by other definitions.
  3. Use ~ equivalence function for code but use in() function to Value Set Authority Center object identifiers for tumor staging definition.
For measure CMS111, Median Admit Decision Time to ED Departure Time for Admitted Patients (, we are having a measure observation calculation issue, where some duration calculation results are based on the ending interval (end time of encounter). If the emergency department (ED) encounter does not include the facility location, it should not calculate a 'Visit' encounter for the measure observation time. If the ED facility location departure time is missing, a measure observation time should not be calculated, but in Bonnie this does occur. Is this due to the logic below? Should we add a null clause in the Initial Population to indicate if there is no ED facility location departure time the encounter will not be included?

Median Admit Decision Time to ED Departure Time for Admitted Patients

The measure intent is to capture the median time interval from when the admit decision is made (represented by an AssessmentPerformed.relevantDatetime or by an AdmitOrder.authorDatetime) to when the patient leaves the ED (represented by the end of HospitalLocation.locationPeriod).

Admit Decision Using Assessment Expression

The “EDDepartureTime”(“RelatedEDVisit”(Encounter)) is represented by the end of HospitalLocations.locationPeriod. However, if HospitalLocations.code is present (Emergency Department), but the end of the locationPeriod is missing (null), then the time interval calculation would continue to infinity. If the ED Location EndTime was not noted, the measure performs the calculation until infinity, or the end of time, instead of to zero. To address this calculation issue, the initial encounter is expressed so that it includes an EDEncounter code and is not null for the EDDepartureTime. In this case, the only ones passing through the measure would have an observation measure time.

ED Encounter with Decision to Admit Expression

If an ED visit is followed by an inpatient encounter, it’s safe to assume there’s missing data that wasn’t reported so you could assert that the end of the location period where it isn’t specified is the start of the inpatient encounter that wasn’t specified. Another thing you could do is to introduce a stratification that would detect the cases where EDFacilityLocation doesn’t have an ending date. This is a way to get the measure to indicate how many we’re getting that don’t have an end date documented. The measure observation would still be calculated but the AdmitTime would take place of the EDDepatureTime.

Hospitalization in CQL

Where can I find the hospitalization library?

The hospitalization global common functions can be found on the Clinical Quality Language (CQL) Formatting and Usage Wiki. An example that uses global common functions will be included in a future cooking with CQL session. The appropriate version of MATGlobalCommonFunctions.cql is included with each measure specification zip file.

Occurrences in CQL

How are occurrences used in Clinical Quality Language (CQL)?

CQL takes a different approach to representing what specific occurrences were achieving, namely identifying a specific instance and associating criteria with that instance. Because CQL can describe queries and their results, and then use those results in subsequent operations, specific occurrences are not required to tie the different appearances of a data element together throughout the measure definition. Rather, with CQL, additional criteria are applied to specific instances of a data element by referencing the same expressions. For more information and examples, see the Specific Occurrences topic in the CQL Formatting and Usage Wiki.

CQL-based eCQM Specifications

Are Clinical Quality Language (CQL) specifications defining electronic clinical quality measure (eCQM) measure sets?

The CQL specification itself does not define how measures are to be expressed, it only provides a mechanism to describe logic related to the quality domains of decision support and quality measurement. Additional guidance describing how CQL is used to create measures is provided in the CQL-Based Health Quality Measure Format (HQMF) Implementation Guide (IG), as well as the currently under-development Clinical Quality Framework-on-Fast Healthcare Interoperability Resources Implementation Guide (CQF-on-FHIR IG).

Is there a change to the method of receiving measure specifications from electronic clinical quality measures (eCQMs)?

eCQMs are still distributed using Health Quality Measure Format (HQMF), but the logic involved is contained in separate Clinical Quality Language (CQL) and Expression Logical Model (ELM) documents distributed along with the HQMF and the criteria in the HQMF document reference expressions defined in the CQL/ELM library.

Do the Clinical Quality Language (CQL) changes impact the human readable specifications currently published with each electronic clinical quality measure (eCQM)? If yes, where can we go to understand the changes? Is there an example available that shows current and future?

Yes, the human readable that’s currently part of the Hyper Text Markup Language (HTML) for each measure and uses Quality Data Model (QDM), will actually use CQL now. Measures with CQL are published so you can see the HTML on the Eligible Professional/Eligible Clinician and Eligible Hospital/Critical Access Hospital pages. There are also examples in the Side-by-Side presentations on the CQL Education page. Refer to the Guide for Reading eCQMs for additional guidance.

In the specifications, is it necessary to specify that the boundary is closed or open?

No, the measure specifications don't indicate whether boundaries are closed or open because that is an aspect of the value, not the type. The systems providing the information indicate whether they are giving an interval that has closed or open boundaries.

How does Clinical Quality Language (CQL) capture the concepts of Initial Patient Population or numerator and denominator?

Health Quality Measure Format (HQMF) specifies the population criteria, but instead of defining that within the HQMF as previously executed, it points to CQL. Refer to the CQL-based HQMF Implementation Guide (IG) for examples and the CQL Formatting and Usage Wiki: Specifying Population Criteria.

What is the difference between using definitions vs. parameters when expressing a measure?

Parameters are external values that are provided when the measure is evaluated, whereas definitions are used to organize criteria within the measure.

Is the statement, ''The denominator is always a subset of the initial population, so the criteria entered to define ‘Initial Population’ does not have to be duplicated for define ‘Denominator’'' only true for patient-based measures?

No, it is true for both patient-based and non-patient based measures. However, for non-patient based measures, because the criteria expression has to return the same type as the rest of the measure population criteria, it is often easiest to just reference the “Initial Population”.

Unions in CQL

In the Emergency Department (ED) encounter observation expression, can the union be used with both option 1 (use of an Encounter code to model observation) and option 2 (use of an Encounter facility location to model observation)?

Emergency Department (ED) encounter observation expression The “union” in this question is referring to the common use of unions to bring together encounters from different value sets into a single expression for consideration. With option 1, because the observation status is determined by looking at a facility code, the encounter codes are still used in the way that they are now (e.g., to represent the type of encounter: inpatient, outpatient). With option 2, however, “Observation” is represented as another type of encounter, so you wouldn’t be able to distinguish other types of encounters within Observation.

Does union return a unique code for both diagnosis of asthma and other illness?

As of Clinical Quality Language (CQL) version 1.2, the use of the distinct keyword with unions is not required because duplicates are automatically eliminated by the union.

Would union work with two diagnoses or should each diagnosis be described separately?
Each diagnosis should be described separately. The expression using union won’t work because it will produce results if either one or both diagnoses are present. If the use case requires both, then the “and” expression is required.
Does using have any impact when also using the union to define the numerator? Define “Numerator”: “Encounter With Antithrombotic Therapy” union “Encounter With ED Visit With Antithrombotic Therapy”

Yes, and it depends on whether we are defining a patient-based or encounter-based measure. For an encounter-based measure, what we are returning from all the criteria are lists of encounters. In a patient-based measure, what we are returning from all the criteria is true or false. So, in a patient-based measure you use <exist> to get a list to be true or false. In an episode-based measure, we are returning lists, so we don’t use <exist>.

Value Sets and CQL

Using the example provided, is 'Hepatitis B Immunizations Procedure' as found in the Clinical Quality Language (CQL) library a value set or definition?

In the example

define "Hepatitis B Immunizations or Procedures":
( ["Immunization, Administered": "Hepatitis B Vaccine"]
union ( ["Procedure, Performed": "Hepatitis B Vaccine Administered"] Procedure
return "Immunization, Administered" { authorDatetime: start of Procedure.relevantPeriod }
) ) HepBVaccination

where AgeInDaysAt(HepBVaccination.authorDatetime)>= 1
and AgeInDaysAt(HepBVaccination.authorDatetime)<= 730

Answer: It is a definition. Value set declarations are defined in the CQL header and are local identifiers for value sets stored in a terminology service like the Value Set Authority Center (VSAC). Definitions are defined in the body of the CQL library and specify chunks of logic that can be used throughout the library or within the measure as population criteria.

When developing a new measure and want to use an existing value set, how are specific codes, a subset of the existing value set, pulled out in a new value set?

When referencing only a subset of the codes from an existing value set, this can be done two ways

  • Define another value set with only that code in it
  • Reference a specific code

In general, if the use case clearly identifies a specific code to reference, you can use it as a direct reference code. However, if there are multiple codes necessary, a new value set is needed.

Note that although Clinical Quality Language (CQL) does provide set operations that could be used to compute the subset of a value set using some expressive criteria, performing calculations involving value sets is not recommended for several reasons:

Terminology operations, such as membership, are communicated in the machine-readable file in specific ways that enable implementations to make use of terminology servers. Performing calculations on value sets requires the use of expansion, which is not required for membership testing when that testing is done by the terminology server. As a result, using value sets in calculation would impose an additional implementation burden on vendors consuming the measure.

The definition of terminology is by design a separate aspect of quality measure development. This separation of concerns has multiple benefits, including that the maintenance and governance of value sets can be performed independent of the maintenance and governance of the measures.

Value set definition often involves operations that are specific to the terminologies involved, so there is a great deal of variability in the way that these expressions are represented.

Example can be found in the CQL Formatting and Usage Wiki.

How is terminology maintained? For Example, List of Values (LOVs).

Measure developers maintain and publish terminologies to the Value Set Authority Center (VSAC). They are distributed with measure definitions as part of the overall process. Those value sets are updated not just when the measures are published, but also periodically to capture additional terminology changes.

How do I indicate a change version of the List of Values (LOVs)?

LOV means List of Values and is another name for value sets. However, value set is the appropriate term. The Value Set Authority Center (VSAC) maintains the value set definitions including codes involved and versions of the terminology those codes came from, hence extensions are determined with versioning in mind.

What is the definition of 'mother'? Is this a new value set to represent the mother relationship? I expect the new value set to represent the mother relationship.

The concept 'mother' is managed by the relationship attribute of Related Person and could be represented as a value set. If appropriate, it could also be a direct reference code. Consistency in defining relationships across all eCQMs is ideal.

Queries in CQL

In a query that has a with or without, what is the result type?

The “with” and “without” operations in Clinical Quality Language (CQL) do not change the result type of the query, so it remains "Encounter, Performed". These operators only filter the results based on the presence or absence of a related record (using the “such that” criteria to determine existence). They are equivalent to “semijoin” and “semiminus” in a relational query language.

What is the difference in the query order between the following Encounter with Emergency Department (ED)&nbsp;visit example?&nbsp;

a) Define “Encounter With ED Visit Less Than Two Days”: “Encounter with Ischemic Stroke” E with “ED visit” ED And b) Define “ED Visit Less Than Two Days”: “ED Visit” ED with “Encounter With Ischemic Stroke” E

Query (a) is returning the inpatient encounters, not the ED visits. What should be counted in this measure is inpatient encounters. We are interested in a case where there was a prior ED visit to consider as part of the encounter. Query (b) is returning the ED visits immediately following an inpatient encounter.

You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

We tried to use “Inpatient Encounters” and intersect it with something else, but it would not work. Why is that?

The Intersect operator takes two lists and returns only those elements that are in both lists, so the lists should have the same kinds of values, such as lists of encounters. You cannot intersect encounters and orders.

If you have overlapping depression periods with no end-date in the measurement period, do you get a query with all the diagnoses?

That's correct because when you don't have an end to the prevalence period and it’s characterized with a closed brace, which is typically how they are characterized, then that means it goes to the end of time. So, when we intersect that with the measurement period, we only get the portion of the prevalence period that is entirely within the measurement period. For example, if you have a diagnosis that starts in March and another that starts in April and they both have no end-date then you'll just get one result.

When the “where” clause is used in the example; does it mean that the ‘let…’ statement can only be assigned one line of code?

let procedure: (
        “Total Hip Total Knee Procedure” (QualifyingEncounters) P
        where P.ordinality in “Principal”

No, the “where” clause in a query will not change the result type of the query. You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

I am new to Clinical Quality Language (CQL), how do we run CQL queries - is it against Consolidated Clinical Document Architecture (C-CDA) documents?

CQL can be used with any data model. In the examples in this series we are focused on using the Quality Data Model (QDM), which has a serialization as Quality Reporting Document Architecture (QRDA). QRDA is similar to C-CDA (they are both Health Level Seven International [HL7] V3 standards), but not the same.

Is ‘from’ required when setting up a relationship between more than two sources and ‘with’ when setting up a relationship with only two sources?

Yes, that’s correct, ‘from’ is used to set up a “multi-source” query where you want to be able to talk about more than two sources at once. If you have a “single-source” query, you can use ‘with’ and ‘without’ to establish relationships between the primary source of the query and one other source at a time.

Looking at the solution for the connection of the mother and baby, is the capability for a cross-context query for a related person new to CQL?

Yes, it is new. We would like feedback in order to gain further understanding of the 'operator' and how it is being used.

Is the related person query included in the FHIR Quality Measure Implementation Guide?

In the FHIR Quality Measure Implementation Guide May ballot content there is an example of this use case and we are seeking comments. Terminology is also being worked on within this example. There is nothing specific about this type of query in the base FHIR Clinical Reasoning measure specification.

How should we express the criteria that a Substance Use Disorder (SUD) encounter in the 'identification period' (6 months before through the first 6 months of the measurement period) is considered new if there are no other SUD encounters in the 60 days prior to the encounter, and that for each new SUD encounter, there is a baseline Quality of Life (QOL) assessment in the 14 days on or before the new SUD encounter, and a corresponding follow up QOL using the same assessment tool within 3 to 6 months of the new SUD encounter, and having a SUD encounter within 60 days of the follow up QOL assessment?

For each SUD encounter, there should be a baseline QOL assessment 14 days on or before the new SUD encounter and a follow up QOL assessment using the same QOL tool within three to six months and that had a SUD encounter within 60 days before that follow up QOL assessment, which could take place on the same day as the SUD encounter. Please see the example below of how this query should be expressed.

Example query.

When setting up relationships between multiple sources of data at the same time, what should you expect to see as the return with multi-source queries without specifying a return statement? For example, in CMS144v7: Consecutive Heart Rates less than 50 Inpatients, what would you expect to see as the return if not using a return statement?

Without a return statement, you’ll get a couple of results that have elements for each of the sources. So, you’ll get heart rate and a moderate or severe LVSDHF (left ventricular systolic dysfunction heart failure) inpatient encounter:

 // Result Type:


  { HeartRate: { id: 'obs-1', code: ... }, ModerateOrSevereLVSDHFInpatientEncounter: { id: 'enc-1', code: ... } }     

  { HeartRate: { id: 'obs-2', code: ... }, ModerateOrSevereLVSDHFInpatientEncounter: { id: 'enc-1', code: ... } }     

  { HeartRate: { id: 'obs-3', code: ... }, ModerateOrSevereLVSDHFInpatientEncounter: { id: 'enc-2', code: ... } }     

  { HeartRate: { id: 'obs-4', code: ... }, ModerateOrSevereLVSDHFInpatientEncounter: { id: 'enc-2', code: ... } }     



 If you don’t specify a return, then for each of the items in your “from,” you’ll get a result. The actual result of the query will be a list where you’ll have every combination of heart rate and moderate or severe LVSDHF inpatient encounter for this patient.  A return is typically used with a multi-source query to pick out particular elements to be returned. The “where” clause eliminates combinations of those encounters so it would pull out the rows that don’t match that criteria. In the end, you only end up with rows that match the criteria but since you didn’t specify the return, you will still get this list. Typically, if the result is used elsewhere then a return would be included. If you’re only using it in something like an “exists”, then you don’t need to include a return.

In multi-source queries, if an attribute is not mentioned specifically in the query, like the “method” attribute, will it still be included in the return?

Yes, if it is defined as an attribute in that source. For example, “method” is one of the attributes for “Physical Exam, Performed”.  So, for the default behavior (when no return is specified), each element will have the same structure as the source it came from.

In multi-source queries, is it feasible to specify the type of attributes we want returned?

Yes, you can use return, it’s an arbitrary expression. So, whatever you want to return from the “from,” you can.

Using Coalesce

Did you have to use Coalesce since you are using two different data types or are the attributes the same?

The Coalesce function takes a list of expressions and returns the first one that results in a value. For Procedure, Performed, we have both an authorDatetime and a relevantPeriod, but for Immunization, Administered, we only have an authorDatetime, so the Coalesce in this case is saying “Use the start of the relevantPeriod if it’s present, otherwise use the authorDatetime.”

In this example, the definition is "Hepatitis B Immunizations or Procedures", and it references two data criteria, one "Immunization, Administered": "Hepatitis B Vaccine", and one "Procedure, Performed": "Hepatitis B Vaccine Administered". In these criteria, "Immunization, Administered" and "Procedure, Performed" are Quality Data Model (QDM) Data Types, and "Hepatitis B Vaccine" and "Hepatitis B Vaccine Administered" are value set references.

The example can be found in the Clinical Quality Language (CQL) Formatting and Usage Wiki.

Is there a preferred pattern to use if not using Coalesce?

It depends how often the definition needs to be used in subsequent logic. If the definition is used often, and the Coalesce pattern is required for each usage, then it makes sense to use a return clause to shape the different results so that they have the same attributes. This allows subsequent expressions to just reference a single attribute, rather than having to use the Coalesce pattern to choose a value from among different attributes.

In the Coalesce expression, if the patient record has an order performed date of 12/12 but the performed author DateTime is 12/07 what is the result?

Coalesce(start of ComfortMeasures.relevantPeriod, ComfortMeasures.authorDatetime)

For Coalesce, each argument is considered in order, and the first one with a value is returned. The use of “first” in this description is referring to the list of arguments to the Coalesce function. So in the example of a performed date of 12/12 and an author date of 12/07, since the performed date (start of relevantPeriod) is first in the list of arguments and has a value, that will be returned as the result.

The example can be found in the Clinical Quality Language (CQL) Formatting and Usage Wiki.

Using Quality Data Model (QDM)

For medication order, is authorDatetime a timestamp or is it a period?

authorDatetime is a single timestamp, the time when the record was authored.

What is the recommendation for measure developers regarding the Quality Data Model (QDM) length of stay attribute? Should they use the attribute or should they indicate length of stay using Clinical Quality Language (CQL) expression without invoking the attribute?

Because length of stay is an attribute of the encounter, it doesn’t work for defining the overall length of stay in the case where we want to consider the encounter immediately prior to the Emergency Department (ED) visit. Using the CQL expression is more general and it allows you to handle that case transparently. The length of stay attribute of Encounter, performed can be used to define the time from admission to discharge for a specific encounter. However, if the measure developer needs to express the time from admission to a previous, but related encounter (i.e., an ED visit), the length of stay attribute would not be sufficient and a CQL expression provides such ability. Note, that to determine the arrival time at the previous ED visit, the measure needs to address the Encounter, Performed location attribute.

Why are we using diagnosis to represent allergy instead of allergy intolerance?

The Quality Data Model (QDM) supports the description of an allergy/intolerance to provide more detailed information than is available in a Diagnosis alone. However, this flexibility means there is the potential for underlying systems to provide the data as both a Diagnosis or as an Allergy/Intolerance. Measure authors can express the allergy in both ways to cover this possibility. For example, to address the type of reaction that meets the measure criteria, the measure can indicate “Diagnosis: Anaphylactic reaction to penicillin” using a precoordinated SNOMED CT concept, or use a post-coordinated approach “Allergy/Intolerance: Penicillin (type: anaphylaxis).” The latter approach may be more consistent with the way an allergy or intolerance is managed using non-measure transactions in Health Level Seven International (HL7) V2, V3, and Fast Healthcare Interoperability Resources (FHIR), except that FHIR uses the metadata element “reaction” to address the QDM attribute “type.”

In calculating methods for determining doses per day using the Quality Data Model (QDM) medication elements, can active medications be used instead of ordered, assuming the patient is taking the medication as directed?

If the frequency is available, then the QDM medication elements calculation would work, but if you are using the supply and the relevant periods to back into a daily value, that might not work because there is no certainty that supply is correlated with the relevant period. Refer to the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples for examples on how to calculate using both methods.

How does attribute result differ from the attribute component?

The attribute component is the list of results. For example, a diagnostic study performed may have a single result or a result and a code. It is a way to represent both components within the Quality Data Model (QDM) datatype. You can find further information about this example on the Clinical Quality Language (CQL) Formatting and Usage Wiki - Cooking with CQL examples.

Is the type of coverage, e.g., commercial, Medicare, Medicaid considered in the Quality Data Model (QDM) participation logic?

The participation logic determines coverage in a QDM measure using the QDM participation type. The logic starts with whether the patient is enrolled and it is particular to each product line, commercial, Medicare or Medicaid. However, in calculating the participation period and the enrollment periods, coverage type is usually ignored.

Is it accurate that if the glucocorticoid dosage expression was used for dispensed to ordered, results would be different because all the attributes are not available?

Correct, the main thing we are trying to get to is a daily dosage. Depending on what Quality Data Model (QDM) medication type is used, different attributes will be available so the calculation will need to take that into account. Also note that in QDM 5.4, the daysSupplied attribute can be used as another way to get to the daily dosage.

Does the new Related Person QDM datatype allow an eCQM specification to reference information about a related person that is already present in the patient’s record? As an example, instead of a direct context query, maternal information may be shared in a C-CDA and incorporated into an infant’s record.

Yes, the new QDM datatype Related Person will allow reference to information that is already present in the patient’s record yet represents information about the related person.

Quality Data Models (QDMs) are not really used for interoperability like Fast Healthcare Interoperability Resources (FHIR) is, it defines the type of metadata that we call attributes. Is it true that Electronic Health Records (EHRs) have been implemented to be able to export the full QDM set of attributes every time you ask for something? That’s the ideal.

In typical implementation, that’s the structure seen. A typical scenario is a database with columns that match to attributes in QDM so the overall structure will look like that but not all of the columns will necessarily be filled. From an architectural perspective, this would be a straightforward and reasonable way to do the implementation.

CQL Tooling

Can you provide an overview of current or future-planned Clinical Quality Language (CQL) execution tooling, i.e., Structured Query Language (SQL) execution, or Extensible Markup Language (XML) execution engines?

There is currently tooling to support authoring, parsing, and validation of CQL. There are open source tools available to evaluate Expression Logical Model (ELM) for both the JavaScript and Java platforms. There is also a .NET toolkit for ELM that can support translation and evaluation.

Developing the measures in Java, C#, or any other commercially supported language would not achieve the goal of sharing the measure logic in a platform independent way, nor would it serve as a vehicle for communicating the intent of the measures in the way that CQL/ELM does. Traditional programming languages do not support the required set of operations for expressing measure logic, and traditional query languages, though closer to the mark, still do not support important aspects like terminology and interval-based timing. Refer to the GitHub tooling repository for additional guidance.

Are there open source implementations or parsers available?
What 'software' does this run inside? What's running or interpreting the Clinical Quality Language (CQL) statements?

CQL is translatable to different environments with system engines that support its execution such as .NET, Java, and JavaScript. The open source tooling provides reference implementations that can be used as-is, or as a starting point for a custom implementation.

What technology is this language used with?

Clinical Quality Language (CQL) is intended to provide a means to accurately and easily share the logic involved and can be used with any technology platform. Open source tooling exists to facilitate usage in Java, .NET, and Java-Script.

Is there/will there be a relationship with Clinical Quality Language (CQL) to JavaScript Object Notation (JSON) or other scripting language?

Yes, CQL is both a high-level syntax expressed in text, as well as an equivalent lower level representation of the logic involved focused on language processing application. This lower-level format is defined as a schema and can be rendered in Extensible Markup Language (XML) or JSON. There is tooling in the GitHub repository to translate from the text representation of CQL to this lower-level representation (Expression Logical Model [ELM]) for XML or JSON rendering. In addition, the repository currently has an engine that can evaluate ELM expressions, there is a JavaScript engine that can run ELM representation.

I’m looking for a good Clinical Quality Language (CQL) editor. What editor are you using?

This editor is called Atom, a desktop general purpose editor. There is a CQL Language Package that gives basic syntax highlighting for CQL files within the Atom editor. It works well, does not give validations, but the Measure Authoring Tool (MAT) has that functionality embedded.

Measure Authoring Tool (MAT)

How does Clinical Quality Language (CQL) effect the Measure Authoring Tool (MAT)?

CQL writes text documents using the CQL library. The MAT provides the structure to make writing easy beyond having a text document. It helps with available operations and acceptable attributes from the Quality Data Model (QDM) element.

Can measure developers write Clinical Quality Language (CQL) directly, as opposed to using tools like the Measure Authoring Tool (MAT)?

While measure developers can write text documents using the CQL library, they are encouraged to use tooling to support CQL development. The MAT provides the structure to make writing easy beyond having a text document. It helps with available operations and acceptable attributes from the Quality Data Model (QDM) element.

Can the Measure Authoring Tool (MAT) help with issues like the square brackets versus parenthesis issue for intervals?

If a user creates Clinical Quality Language (CQL) statements freeform in the MAT, then the user is required to know the syntax, but it is possible validations will occur if it is not correct. If the user is using advanced functionality in the MAT to create the intervals, then the tool will insert the CQL logic with appropriate syntax and styling.

What Clinical Quality Language (CQL) artifacts are exported from the Measure Authoring Tool (MAT)?

The MAT exports CQL, Expression Logical Model (ELM), and JavaScript Object Notation (JSON) file artifacts. Refer to the MAT User Guide for additional MAT-specific questions.

Is the 'Hospitalization' function in a library in the Measure Authoring Tool (MAT)?

Yes, it is. Specifically, in this Clinical Quality Language (CQL) Formatting and Usage Wiki source. In addition, the function is available as part of the MAT Global Common Functions library in the MAT and in the CQL Style Guide. The appropriate version of MATGlobalCommonFunctions.cql is included with each measure specification zip file.

Is the Length of Stay function included in the Measure Authoring Tool (MAT) tool?

The ability to do this is currently in the MAT by creating a standalone Clinical Quality Language (CQL) library and including this function within it. Also calling it out as needed. The current Global Common Library includes a LengthInDays function for this purpose.

Can measures (developed in the Measure Authoring Tool (MAT)) be shared to use as examples?

Measures in the Measure Library can only be shared by the owner. However, users of the MAT can see all shared measures and look them up by title or CMS ID.

Using Fast Healthcare Interoperability Resources (FHIR)

How would some of the most commonly used datatypes in Quality Data Model (QDM) be expressed in a Fast Healthcare Interoperability Resource (FHIR)-based measure?

The common datatype examples below are expressed in FHIR-using Quality Data Model (QDM) version 5.4, FHIR version 4.0.0, and include FHIRHelpers version 4.0.0.


From a performance perspective of a Quality Data Model (QDM) approach vs. a Fast Healthcare Interoperability Resource (FHIR) approach, you might be able to have a pretty efficient database access with QDM. With the FHIR measure doing one patient at time, you’re going to be making a lot of FHIR application programming interface (API) calls. One option might be to use a FHIR bulk export, which would return a large Newline-Delimited JavaScript Object Notation (ND JSON) file (the file format used for bulk data transfer in FHIR), that might be a way to get a lot of information at one time. Is there some thought to using a bulk concept to frontload the data?

The bulk export is certainly one option for retrieving all the data at one time. The way Clinical Quality Language (CQL) is built, all of the data access is expressed in terms of these retrieves so you can characterize the overall data requirements for this library by only looking at this set of retrieves and use that as parameters for an export operation to say “export all of the data required for this whole population given these data requirements.” You can think of evaluating this patient at the time against a FHIR endpoint where these retrieves are converted into actual FHIR Uniform Resource Locators (URLs) is one approach to implementation. You can also imagine an implementation that went behind the scenes to access the same infrastructure that is supporting the FHIR API and dig into that directly. With the reference implementation that is plugged into a HAPI FHIR server that reaches into the data access layer, you’re hitting the underlying data access layer instead of going back out through the endpoint when you run the CQL in process in the HAPI FHIR server. It’s still the case that in the reference implementation, the processing is happening a patient at a time, but you can imagine an implementation that does the same kind of thing but across the population rather than a patient at a time. The key aspect that’s being communicated from the logic perspective is what the structure looks like and what the criteria are. It may be the case that you actually have a structured query language (SQL) database that has your FHIR resources in it and the way that you take the CQL and run it in that environment may be to translate it to an SQL query across patients. So there are a lot of potential approaches to evaluating the CQL and one of the primary goals of this approach is to make sure the logic can be shared and evaluated in all those different environments that makes the most sense for those environments.

Once the Quality Improvement (QI)-Core QUICK model is fully mature and supported, will that be the expected mechanism to write a Fast Healthcare Interoperability Resources (FHIR)-based measure?

We’re currently exploring that and making sure that the specifications can be expressed that way and making sure that it’s a reasonable and feasible way of doing this. At this point, we’re still in the exploration phase. We are making sure the specification fully supports the specification of electronic clinical quality measure and quality reporting using this mechanism.

In the draft of the Exclusive Breast Milk Feeding Measure - PC-05 (snippet from EXM9_FHIR4 version 8.1.000), there are some specific changes on how to represent some of the concepts used in this measure within Fast Healthcare Interoperability Resources (FHIR). Specifically, there are some changes around representation of total parenteral nutrition and nutrition intake resource that are planned for R5. When looking at a single newborn with no parenteral nutrition given, generally does status matter if it’s a negation?

The example below states that “there is no evidence that parenteral nutrition was applied because there is no record that it happened.” That’s not a guarantee that it didn’t happen since some occurrences may not be reflected in the database. The statement is merely saying that there is no evidence that parenteral nutrition was applied. We could take it one step further and say we are looking for positive evidence (for example, documentation) that it wasn’t applied, but such documentation rarely, if ever, exists. Appropriate statuses are in-progress, not-done, on-hold, completed, entered-in-error, stopped, and unknown. Other than entered-in-error and unknown, this set of responses are valid statuses in this context. However, when you get FHIR to indicate the Quality Data Model (QDM) concept of negation rationale, you have to add a status to say it didn’t happen and there is no evidence of it. In the example below, the expression only evaluates that there is no evidence of MedicationAdministration: Parenteral Nutrition. A reason for absence of the activity is not requested. Note, the code below was tested and the updated measure was presented at the 10/24/2019 Cooking with CQL #39.

Image of Relevant Code

With the Exclusive Breast Milk Feeding Measure - PC-05 (snippet from EXM9_FHIR4 version 8.1.001), currently Breast Milk is a value set with a substance code. In order to use the Procedure resource, can we create a new value set containing all the Procedure codes for Breast Milk? If we have that value set, can we just say procedure breast milk?

If you can find specific procedure codes that say “feeding breast milk” then that would be your procedure, but if you’re looking for exclusive breast milk feeding and no other substances then you would have to find a procedure code for “exclusive breast milk feeding” or indicate without “procedure enteral feeding for any substance other than breast milk.” It will be easier to find a procedure code (or codes) more generic to enteral feeding, meaning feeding through the gastrointestinal track and then indicate a Procedure.usedCode of breast milk substances and indicate no feeding with anything else. 

When the Quality Data Model (QDM) says Substance Administered, empirically we know what that means, but the only substances that Fast Healthcare Interoperability Resources (FHIR) references as administered are those that can be classified as medications. We count total parenteral nutrition like a medication but breast milk isn’t handled that way. Until such time as FHIR includes a way to represent intake and output of substances, the best approach is to use the Procedure resource to reference “feeding” as a procedure and Procedure.usedCode as the substance used to accomplish the feeding procedure. The implementation question and the terminology choice require consideration regarding how the data would be represented in the systems. A procedure that used Enteral Feeding as the code would capture more of the intent. Note, the code below was tested and the updated measure was presented at the 10/24/2019 Cooking with CQL #39.

Image of relevant code

Based on EXM130 – consider the Procedure.performed element:
(the rest of the question is in the answer)

Q: In the Fast Healthcare Interoperability Resources (FHIR) Standard for Trial Use (STU) 3, it is defined as a choice of dateTime|Period and in R4, it is defined as a choice of dateTime|Period|string|Age|Range where the Quality Improvement (QI) Core constrains out the “string” type.

For STU3, the standard “Normalize Interval” function works:

STU3 Normalize Interval Function

But for R4, we need to expand the “Normalize Interval” function to allow for the new types:

R4 Normalize Interval Function

It’s a great idea to have a “Normalize Interval” function in the global library, but will you have one function, “Normalize Interval” function, that contains the flexible arguments in the parameter or will you have multiple ones depending on the FHIR resource? How many choice data type elements will the resource have?

A: We could define “Normalize Interval” versions that had only the choices for what we wanted but when you start doing that, the differences between the sets of types defined in the different elements becomes unwieldy. By defining one version of “Normalize Interval” that has all the possible choice types we encounter in timing elements, we can define one function that can handle all of those and then as long as the types that the elements can be are a subset of these, then the Clinical Quality Language (CQL) can work with it.

Based on the EXM130 expression below, can you explain the “Message” function and each component of it?

EXM130 Expression

Clinical Quality Language (CQL) is a functional language, meaning everything in CQL is going to return a value. Even in the case where we’re throwing an ‘Error’ or returning a ‘Warning,’ it will still return a value. The first argument to the Message function is the value it will return as an Interval. You can also add conditions to log the Message. Below are the components of this line broken down:

Message(null as Interval<DateTime>, true, '1', 'Error', 'Cannot compute a single interval from a Timing type')

  • null as Interval<DateTime> = the first argument is the value you want to return
  • true = the condition, you can conditionally return or log the message.
  • 1 = the error code.
  • Error = the message you want to send back - this can be ‘Error,’ ‘Warning,’ or ‘Information.’ If it’s an ‘Error,’ it also stops processing. If it’s a ‘Warning,’ it’s a message that comes back as part of the evaluation.  Since it doesn’t stop processing, it needs to send back a result.
  • Cannot compute a single interval from a Timing type = the message you actually want to send out.

Based on the EXM130 expression below, why does the message only happen to the timing, instance, and string? Does it not apply for all resources?

EXM130 Expression

In the case of a timing element as highlighted above, a FHIR.string means you have a string that the user entered as the value for that time. For example, in this condition the resource string could have a value of “last spring.” With Fast Healthcare Interoperability Resources (FHIR) in the condition resource, it is possible to communicate that the user has actually entered the timing as just a natural language string and that’s what the string choice type means. Regarding FHIR.Instant as highlighted above, it is okay since it is just a DateTime that has to be to the millisecond. Regarding timing, in R4 it is an observation which was expanded to support not only DateTime and Period, but also Timing and Instant.

Timing is a very complex object that lets you build up very complex schedules, therefore, it is very flexible. However, if there is a use case where there is a system that wants to use the timing type of the effective element of an observation it means that the data received cannot be processed, which will result in an error message.

In the EXM130 expression below, would it be better to move the FHIR.Timing and the FHIR.string to the bottom of the list if one were to prioritize the list?

EXM130 Expression

The case expression in Clinical Quality Language (CQL) doesn’t carry any implication of ordered processing and in any given instance choices are exclusive. Therefore, you will only have one set of the types chosen at a given time. For example, you would not have a FHIR.dateTime and a FHIR.Timing in the same element. However, implementations may walk through each of the instances from top to bottom so it would be reasonable to move the FHIR.Timing and the FHIR.string to the bottom to allow for the more common instances to be hit first, but it doesn’t change the actual semantics of the function.

The measure EXM135 is an example of ConditionOnsetAbatementPrevalencePeriod where we determine the Onset/Abatement and Prevalence Period for a condition. This makes sense for Pregnancy, but could you also use the procedure ‘Delivery’ to say that it ended?

We define the Prevalence Period:

EXM135 Prevalence Period

Yes, this is correct. For all other conditions you can follow the example but for pregnancy you can also use ‘Delivery’.

For the measure EXM135, is there a reason you exclude the timepoint of the abatement time by using parentheses “)” instead of brackets “]”?

Yes, there are two reasons:

  1. This is when they said the condition was over so it really shouldn’t be included during the time that it is happening. It is an exclusive boundary.
  2. More importantly, if this element is not present and we use the inclusive boundary, then it would mean that this condition goes until the end of time. This is the opposite of what we are trying to say. Using the inclusive boundary means that we don’t know when that interval ends.

So, excluding the abatement time assumes that the condition abated some time before the recorded date. If this is false, then it means the condition goes on until the end of time.

Can you provide some resources for using Clinical Quality Language (CQL) in Fast Healthcare Interoperability Resources (FHIR)?

In the example on AllergyIntolerance, why are some Quality Improvement (QI)-Core Patterns, such as “allergy-active” and “allergy-confirmed,” represented in the Global Common Library? (the rest of the question is in the answer)



Use of AllergyIntolerance




// connectathon/fhir4/cql/EXM105_FHIR4-8.1.000.cql


define "Statin Allergy":


  ["AllergyIntolerance": "Statin Allergen"] StatinAllergy


    where (StatinAllergy.clinicalStatus is null or FHIRHelpers.ToConcept(StatinAllergy.clinicalStatus) ~ Global."allergy-active")


      and FHIRHelpers.ToConcept(StatinAllergy.verificationStatus) in { Global."allergy-unconfirmed", Global."allergy-confirmed" }

We define several direct reference codes related to AllergyIntolerance and other resources profiled by QI-Core in the Global Common Library so it is easy to reference. If there was a value set established, then that could be referenced directly from the Clinical Quality Language (CQL). In the interim, we reference the direct reference codes in the Global Common Library.

Regarding the measure Device Indicating Frailty, when considering Fast Healthcare Interoperability Resources (FHIR)-based Clinical Quality Language (CQL) Quality Improvement (QI)-Core Patterns within the DeviceRequest.intent comparison, is there a way to ask whether the code is “like ‘%order’”, similar to the what is supported by some database query languages? (the rest of the question is in the answer)




Use of DeviceRequest




// connectathon/fhir4/cql/AdvancedIllnessandFrailtyExclusion_FHIR4-4.0.000.cql


define "Device Indicating Frailty":


  [DeviceRequest: "Frailty Device"] FrailtyDeviceOrder


    where FrailtyDeviceOrder.status in { 'active', 'on-hold', 'completed' }


      and FrailtyDeviceOrder.intent in { 'order', 'original-order', 'reflex-order', 'filler-order', 'instance-order' }

Yes, CQL does have that capability. There is a Matches function that supports string-based pattern matching and there are StartsWith or EndsWith functions that you can use. However, because these comparisons are terminological, the recommended approach is to define a value set that contains all and only the specific codes of interest. This example is listing the codes for illustration purposes only. Using a string-based pattern matching function for terminological comparison introduces a risk of matching on unintentional codes.