8.0CQL Getting Started



Clinical Quality Language (CQL) is a high-level, domain-specific language focused on clinical quality and targeted at measure and decision support artifact authors. HAPI embeds a CQL engine allowing the evaluation of clinical knowledge artifacts that use CQL to describe their logic.

A more detailed description of CQL is available at the CQL Specification Implementation Guide

The FHIR Clinical Reasoning module defines a set of resources, profiles, operations, etc. that can be used to work with clinical knowledge within FHIR. HAPI provides implementation for some of those operations, described in more detail below.

Working Example

A complete working example of HAPI CQL can be found in the JPA Server Starter project. You may wish to browse its source to see how it is set up.


To get up and running with HAPI CQL, you can enable it using the hapi.properties file in the JPA Server Starter by setting hapi.fhir.enable_cql key to true. If you are running your own server follow the instructions below to enable it in HAPI FHIR directly.

Once you've enabled CQL processing, the next step is to load the appropriate knowledge artifact resources into your server.

CQL Settings

There are two Spring beans available that add CQL processing to HAPI. You can enable CQL processing by importing the appropriate version for your server configuration.

  • ca.uhn.fhir.cql.config.CqlDstu3Config
  • ca.uhn.fhir.cql.config.CqlR4Config


HAPI provides implementations for some Measure operations for DSTU3 and R4


The $evaluate-measure operation allows the evaluation of a clinical quality measure. This operation is invoked on an instance of a Measure resource:


The Measure will be evaluated, including any CQL that is referenced. The CQL evaluation requires that all the supporting knowledge artifacts for a given Measure be loaded on the HAPI server, including Libaries and ValueSets.