CQL 語法速查

替運算式取名字，其他地方用雙引號裡的名稱引用它。第二個 define 用 exists 檢查第一個的結果是否至少有一筆。

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

define "Has Diabetes":
  exists "Diabetes Conditions"

取出這位病人的 Condition（診斷）中，代碼在 Diabetes 值集裡的那些。

[Condition: "Diabetes"]

用單一代碼取資料：代碼是 LOINC 4548-4 的 Observation，也就是 HbA1c 檢驗結果。

[Observation: "HbA1c"]

不加篩選，取出這位病人所有的 Encounter（就診紀錄）。

[Encounter]

指定用哪個欄位比對。不寫欄位時用資源的主要代碼欄位，Condition 和 Observation 都是 code，所以這行和第一個寫法的結果相同。

[Condition: code in "Diabetes"]

O 是別名。只有別名的查詢會原樣回傳整個清單，通常還會接下面的子句。

[Observation: "HbA1c"] O

只留下條件是 true 的資料，false 和 null 都會被排除。Observation 的 effective 在 FHIR 可能是時間點或一段期間，as dateTime 只取時間點；如果是期間，結果是 null，這一筆就不會留下。

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

只留下找得到至少一筆相符資料的項目：就診期間內有驗 HbA1c 的就診。

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

反過來，留下一筆相符資料都找不到的項目：就診期間內沒有驗 HbA1c 的就診。

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

決定每一筆輸出什麼；Tuple 可以組成有欄位名稱的新結構。Tuple 裡不會自動轉換型別，所以這裡呼叫 FHIRHelpers.ToDateTime，讓 takenAt 成為 CQL 的 DateTime；在比較運算裡，FHIRHelpers 會自動轉換。

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

排序：asc 由小到大（預設），desc 由大到小。sort by 後面直接寫欄位名稱，不加別名；start of period 是就診開始的時間。

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

布林值。查不到資料時是 null，見三值邏輯與 null。

true
false

整數。

42

小數。

7.5

文字，用單引號。雙引號包的是名稱，不是文字。

'final'

日期，以 @ 開頭。

@2026-03-15

日期加時間，中間用 T 隔開；+08:00 是台灣的時區。

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

只有時間，以 @T 開頭。

@T08:30

數值加單位。單位用 UCUM 寫法並加單引號；時間長度用 years、months、days 等英文字，不加引號。

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

區間。中括號包含端點，小括號不包含：Interval[18, 65) 是 18 以上、未滿 65。

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

清單，用大括號。retrieve 和查詢的結果也都是清單。

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

有欄位名稱的結構，每個欄位寫成「名稱: 值」。

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

單一代碼：代碼值和代碼系統，可以加 display。

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

代表同一件事的一組代碼，例如同一項檢驗的兩個 LOINC 代碼。FHIR 的 CodeableConcept 在 CQL 裡就是 Concept。

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

是否在清單裡。in 和 contains 是同一件事，只是左右顛倒。

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

是否落在區間內：18 到 75 歲，兩端都包含。區間也可以用 contains。

AgeInYears() in Interval[18, 75]

代碼是否在值集裡。C.code 是 FHIR 的 CodeableConcept，其中任一個代碼在值集裡就算，結果和 [Condition: "Diabetes"] 相同。

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

清單至少有一筆就是 true。空清單和 null 都得到 false，不會是 null。

exists "HbA1c In Period"

清單有幾筆，不算 null。這裡是「量測期間內至少驗了兩次 HbA1c」。

Count("HbA1c In Period") >= 2

第一筆、最後一筆，照清單現有的順序取，清單是空的時候是 null。HbA1c Results 已經依 takenAt 由舊到新排好，所以 Last 是最近一次。

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

比較。數量要單位相容才能比；任一邊是 null，例如沒有 HbA1c 結果，比較的結果就是 null。

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

等價。比較文字時不分大小寫；比較代碼時只看代碼系統和代碼值，不看 display；兩邊都是 null 時是 true，所以 ~ 不會回傳 null。

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

且、或、非。遇到 null 的算法見三值邏輯與 null。

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

「如果 A，那麼 B」：A 不成立時結果是 true，A 成立時結果就看 B。這裡是「有糖尿病的話，量測期間內要驗過 HbA1c」。

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

檢查是不是 null，結果只會是 true 或 false。

"Latest HbA1c" is null

值剛好是 true（或 false）才成立，null 會得到 false。為什麼需要它，見結果與 is true。

"HbA1c Controlled" is true

條件是 null 時會走 else。所以先用 is true、is false 分出兩種確定的情況，最後的 else 才是資料不足。

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

整段落在區間內。左邊是時間點時，意思是這個時間點在區間內，例如查詢一節的 (O.effective as dateTime) during "Measurement Period"。

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

早於、晚於。start of、end of 取出區間的開頭或結尾：這裡是量測期間開始以前的 HbA1c。

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

加上時間量：Y 之前的 3 個月內；or more 則是 3 個月以上。這裡是量測期間結束前 3 個月內的 HbA1c。

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

兩段期間有重疊：跨年的住院也算進 2026 年。

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

只看期間開始或結束的那一刻：結束時間落在量測期間內的就診。

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

區間的開頭和結尾。量測期間的右端是小括號，所以 end of 是 2027-01-01 的前一毫秒。

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

兩個時間之間經過幾個完整的單位，單位可以是 years、months、days 等。

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

跨過幾次單位的界線。12 月 31 日到隔天只差一天：完整的年是 0，但跨過一次年份界線，所以是 1。

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

日期加減。Today() 是執行當天，Today() - 90 days 就是 90 天前。

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

區間的長度：3 月 1 日到 3 月 4 日是 3 天。

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

病人年齡，依 Patient 的 birthDate 計算，沒有生日時是 null。AgeInYears() 以執行當天計算；AgeInYearsAt 以指定的時間計算，結果不會因為哪天執行而改變，品質指標多用這個。

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

參數要寫型別，這裡的 Observation 是 FHIR 的 Observation；呼叫時把值放進括號。要寫明回傳型別，可以在括號後面加 returns Boolean。

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

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

加了 fluent，就能接在值後面用點號呼叫：O.isFinal() 等於 isFinal(O)。這是 CQL 1.5 加入的寫法。

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

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

呼叫 include 進來的 library 裡的函式，前面加 called 指定的別名。

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