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

Clinical Reasoning Operations

HAPI provides implementations for some operations in DSTU3 and R4:

CQL Measure


Further development of the CQL capabilities in HAPI is planned:

  • Additional features and performance enhancements for Measure evaluation
  • Additional FHIR Clinical Reasoning Module operations:
    • Library $evaluate
    • PlanDefinition $apply
  • Support for the CPG IG Operations
    • $cql