Clinical Quality Language (CQL)

Last updated: May 18, 2026

Roles: Investigator Research Leaders Informaticist Software Engineer Clinician Scientist/Trainee

Learning objectives

What is Clinical Quality Language (CQL) and how does it relate to FHIR?
CQL is a domain-specific language for representing computable clinical logic, such as cohort criteria, algorithms, and clinical rules. CQL is data-model agnostic, but it is commonly used with FHIR so that logic can reference standardized clinical data in a format supported by many vendors.
How can CQL be used to represent clinical and research logic?
CQL can express precise, human-readable, machine-computable criteria for use cases such as electronic clinical quality measures, clinical decision support, cohort definitions, phenotype definitions, and computable protocols. For example, CQL can define whether a patient is an adult, had an outpatient encounter during a study period, and has an elevated HbA1c result.
Why is CQL relevant to clinical researchers using FHIR data?
CQL can help researchers define and share standardized logic across FHIR-enabled sites, reducing ambiguity in cohort selection, eligibility criteria, quality measurement, guideline adherence studies, and point-of-care research interventions. It can also help connect research workflows with existing quality measurement and decision support infrastructure.
What should researchers consider before using CQL in a project?
Researchers should assess whether the required FHIR data are available, complete, consistently coded, and suitable for the intended logic. They should also account for terminology requirements, clinical validation, site-to-site implementation differences, and the need for specialized tooling to author and execute CQL.

1 Overview

HL7 Clinical Quality Language (CQL) is a domain-specific language for specifying clinical logic such as algorithms, rules, and complex criteria. It is most often used for defining electronic clinical quality measures (eCQM) and clinical decision support (CDS) logic, but it can also be used for cohort selection, prior authorization logic, questionnaire population, and other use cases that need to extract, reason over, and/or manipulate health data in a standardized way. CQL is sometimes referred to as a way of representing clinical knowledge because it can be used to encode clinical guidelines, calculators, and measures.

CQL is intended to be both human-friendly and machine-computable. Simple expressions can often be understood by people who are not familiar with CQL. For example:

```
AgeInYears() >= 18
```
```
exists [Condition: "Diabetes"]
```

[Encounter: "Inpatient"] E where E.period starts 1 year or less before Today()

Human-readable CQL expressions are usually bundled together in a single file called a CQL library. CQL libraries can be translated automatically into a special format that is optimized for machine processing, called the Expression Logical Model (ELM). In this way, CQL can be used to turn clinical intent, such as “adult patients with elevated A1C,” into precise logic that software systems can evaluate against structured health data.

For a comprehensive overview of CQL, watch the Clinical Quality Language Deep Dive video from the FHIR DevDays 2023 conference.

2 Relationship to FHIR Standards

2.1 FHIR

The CQL specification is primarily concerned with defining a standard way to express logic over clinical data. As such, it is data-model agnostic, meaning that it does not make any assumptions about how data is represented or exchanged. In theory, CQL can be used with any data specification or format, but when authors write CQL logic they must declare which data model(s) the logic is intended for. Similarly, CQL tools must declare which data model(s) they support.

When CQL was first introduced, most CQL libraries used the Quality Data Model (QDM) for representing clinical data. Today, CQL authors and implementers usually prefer using HL7 FHIR (or FHIR implementation guides like QI Core) as the underlying data model. In these cases, CQL libraries reference FHIR resources (e.g., Patient, Encounter, Condition) and their corresponding elements (e.g., Patient.gender, Encounter.period, Condition.clinicalStatus). FHIR-based CQL implementations must be capable of retrieving the FHIR resources that CQL libraries request.

2.2 FHIR Clinical Reasoning and Questionnaires

FHIR also defines several resources in the Clinical Reasoning module that can be used to exchange CQL and CQL-enabled workflows as FHIR resources:

Library packages a CQL library (and optionally its translated ELM) along with related metadata about the CQL library.
Measure represents an electronic quality measure or population-based calculation.
MeasureReport represents the results of evaluating an electronic clinical quality measure.
PlanDefinition represents a computable clinical guideline, protocol, or other decision support artifact.
ActivityDefinition represents actions that may be recommended by decision support logic within a plan definition.

In addition, the Questionnaire resource and related extensions allow CQL as an expression language for populating the initial values in Questionnaire responses. See Structured Data Capture: Using Expressions for additional guidance.

2.3 SMART on FHIR and CDS Hooks

