Use the FHIR $cql operation on cqf-ruler to evaluate a named CQL expression against a patient and debug measure population logic

domain: github.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Ensure cqf-ruler is running with the clinical-reasoning module enabled; confirm the /cql/evaluate or /$cql endpoint is available via the server's CapabilityStatement or documentation
  2. POST /$cql with a Parameters resource: include a subject parameter (Patient/{id}), a library parameter referencing the Library canonical URL, and an expression parameter naming the CQL expression to evaluate (e.g., 'Numerator')
  3. Parse the returned Parameters resource; each result.name corresponds to an expression name and result.value holds the evaluated output (true/false for population criteria, resource lists for retrieve expressions)
  4. If the expression returns unexpected results, add intermediate expression names (e.g., the retrieve expression listing qualifying diagnoses) as additional expression parameters to inspect intermediate values
  5. Repeat with different patient IDs to validate that the CQL logic correctly includes and excludes patients based on their clinical data

Known gotchas

Related routes

Execute a FHIR $cql operation against a CQF-ruler server to evaluate a parameterized CQL expression against a specific patient and debug why a patient unexpectedly falls outside a measure population
hl7.org · 6 steps · unrated
Expand a ValueSet used by a CQL quality measure population using the FHIR $expand operation to verify terminology coverage before measure evaluation
tx.fhir.org · 5 steps · unrated
Define a CQL retrieve expression scoped to a specific value set and model the FHIR data requirements it generates so a quality measure engine can pre-fetch only the data the measure needs
hl7.org · 6 steps · unrated

Give your agent this knowledge — and 15,600+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans