CQL syntax cheat sheet

Names an expression so other expressions can refer to it by that name. The second define uses exists to check whether the first returned anything.

define "Diabetes Conditions":
  [Condition: "Diabetes"]

define "Has Diabetes":
  exists "Diabetes Conditions"

This patient’s Conditions (diagnoses) whose code is in the Diabetes value set.

[Condition: "Diabetes"]

Filters by a single code: Observations coded LOINC 4548-4, that is, HbA1c results.

[Observation: "HbA1c"]

No filter: every Encounter (visit) for this patient.

[Encounter]

Names the element to match on. Without it, the resource’s primary code element is used, which is code for both Condition and Observation, so this line returns the same as the first form.

[Condition: code in "Diabetes"]

O is the alias. A query with only an alias returns the whole list unchanged; the clauses below usually follow.

[Observation: "HbA1c"] O

Keeps only items for which the condition is true; false and null are both dropped. In FHIR, an Observation’s effective can be a point in time or a period. as dateTime takes the point in time; for a period it gives null, so that item is dropped.

define "HbA1c In Period":
  [Observation: "HbA1c"] O
    where O.status in { 'final', 'amended', 'corrected' }
      and (O.effective as dateTime) during "Measurement Period"

Keeps items that have at least one related match: visits during which an HbA1c was taken.

define "Visits With HbA1c":
  [Encounter] E
    with [Observation: "HbA1c"] O
      such that (O.effective as dateTime) during E.period

The opposite: keeps items with no related match at all, here visits with no HbA1c taken during them.

define "Visits Without HbA1c":
  [Encounter] E
    without [Observation: "HbA1c"] O
      such that (O.effective as dateTime) during E.period

Decides what each item becomes; Tuple builds a new structure with named fields. Tuple fields aren’t converted automatically, so this calls FHIRHelpers.ToDateTime to make takenAt a CQL DateTime. In comparisons, FHIRHelpers converts for you.

define "HbA1c Results":
  "HbA1c In Period" O
    return Tuple {
      takenAt: FHIRHelpers.ToDateTime(O.effective as dateTime),
      result: O.value as Quantity
    }
    sort by takenAt

Sorts ascending (the default) or descending. sort by takes element names directly, without the alias; start of period is when the visit started.

define "Encounters Latest First":
  [Encounter] E
    sort by start of period desc

True or false. When data is missing it is null; see Three-valued logic and null.

true
false

A whole number.

42

A decimal number.

7.5

Text, in single quotes. Double quotes hold names, not text.

'final'

A date, starting with @.

@2026-03-15

A date and time separated by T; +08:00 is Taiwan’s time zone.

@2026-03-15T08:30:00.000+08:00

A time of day only, starting with @T.

@T08:30

A number with a unit. Units use UCUM codes in single quotes; lengths of time use words such as years, months and days, without quotes.

7 '%'
30 'mL/min/{1.73_m2}'
90 days

A range. Square brackets include the boundary and parentheses exclude it: Interval[18, 65) is 18 or more and under 65.

Interval[18, 65)
Interval[@2026-01-01, @2026-12-31]

A list, in curly braces. Retrieves and queries also return lists.

{ 'final', 'amended', 'corrected' }

A structure with named fields, each written as name: value.

Tuple { takenAt: @2026-03-15, result: 6.8 '%' }

A single code: the code and its code system, optionally with a display.

Code '4548-4' from "LOINC" display 'Hemoglobin A1c/Hemoglobin.total in Blood'

A set of codes that mean the same thing, such as two LOINC codes for the same test. A FHIR CodeableConcept becomes a Concept in CQL.

Concept { Code '4548-4' from "LOINC", Code '17856-6' from "LOINC" } display 'Hemoglobin A1c'

Whether the list holds the element. in and contains are the same test with the sides swapped.

'final' in { 'final', 'amended', 'corrected' }  // true
{ 'final', 'amended', 'corrected' } contains 'preliminary'  // false

Whether the value falls within the range: 18 to 75, both ends included. contains works for intervals too.

AgeInYears() in Interval[18, 75]

Whether a code is in a value set. C.code is a FHIR CodeableConcept, and it counts if any of its codes is in the value set, so this returns the same as [Condition: "Diabetes"].

define "Diabetes By Code":
  [Condition] C
    where C.code in "Diabetes"

True if the list has at least one item. An empty list and null both give false, never null.

exists "HbA1c In Period"

How many items the list has, not counting nulls. Here: at least two HbA1c results in the measurement period.

Count("HbA1c In Period") >= 2

The first or last item, in the list’s current order; null if the list is empty. HbA1c Results is already sorted by takenAt from oldest to newest, so Last is the most recent.