While the CQL specification defines a standard representation for clinical logic, it does not define how the results of that logic should be presented to users or delivered to systems. Instead, standards such as SMART on FHIR and CDS Hooks are used to present and exchange clinical logic results and CDS suggestions. SMART on FHIR and CDS Hooks implementations often do perform logical operations on clinical data, but they operate as black boxes; these standards define how data goes in and out of the systems, but they do not define how the input data is used to derive the output results. As such, CQL can provide a standards-based mechanism for representing the clinical reasoning that happens “inside the box” for SMART on FHIR and CDS Hooks systems.

3 Common CQL Use Cases

3.1 Electronic Clinical Quality Measures

Electronic clinical quality measures (eCQMs) are measures specified in a standard electronic format that use data electronically extracted from electronic health records (EHRs) and/or health information technology (IT) systems to assess the quality of health care provided [1].

For example, CMS125: Breast Cancer Screening measures the percentage of women aged 50 to 74 who received a mammogram within a certain period of time.

Many eCQMs follow a population-based paradigm, defining criteria that evaluate each patient for membership in the following populations:

Initial Population: the initial cohort from which the denominator will be selected; often designated by broad criteria like age and gender.
Denominator: the population to which the measure applies; often providing more specific criteria such as diagnoses, procedures, lab results, or visits.
Denominator Exclusions: criteria used to remove patients from the denominator when the numerator is not applicable to the patient (e.g., a patient with a bilateral mastectomy should not be evaluated for a mammography measure)
Denominator Exceptions: criteria used to remove patients from the denominator for medical reasons (e.g., pregnancy), patient reasons (e.g., religious objection), or system reasons (e.g., a vaccine shortage). In this case, patients are only removed from the denominator if they do not meet the numerator criteria.
Numerator: the population that satisfies the intent of the measure; often used to determine if the required standard of care was applied or the desired outcome was achieved. In some measures the numerator may represent undesired outcomes, in which case lower scores are better.
Numerator Exclusions: criteria used to remove patients from the numerator when they should not be counted for some other reason.

As the population names suggest, these measures are typically scored by dividing the numerator by the denominator, taking into account relevant exclusions and exceptions. The above descriptions focus on patient-based populations, but some measures may count encounters, episodes, or other items instead. The CMS documentation for specifications by measure category describes the different types of measures, and the documentation for developing specifications provides additional details about the different measure populations.

CQL-based measures use CQL logic to define the population criteria for each of the populations above. The Centers for Medicare and Medicaid Services (CMS) began publishing eCQMs in the CQL format in 2019 [2] and have published updates every year since then. Current measures (as of 2026) use CQL with the QDM, HQMF, and QRDA. CMS is in the process of transitioning to FHIR for measure data and reporting, at which point these measures will be called digital quality measures (dQM) [3]. Visit the eCQI Resource Center to download CMS eCQMs and access robust documentation about developing and using CQL-based eCQMs.

3.2 Clinical Decision Support

Clinical decision support (CDS) is a digital tool that provides timely and person-specific information, intelligently filtered or presented at appropriate times, to enhance patient outcomes and quality of care [4].

CDS may be presented as clinician- or patient-facing dashboards, clinical recommendations based on guidelines, risk calculators, patient-safety alerts, relevant links to documentation, order sets, and more. The CDS Five Rights Framework [5] indicates that successful CDS tools should deliver

the right information
to the right people
in the right format
through the right channels
at the right time.

CQL logic can be used in CDS implementations for tasks such as determining if a patient should receive a particular treatment, calculating risk, suggesting screenings or labs, calculating dosage information, and processing patient data to surface clinical insights such as trends and summaries. To provide a complete solution, CQL is often used in conjunction with other standards and technologies, including:

SMART on FHIR
CDS Hooks
FHIR Clinical Reasoning
FHIR Structured Data Capture

The FHIR Clinical Guidelines implementation guide provides additional guidance and specification regarding how to use CQL with FHIR to implement clinical guidelines as standards-based clinical decision support tools. See its examples page for a list of guidelines that have been converted to CQL-based CDS. From 2016 to 2024, the AHRQ CDS Connect project implemented and piloted a number of CQL-based CDS artifacts, the findings of which are available in its publication archives.

4 CQL for Clinical Researchers

CQL may be applicable to clinical researchers in any context in which they want to use or share standards-based clinical logic and algorithms.

4.1 Defining research cohorts

CQL can help researchers express inclusion, exclusion, and phenotype definitions in a standardized, human-reviewable form. This may be useful when a study needs to identify patients across multiple FHIR-enabled sites. Even in cases where available tooling does not support executing CQL logic, CQL expressions provide a deterministic, fully-specified approach to defining cohort criteria.

4.2 Connecting research and quality measurement

