Reading the workbench’s CQL

The example clause

Every example on this page uses this clause. The workbench splits it into four atomic conditions and two groups:

本品限內科專科醫師處方，病人需為成人（年滿十八歲），且 eGFR ≥ 30 mL/min/1.73m²；未達標準者，須經腎臟科會診同意後使用。Translation: Must be prescribed by an internal medicine specialist. The patient must be an adult (18 or older) with eGFR ≥ 30 mL/min/1.73m². Below that threshold, use requires nephrology consultation approval.

The full file

This is the complete file renderCql generates for the clause. The next four sections walk through it from top to bottom.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

library Clause_Sample version '1.0.0'

using FHIR version '4.0.1'

/* Evidence adapters supply true, false, or null for each reviewed criterion. */
parameter "C1" Boolean default null
parameter "C2" Boolean default null
parameter "C3" Boolean default null
parameter "C4" Boolean default null

context Patient

define "Criterion C1":
  "C1"

define "Criterion C2":
  "C2"

define "Criterion C3":
  "C3"

define "Criterion C4":
  "C4"

define "Group G1":
  "Criterion C1"
  and "Criterion C2"
  and "Group G2"

define "Group G2":
  "Criterion C3"
  or "Criterion C4"

define "Eligibility":
  "Group G1"

define "Eligibility Status":
  if "Eligibility" is true then 'eligible'
  else if "Eligibility" is false then 'ineligible'
  else 'insufficient-data'

Header: library, using, context

Lines 1, 3 and 11 say what the file is, which data model it uses, and who it is evaluated for.

library Clause_Sample version '1.0.0'

The name and version of this logic, used to tell exported files apart.

using FHIR version '4.0.1'

Declares the FHIR R4 data model. The workbench’s logic doesn’t actually read FHIR data; the next section explains why.

context Patient

Every define after this line is evaluated for one patient.

Parameters: one input per condition

Each atomic condition becomes a parameter of type Boolean. The CQL never queries the record itself: an evidence adapter checks the record first and passes the answer in as a parameter.

parameter "C3" Boolean default null

A parameter only ever holds one of three values. Take C3 (eGFR ≥ 30):

default null means that when nobody supplies a value, the answer is “unknown”, not “doesn’t meet”.

define: naming an expression

define is followed by a name and a colon; its body starts on the next line. The workbench generates three layers:

define "Criterion C3":
  "C3"

define "Group G2":
  "Criterion C3"
  or "Criterion C4"

define "Eligibility":
  "Group G1"

• Criterion C3 takes the value of parameter C3 as is.
• Group G2 is G2 on the review screen: C3 or C4.
• Eligibility points at the outermost group, G1: the verdict for the whole clause.

Note: double quotes hold names, like "Group G2"; single quotes hold text, like 'eligible'.

Three-valued logic: what null does

A parameter can be null, so and, or and not all have to handle “unknown”. The rule fits in one sentence: if the answer is already settled, null doesn’t matter; if it isn’t, the result is null.

For example, false and null is false: once one condition fails, “all of them” can’t hold, whatever the other value is. true or null is true for the same reason.

The result: why is true

The last define turns the three-valued result into three statuses:

define "Eligibility Status":
  if "Eligibility" is true then 'eligible'
  else if "Eligibility" is false then 'ineligible'
  else 'insufficient-data'

is true holds only when the value is true. On null it returns false, not null, so the three branches map exactly to the three outcomes: eligible, ineligible and insufficient-data.

define "Eligibility Status":
  if "Eligibility" then 'eligible'
  else 'ineligible'

Four scenarios, step by step

Plug in each set of parameters and work from the inside out: G2 first, then G1.

In row three C3 is null, but C4 is true, and null or true is already settled as true, so the patient is still eligible. In row four both C3 and C4 are null, so G2 can’t be decided and the whole clause is insufficient-data until an eGFR result or a consult record comes in.

Try it yourself

Set each condition to meets, doesn’t meet or not found, and watch G2, G1 and the result change. Start from a scenario in the table above, then change one cell.

FAQ

Next steps