CQL Syntax Learning Notes

Clinical Quality Language (CQL) reference for healthcare application developers.

What is CQL?

Clinical Quality Language (CQL) is a high-level, domain-specific language for expressing clinical knowledge. It's used for:

Clinical decision support rules
Quality measures
Research cohort definitions

Basic Syntax

Library Declaration

library DrugRepurposingLogic version '1.0.0'

using FHIR version '4.0.1'

include FHIRHelpers version '4.0.1'

Context

context Patient

Data Types

Primitives

Type	Example
`Integer`	`42`
`Decimal`	`3.14`
`String`	`'Aspirin'`
`Boolean`	`true`, `false`
`DateTime`	`@2024-01-15T10:30:00`

Intervals

Interval[1, 10]           // Closed interval
Interval(1, 10)           // Open interval
Interval[@2024-01-01, @2024-12-31]  // Date interval

Lists

{ 'Aspirin', 'Metformin', 'Lisinopril' }

Queries

Basic Query

define "Active Medications":
  [MedicationRequest: status = 'active']

With Relationships

define "Medications for Diabetes":
  [MedicationRequest] MR
    where MR.status = 'active'
      and exists (
        [Condition: code in "Diabetes Conditions"] C
          where C.subject = MR.subject
      )

Sorting and Limiting

define "Recent Medications":
  [MedicationRequest] MR
    where MR.status = 'active'
    sort by authoredOn desc

Expressions

Conditional Logic

define "Risk Level":
  if Score > 0.9 then 'High'
  else if Score > 0.5 then 'Medium'
  else 'Low'

Null Handling

define "Safe Score":
  Coalesce(PredictionScore, 0)

define "Has Score":
  PredictionScore is not null

Existence Checks

define "Has Active Medication":
  exists [MedicationRequest: status = 'active']

Value Sets

Definition

valueset "Diabetes Medications": 'http://example.org/fhir/ValueSet/diabetes-meds'

Usage

define "Patient On Diabetes Medication":
  exists [MedicationRequest: medication in "Diabetes Medications"]

Functions

Built-in Functions

// String functions
Length('Aspirin')        // 7
Upper('aspirin')         // 'ASPIRIN'
StartsWith('DB00945', 'DB')  // true

// Date functions
Today()
Now()
AgeInYears()

// Math functions
Abs(-5)                  // 5
Round(3.7)              // 4

Custom Functions

define function "EvidenceLevel"(score Decimal):
  case
    when score >= 0.99 then 'L4'
    else 'L5'
  end

Drug Repurposing Example

library DrugRepurposingCDS version '1.0.0'

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

codesystem "DrugBank": 'https://www.drugbank.ca'

context Patient

define "Active Medications":
  [MedicationRequest] MR
    where MR.status = 'active'

define "Medications With Predictions":
  "Active Medications" MR
    where exists (
      MR.medication.coding C
        where C.system = 'https://www.drugbank.ca'
    )

define "High Confidence Candidates":
  "Medications With Predictions" MR
    return {
      medication: MR.medication.coding.display,
      drugbankId: MR.medication.coding.code
    }

Testing CQL

CQL Testing Framework

// Test case
define "Test Active Medication Count":
  Count("Active Medications") = 3