Researchers studying care quality, guideline adherence, implementation outcomes, or learning health systems may encounter CQL in the context of existing clinical quality measurement and decision support tools. In cases where measurement or decision support tools are needed but do not yet exist, researchers may choose to build them using CQL logic and related technologies.

4.3 Supporting computable protocols and pragmatic trials

CQL may be useful when research logic needs to run at the point of care, such as identifying eligible patients, detecting clinical events, or supporting CDS interventions within clinical workflows.

5 Example CQL Library

We will create a CQL library that contains expressions representing the following criteria:

Adult patients who had an outpatient encounter during the study period and whose most recent HbA1c result was greater than 6.5%.

CQL can be used to express the following concepts from the criteria:

The study period
If the patient is an adult
Outpatient encounters during the study period
The most recent HbA1c lab test
If the most recent HbA1c value was 6.5% or greater
If the patient meets the combined criteria

5.1 Defining the ExampleElevatedHbA1c CQL Library Step-by-Step

First we must declare a library name and version. CQL uses the library and version keywords for this.

library ExampleElevatedHbA1c version '0.0.1'

Next we must indicate what data model we’re using (FHIR) and include any helper libraries for that data model. CQL uses the using keyword to declare models and the include keyword to include additional libraries in your logic.

using FHIR version '4.0.1'
include FHIRHelpers version '4.0.1'

When CQL queries for data, it’s often useful to filter the queries based on clinical terminology. For example, we only want to retrieve encounters that are coded as outpatient and observations that are coded HbA1c lab tests. CQL requires authors to declare terminology requirements up front and provides valueset, codesystem, concept, and code keywords for doing so. In our case, we will use value sets from the Value Set Authority Center.

valueset "Outpatient Clinical Encounters": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1160.24'
valueset "HbA1c Laboratory Test": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.198.12.1013'

Since the study period could change, we will use a CQL parameter to define the study period as a DateTime interval that is passed in during execution. This means that the CQL can be executed with any arbitrary study period rather than encoding a specific study period into the CQL logic.

parameter "Study Period" Interval<DateTime>

Next we will declare that the rest of the CQL expressions in the library are intended to be processed in the context of a patient. CQL uses the context keyword and supports different contexts depending on the data model being used. Most data models support the Patient context.

context Patient

We’re finally at the point where we can define the first patient-based criteria. We need to determine if the patient is an adult. To do this, we’ll use CQL’s built-in AgeInYears() function to determine if the patient is 18 years or older. Note as well that we use a define keyword to give the CQL statement a name that we can reference later. Statement names should reflect what they represent, so we’ll call it Is Adult since it returns a true or false value depending on if the patient is an adult.

define "Is Adult": AgeInYears() >= 18

To determine if the patient had an outpatient encounter in the study period, we must query for Encounters that have a code in the Outpatient Clinical Encounters value set and whose encounter period occurred during the Study Period.

define "Has Outpatient Encounter During Study Period":
  exists [Encounter: "Outpatient Clinical Encounters"] E
    where E.period during "Study Period"

In the above expression, [Encounter: "Outpatient Clinical Encounters"] retrieves Encounter resources from the FHIR server and filters them by the Outpatient Clinical Encounters value set. The letter E is used as an alias to refer to each returned Encounter in the where clause. The exists keyword is used to check if the query returns at least one result (i.e., at least one matching encounter exists).

Next we want to check the most recent HbA1c value. First we’ll find the most recent HbA1c laboratory test by querying for Observations with a code in the HbA1c Laboratory Test value set. Since we want the most recent one, we will sort the results by their issued dates and return the last one by using CQL’s built-in Last function.

define "Most Recent HbA1c": 
  Last([Observation: "HbA1c Laboratory Test"] HbA1c sort by issued)

To see if the result is 6.5% or above, we can reference the Most Recent HbA1c expression we just defined and check its value. CQL indicates that UCUM units must be wrapped in single-quotes, so when we do the comparison, we must use '%' rather than %.

define "Has Elevated HbA1c": "Most Recent HbA1c".value >= 6.5 '%'

Finally we can combine our statements using the and keyword to provide one expression that checks all of the criteria.

define "Is Adult with Outpatient Encounter and Elevated HbA1c":
  "Is Adult" and
  "Has Outpatient Encounter During Study Period" and
  "Has Elevated HbA1c"

5.2 The Complete ExampleElevatedHbA1c CQL Library

Putting all of the steps above together, we end up with the following library. Note that this library is for example purposes only. It has not been fully tested and should not be used in production environments.

library ExampleElevatedHbA1c version '0.0.1'
using FHIR version '4.0.1'
include FHIRHelpers version '4.0.1'

valueset "Outpatient Clinical Encounters": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1160.24'
valueset "HbA1c Laboratory Test": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.198.12.1013'

