Measure/$evaluate-measure via SQL

FHIR Measure/$evaluate-measure implemented as native PostgreSQL SQL on Aidbox. No CQL engine required. 12 CMS quality measures, 484 test patients, interactive demo.

⚑ Solution

A working FHIR R4 Measure/$evaluate-measure implementation on Aidbox, without a CQL engine. Four things to know:

1. 12 measures translated from CQL to native PostgreSQL SQL. Each measure is a single SQL file (sql/measures/cmsXXX/02-cmsXXX-measure.sql, ~200–400 lines) that replaces the original CQL definition. The translation was verified against the reference MeasureReports from dqm-content-qicore-2025 and independently with the cqframework CQL engine.
2. Every supported measure is stored as a FHIR Measure resource in Aidbox (plus its Library resources), with canonical URL, version, groups and scoring metadata. Loaded via setup.py from data/measures-bundle.json. You can list them with GET /Measure and look one up by alias, FHIR Resource ID, or canonical URL.
3. The operation is exposed on the Measure resource type — per the FHIR R4 spec the measure is passed as a parameter:

   POST /Measure/$evaluate-measure?measure=cms130&reportType=population&periodStart=2026-01-01&periodEnd=2026-12-31

   Instance-level invocation POST /Measure/{id}/$evaluate-measure is allowed by the spec but not implemented in this example.
4. Response is a FHIR R4 MeasureReport with group.population counts (initial-population, denominator, denominator-exclusion, numerator), group.measureScore, and — for single-patient reports — evaluatedResource[] with references to the actual Encounter / Condition / Observation that triggered each population. Output aligns with the DEQM indv-measurereport-deqm profile.

Supported parameters: measure, subject, reportType (subject | subject-list | population), periodStart, periodEnd. Full details in API Parameters.

Jump to Quick Start to run it in five minutes, or Architecture to see how the request flows end to end.

01 Quick Start

Prerequisites: Docker with Docker Compose, Python 3, curl (optional, for manual API calls).

Build and start the full stack:

docker compose up --build

This starts three containers: PostgreSQL, Aidbox (port 8888), and the SQL evaluate app (port 8090).

02 Activate Aidbox

Open http://localhost:8888 in your browser and follow the activation prompt.

03 Load Data

In a second terminal, from this directory:

python3 setup.py

This creates shared views, loads terminology and clinical data for all 12 measures (~2 min).

04 Evaluate a Measure

Open Aidbox REST Console and evaluate CMS130 for a single patient:

POST /Measure/$evaluate-measure?measure=cms130&subject=Patient/007ec5f1-08cf-474a-a472-f6a92cca4b79&periodStart=2026-01-01&periodEnd=2026-12-31

Summary report for CMS125 Breast Cancer Screening (all patients, read-only):

GET /Measure/$evaluate-measure?measure=cms125&reportType=population

Response — a FHIR MeasureReport with population counts and measure score:

{
  "resourceType": "MeasureReport",
  "status": "complete",
  "type": "individual",
  "measure": "http://ecqi.healthit.gov/ecqms/Measure/CMS130FHIRColorectalCancerScrn",
  "subject": {
    "reference": "Patient/007ec5f1-08cf-474a-a472-f6a92cca4b79"
  },
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "group": [{
    "population": [
      {
        "code": { "coding": [{ "code": "initial-population" }] },
        "count": 1
      },
      {
        "code": { "coding": [{ "code": "denominator" }] },
        "count": 1
      },
      {
        "code": { "coding": [{ "code": "denominator-exclusion" }] },
        "count": 1
      },
      {
        "code": { "coding": [{ "code": "numerator" }] },
        "count": 0
      }
    ],
    "measureScore": {
      "value": null
    }
  }]
}

05 REST Console Examples

Open the Aidbox REST Console at http://localhost:8888/ui/console and paste any of the snippets below. The adapter resolves the measure parameter in three forms: short alias (cms130), FHIR Resource ID (CMS130FHIRColorectalCancerScrn), or canonical URL.

By alias — individual patient

CMS130 Colorectal Cancer Screening for a single patient:

POST /Measure/$evaluate-measure?measure=cms130&subject=Patient/007ec5f1-08cf-474a-a472-f6a92cca4b79

By canonical URL — summary (all patients)

CMS125 Breast Cancer Screening, population-level MeasureReport:

POST /Measure/$evaluate-measure?measure=https://madie.cms.gov/Measure/CMS125FHIRBreastCancerScreen

By alias with explicit period

CMS165 Controlling High Blood Pressure for a single patient, measurement period 2026:

POST /Measure/$evaluate-measure?measure=cms165&subject=Patient/045f7e0b-bfb3-4ee0-a06d-83c853f6a81e&periodStart=2026-01-01&periodEnd=2026-12-31

By FHIR Resource ID — individual patient

CMS131 Diabetes Eye Exam for a single patient:

POST /Measure/$evaluate-measure?measure=CMS131FHIRDiabetesEyeExam&subject=Patient/01a1241d-fd97-4c72-b288-fd31c4c7ae80

06 Demo App

Start a local HTTP server from this directory:

python3 -m http.server 3000

Then open the demo in your browser:

→ http://localhost:3000/demo/app.html

The demo shows all 12 measures with:

• Patient-level care gaps
• Step-by-step decision chains with evidence
• Measure scores (population-level)

Included Measures

12 measures 484 patients

Aliases & Canonical URLs

Each measure can be referenced by short alias, FHIR Resource ID, or canonical URL in the measure parameter. Click any value to copy.

⚙ Architecture

End-to-end request flow for one Measure/$evaluate-measure call:

Inside the database, the SQL flows through four stable layers:

Each measure is a single SQL file (~200–400 lines) that uses shared flat views and a concepts table for offline terminology matching. No CQL engine, no Java, no external terminology service calls at runtime.

How it works

1. Client sends POST /Measure/$evaluate-measure?measure=cms130&subject=Patient/123
2. Aidbox looks up App/com.sql.evaluate.app and forwards the request to the Flask app on port 8090
3. Flask reads the measure SQL file (sql/measures/cmsXXX/02-cmsXXX-measure.sql), substitutes the measurement period, POSTs to Aidbox /$sql
4. PostgreSQL runs the query: JSONB → flat views → concepts join → measure-specific CTEs (IP, exclusions, numerator)
5. Flask aggregates the per-patient rows into populations and builds a FHIR R4 MeasureReport
6. For single-patient reports, Flask also runs an evidence query and populates evaluatedResource[] with real resource references

⚙ API Parameters

5 of 7 FHIR R4 $evaluate-measure parameters supported. See the R4 OperationDefinition for the full spec.

■ Shutdown

Stop all containers (data preserved in Docker volume):

docker compose down

Or stop and delete all data (clean slate for next run):

docker compose down -v