Skip to main content

FHIR4DS Technical Whitepaper

SQL-Native CQL Evaluation: Architecture, Speed, and Auditability

1. Executive Summary​

FHIR4DS represents a paradigm shift in clinical quality measurement and population health analytics. By translating Clinical Quality Language (CQL) directly into vectorized DuckDB SQL, the engine enables the evaluation of entire patient populations in a single columnar query. This approach eliminates the "black box" nature of traditional engines while providing order-of-magnitude performance gains.

MetricFHIR4DS Capability
Execution Speed~13ms mean (~2ms median) per patient
Throughput Advantage~73× faster than traditional JVM engines
Standards Compliance100% FHIRPath, CQL, and SQL-on-FHIR v2
AuditabilityFull per-expression evidence narratives
InfrastructureZero-server — runs in notebooks or browser (WASM)
ScaleVectorized execution handles 100k+ patients with ease

2. The Paradigm Shift: SQL-Native Execution​

Traditional clinical reasoning engines operate on a row-by-row (or patient-by-patient) basis. This requires loading each patient's full FHIR bundle into memory, initializing a virtual machine, and traversing the logic tree for every individual.

FHIR4DS introduces SQL-Native Execution. Instead of looping through patients, the engine compiles the entire CQL library into a single, highly optimized DuckDB SQL statement.

  • Vectorized Processing: FHIR4DS treats patient data as columns in a database. Operations are performed on the entire population at once, utilizing modern CPU instructions (SIMD) via DuckDB.
  • No Pre-Flattening: The engine queries raw FHIR JSON directly using high-performance C++ extensions, avoiding costly ETL or data transformation steps.
  • Analytical Optimization: By leveraging the DuckDB optimizer, complex joins and filters are resolved at the database level rather than the application level.

3. Performance & Scalability​

Speed Benchmarks​

In head-to-head benchmarks against the industry-standard Java Clinical Reasoning engine (using 10 shared measures with 100% accuracy), FHIR4DS demonstrated a transformative performance gap:

MetricTraditional Engine (Java)FHIR4DS (SQL Native)Speedup
Mean Execution/Patient~968ms~13ms~73×
Median Execution/Patient~839ms~2ms~405×

Linear vs. Near-Zero Marginal Scalability​

Because FHIR4DS uses a set-based architecture, the cost of adding a patient to a query is near-zero compared to the linear overhead of row-by-row engines. At production scales (10,000+ patients), the advantage compounds, enabling real-time analytics that were previously only possible via overnight batch processing.

Timing Explained: Pre-Compilation vs. Execution​

FHIR4DS separates the analytical lifecycle into three distinct phases:

  1. CQL Parse: Resolves syntax and creates an ELM-compatible AST (~789ms).
  2. SQL Translation: Compiles the AST into optimized DuckDB SQL (~3–5s).
  3. SQL Execution: The relevant production metric (~13ms/patient).

Phase 1 and 2 are pre-compilation steps that happen once per library version and are cached. Phase 3 is the only recurring cost during production runs.

4. Standards Compliance & Accuracy​

FHIR4DS is built for production healthcare environments where accuracy is non-negotiable.

  • CQL Spec Compliance: 100% compliance across 3,044 tests.
  • FHIRPath Spec Compliance: 100% compliance across 935 tests.
  • SQL-on-FHIR v2 Compliance: 100% compliance across 140 tests.
  • Clinical Accuracy: Tested against 46 official 2025 QI-Core CMS eCQMs. 42 of 46 achieve 100% accuracy against official test bundles (the remaining 4 have known upstream test data issues).

5. Transparency & Auditability​

A critical failure point of traditional engines is the "Black Box" problem: getting a result without knowing why it was reached. FHIR4DS solves this through two layers of transparency:

  1. Inspectable SQL: The generated SQL is plain, readable DuckDB SQL. Data scientists can debug, index, or optimize the query directly.
  2. Evidence Narratives: The engine generates a "logical breadcrumb" for every decision. Every population membership (e.g., Numerator inclusion) is accompanied by a human-readable narrative and the specific FHIR resources that satisfied the criteria.

6. Deployment & Environment Portability​

The FHIR4DS architecture is completely portable, requiring no specialized server infrastructure.

  • Local Analytics: Run production-grade CQL in a standard Jupyter or Colab notebook.
  • Zero-Server Infrastructure: No JVM, Docker, or server setup required.
  • Edge Computing (WASM): The entire engine (DuckDB + Extensions + Python) compiles to WebAssembly, enabling 100% client-side execution in SMART on FHIR applications. Patient data never leaves the local environment.

7. Primary Use Cases​

  • Regulatory Reporting: Automated eCQM submission with full audit trails.
  • Real-Time Clinical Decision Support: SMART on FHIR apps that evaluate logic in the browser.
  • Population Health: High-speed screening and risk stratification across millions of records.
  • Research Pipelines: Fast FHIR data extraction via SQL-on-FHIR ViewDefinitions.

8. Conclusion​

FHIR4DS bridges the gap between healthcare standards and modern data science. By combining the rigor of Clinical Quality Language with the performance of columnar SQL, it provides a scalable, auditable, and incredibly fast foundation for the next generation of healthcare analytics.

tip

Next Steps