parameter "Study Period" Interval<DateTime>

context Patient

define "Is Adult": AgeInYears() >= 18

define "Has Outpatient Encounter During Study Period":
  exists [Encounter: "Outpatient Clinical Encounters"] E
    where E.period during "Study Period"

define "Most Recent HbA1c": 
  Last([Observation: "HbA1c Laboratory Test"] HbA1c sort by issued)

define "Has Elevated HbA1c": "Most Recent HbA1c".value >= 6.5 '%'

define "Is Adult with Outpatient Encounter and Elevated HbA1c":
  "Is Adult" and
  "Has Outpatient Encounter During Study Period" and
  "Has Elevated HbA1c"

If you’d like, you can copy the CQL library above into the online CQL Playground to see what the machine-computable ELM representation looks like. Feel free to experiment by changing the CQL and watching the ELM representation change in response.

6 Implementation Considerations

When using CQL or determining if you should use CQL for a research project, consider the following:

CQL results are only as good as the data provided as input. CQL does not limit the FHIR resources or elements you can reference, but real-world FHIR implementations do not support every FHIR resource or every element within each FHIR resource. The data requirements of a CQL library should be evaluated for feasibility based on the FHIR data that is available. In addition, FHIR data may be incomplete (e.g., missing values), may use non-standard codes, or may be coded incorrectly. If CQL is provided poor quality data, it will generally provide poor quality results.

A strong understanding of terminology is required. CQL uses value sets, code systems, and codes to filter data from broad health data types (e.g., procedure) to specific concepts (e.g., appendectomy). CQL authors and implementers must have a robust understanding of standard terminologies, how they are used, and how they relate to FHIR resources.

CQL logic must be clinically validated. CQL tools can ensure that logic is syntactically correct, but they do not guarantee that the logic is semantically or clinically correct. Researchers should validate CQL definitions against chart review, known cohorts, synthetic data, or other expected results. Since FHIR implementations vary from site to site, CQL should be validated against representative data from each site (see the first point above).

CQL execution requires specialized tooling. While CQL has been used in quality measurement for many years, health IT products outside of the quality measurement space are still in the process of adopting CQL. Researchers should not assume that sites are capable of executing CQL logic without introducing additional software services. The CQL Community Projects wiki lists known open-source CQL implementations, but a similar list of commercial vendors supporting CQL is not currently available.

7 CQL Resources

The following resources may be useful for researchers who want to learn more about CQL:

Clinical Quality Language Specification: The official specification describing CQL and its capabilities. The Author’s Guide provides a friendly walk-through of the most important CQL concepts and the Appendix B - CQL Reference provides an exhaustive list of all standard CQL operations and system functions.
FHIR Clinical Reasoning: A module within the FHIR specification that describes how to represent clinical knowledge artifacts, such as clinical decision support rules and clinical quality measures, using FHIR resources and expression languages like CQL. This includes resources like Library, Measure, and PlanDefinition.
Using CQL with FHIR Implementation Guide: A FHIR implementation guide describing how to use CQL with FHIR, including authoring guidance and patterns, implementation guidance, common CQL functions for FHIR, and more.
eCQI Resource Center: A robust collection of information about standards and technologies related to electronic clinical quality. The CQL module provides links to tools and educational resources. The dQM module contains information about the transition to FHIR-based CQL measures. Also check out the eligible clinician, inpatient, and outpatient eCQMs for real-world CQL measures (but note that they do not yet use FHIR).
CQL Community Projects: A listing of open-source projects including CQL compilers, CQL engines, CQL authoring tools, and CQL content.
#cql on chat.fhir.org: A public user forum where CQL novices and experts can discuss CQL, ask questions, and get help.
CQL Playground: An online web application that allows users to enter CQL and compile it on the fly to ELM. Although it does not yet support execution, it’s useful for quickly checking CQL logic for syntactic correctness.
CQL Studio: A brand-new web application for CQL authoring and testing. As of May 2026 it is still under active development. Users may encounter bugs, but it shows great promise for the future, including AI-enabled CQL authoring.

References

[1]

CMS. Available: https://ecqi.healthit.gov/sites/default/files/eCQM-Basics-February-2026.pdf

[2]

CMS. Available: https://ecqi.healthit.gov/node/192236

[3]

CMS. Available: https://ecqi.healthit.gov/fhir/about

[4]

ONC. Available: https://healthit.gov/clinical-quality-and-safety/clinical-decision-support/

[5]

J. A. Osheroff et al., Improving outcomes with clinical decision support: An implementer’s guide, 2nd ed. HIMSS Publishing, 2012.