define "Latest HbA1c":
  Last("HbA1c Results")

Comparison. Quantities need compatible units. If either side is null, for example when there is no HbA1c result, the comparison is null.

define "HbA1c Controlled":
  "Latest HbA1c".result < 7 '%'

Equivalence. Text is compared ignoring case; codes are compared on code system and code only, ignoring display; two nulls are equivalent, so ~ never returns null.

'Final' ~ 'final'  // true
'Final' = 'final'  // false

And, or, not. For how they treat null, see Three-valued logic and null.

define "Adult With Diabetes":
  "Has Diabetes" and AgeInYears() >= 18

“If A, then B”: when A is false the result is true; when A is true the result is B. Here: a patient with diabetes should have an HbA1c in the measurement period.

define "HbA1c Checked If Diabetic":
  "Has Diabetes" implies exists "HbA1c In Period"

Tests for null. The result is always true or false.

"Latest HbA1c" is null

Holds only when the value is exactly true (or false); null gives false. For why this matters, see The result and is true.

"HbA1c Controlled" is true

A null condition takes the else branch. So test is true and is false first; the final else is then the missing-data case.

define "HbA1c Status":
  if "HbA1c Controlled" is true then 'controlled'
  else if "HbA1c Controlled" is false then 'uncontrolled'
  else 'no-result'

Falls entirely within the interval. When the left side is a point in time, the point is within the interval, as in (O.effective as dateTime) during "Measurement Period" under Queries.

define "Encounters In Period":
  [Encounter] E
    where E.period during "Measurement Period"

Earlier or later. start of and end of pick an interval’s start or end: here, HbA1c results before the measurement period began.

define "HbA1c Before Period":
  [Observation: "HbA1c"] O
    where (O.effective as dateTime) before start of "Measurement Period"

Adds a length of time: within the 3 months before Y; or more means at least 3 months before. Here, HbA1c results in the last 3 months of the measurement period.

define "HbA1c Near Period End":
  [Observation: "HbA1c"] O
    where (O.effective as dateTime) 3 months or less before end of "Measurement Period"

The two periods share some time: a hospital stay over the new year counts toward 2026.

define "Encounters Overlapping Period":
  [Encounter] E
    where E.period overlaps "Measurement Period"

Looks only at the moment a period starts or ends: visits that ended during the measurement period.

define "Encounters Ending In Period":
  [Encounter] E
    where E.period ends during "Measurement Period"

An interval’s start and end. The measurement period’s upper bound is open, so end of returns the millisecond before 2027-01-01.

start of "Measurement Period"  // @2026-01-01T00:00:00.000
end of "Measurement Period"  // @2026-12-31T23:59:59.999

How many whole units passed between two times; the unit can be years, months, days and so on.

years between @1960-05-01 and @2026-10-28  // 66
days between @2026-03-01 and @2026-03-15  // 14

How many unit boundaries were crossed. 31 December to the next day is one day: zero whole years, but one year boundary crossed, so 1.

years between @2025-12-31 and @2026-01-01  // 0
difference in years between @2025-12-31 and @2026-01-01  // 1

Adds or subtracts time. Today() is the day of evaluation, so Today() - 90 days is 90 days ago.

@2026-01-15 + 3 months  // @2026-04-15
Today() - 90 days

The length of an interval: 1 March to 4 March is 3 days.

duration in days of Interval[@2026-03-01, @2026-03-04]  // 3

The patient’s age from the Patient’s birthDate, or null if it is missing. AgeInYears() uses the day of evaluation; AgeInYearsAt uses the time you give, so the result doesn’t depend on when it runs. Quality measures usually use the latter.

AgeInYears() >= 18
AgeInYearsAt(end of "Measurement Period") >= 18

Arguments need a type; Observation here is the FHIR Observation. Call it by putting the value in parentheses. To state the return type, add returns Boolean after the parentheses.

define function "Is Final"(obs Observation):
  obs.status in { 'final', 'amended', 'corrected' }

define "Final HbA1c":
  [Observation: "HbA1c"] O
    where "Is Final"(O)

With fluent, the function can be called with a dot after a value: O.isFinal() is the same as isFinal(O). Fluent functions arrived in CQL 1.5.

define fluent function isFinal(obs Observation):
  obs.status in { 'final', 'amended', 'corrected' }

define "Final eGFR":
  [Observation: "eGFR"] O
    where O.isFinal()

Calls a function from an included library, prefixed with the alias given after called.

define "HbA1c Dates":
  "HbA1c In Period" O
    return FHIRHelpers.ToDateTime(O.effective as dateTime)