Skip to content

Getting Started with Clinical Quality Language

Jump to bottom
Mark Marciante edited this page Dec 2, 2025 · 5 revisions

Getting Started with CQL

Whether you're developing measures, building engines, or using CQL in implementation guides, this guide will help you get up and running.

Choose your path below to get started.

🎯 Choose Your Path

📊 Measure Developer ⚙️ Engine Developer 👤 Clinical Data Solution Implementer
Authoring quality measures and clinical decision support Building CQL execution engines and infrastructure Using CQL in implementation guides
Start Here → Start Here → Start Here →

📊 Measure Developer Path

Goal: Write CQL to define quality measure logic and clinical decision support rules

Your 6-Step Roadmap

Step Action Resources
1 Set up tools VS Code • CQL Plugin • MADiE
2 Learn basics Session 63: Beginning CQL • CQL Spec Ch. 2 • Cheat Sheet
3 Study examples Example Measures • Current eCQMs
4 Follow conventions Formatting Guide • Authoring Patterns
5 Get help chat.fhir.org #cql • Q&A Index
6 Using CQL with Terminology Services Using CQL With Terminology Services

Ready to dive deeper? → Go to Measure Developer Hub

⚙️ Engine Developer Path

Goal: Implement CQL parsers, evaluators, and execution infrastructure

Your 6-Step Roadmap

Step Action Resources
1 Understand architecture CQL Specification • ELM Model • Reference Implementations
2 Set up environment Clone reference implementation • CQL Translator
3 Build core features Start with data types → operators → retrieves → queries
4 Test conformance CQL Test Suite • Run tests regularly
5 Join community CQL Developers Stream • [HL7 Connectathons]
6 Using CQL with Terminology Services Using CQL With Terminology Services

Ready to dive deeper? → Go to Engine Developer Hub

👤Clinical Data Solution Implementer

Goal: Understand and implement CQL logic from implementation guides like Da Vinci and HEDIS

Your 6-Step Roadmap

Step Action Resources
1 Learn to read CQL Understanding Basics • Session 63: Beginning CQL • Cheat Sheet
2 Understand your IG Review clinical logic • Identify data elements • Understand populations
3 Choose tools Select CQL Engine • Set up data mapping • Test with samples
4 Validate and test Use IG test cases • Verify data requirements • Check expected outcomes
5 Get support Da Vinci Project • [chat.fhir.org #cql]
6 Using CQL with Terminology Services Using CQL With Terminology Services

Ready to dive deeper? → Go to Clinical Data Solution Implementers

Understanding CQL Basics

Your First CQL Library

Here's a simple CQL library structure:

library MyFirstMeasure version '1.0.0'

using FHIR version '4.0.1'

include FHIRHelpers version '4.0.1'

valueset "Diabetes": 'http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113883.3.464.1003.103.12.1001'

define "Measurement Period":
  Interval[@2024-01-01, @2024-12-31]

define "Patient Has Diabetes":
  exists (
    [Condition: "Diabetes"] C
      where C.clinicalStatus ~ "active"
  )

Key Components:

  1. Library declaration - Names and versions your library
  2. Using declaration - Specifies your data model (FHIR or QDM)
  3. Include statements - Imports shared libraries
  4. Value set declarations - References to standard terminologies
  5. Define statements - Your clinical logic expressions

Reading CQL Expressions

Retrieving Data:

// Get all conditions with a specific code
[Condition: "Diabetes"]

// Filter the results
[Condition: "Diabetes"] C
  where C.clinicalStatus ~ "active"

Queries with Timing:

// Find encounters in a specific period
[Encounter: "Inpatient"] E
  where E.period during "Measurement Period"

Calculations:

// Calculate age at a specific date
AgeInYearsAt(start of "Measurement Period")

// Calculate duration
duration in days of EncounterPeriod

Essential Resources

Core Documentation

Tools

Learning Resources

Reference Implementations

If you're building or evaluating CQL engines:

Data Models

CQL works with different healthcare data models:

FHIR (Recommended for new projects)

QDM (Existing measures)

  • Established for quality measures
  • Used in many current CMS eCQMs
  • Gradually transitioning to FHIR
  • QDM Specification

Community & Support

Get Help

Stay Connected

Next Steps

Choose your path above to access role-specific resources and guidance:

← Back to Home

Maintained by the Digital Quality Implementers Community

Clone this wiki locally