cql-sdk

Install from PyPI: pip install ms-cql-sdk

Published at https://pypi.org/project/ms-cql-sdk/. The Python import name remains cql_sdk.

A Python SDK that compiles Clinical Quality Language (CQL) definitions to parameterized PostgreSQL SQL and executes them over FHIR R4 resources stored as JSONB. ELM remains an internal compiler representation and a compatibility surface for existing consumers.

What's new in 0.7.1

• PostgreSQL property compilation now expands FHIR choice roots to their concrete JSON fields, including effectiveDateTime, valueQuantity, onsetDateTime, and performedPeriod.
• Choice expansion matches the existing in-memory runtime while ordinary FHIR properties retain compact SQL.
• Live validation covers the ePC-02 gestational-age Observation predicates against PostgreSQL-backed FHIR JSONB data.

What's new in 0.7.0

• PostgresCompiler translates CQL/ELM definitions to parameterized SQL.
• PostgresExecutor runs definitions against PostgreSQL 16.
• PostgresFHIRStore initializes the FHIR JSONB schema, atomically replaces patient Bundles, and loads the bundled expanded ValueSets.
• All definitions in the platform's CMS122v11, CMS165v9, and ePC-02 measures compile and execute as SQL.
• The prior in-memory Python ELM runtime remains available for compatibility.

Disclaimer

This SDK is provided as-is under the MIT license. It is a general purpose CQL/ELM execution toolkit and does not include or grant any rights to third-party measure specifications, value sets, or code systems.

If you use this SDK to compute HEDIS® measures in production, you are responsible for obtaining the appropriate license from NCQA. HEDIS is a registered trademark of the National Committee for Quality Assurance (NCQA). See https://www.ncqa.org/hedis/measures/ for measure licensing terms.

The same applies to other proprietary measure stewards (for example, CMS eCQM artifacts may have their own usage terms, and any LOINC, SNOMED CT, RxNorm, ICD, or CPT content carries its own licensing).

What's new in 0.6.1

• README: surface the 0.6.0 release notes on the PyPI project page (no code changes).

What's new in 0.6.0

• Expanded CQL → ELM front-end for parity with common Firely CQL SDK constructs:
  • DateTime literals with timezone offsets (Z, +hh:mm, -hh:mm).
  • The X between low and high range operator.
  • Conditional expressions: if ... then ... else ... and case ... when ... then ... [else ...] end.
  • duration in <precision> between and difference in <precision> between.
  • Model-qualified cast types such as X as FHIR.dateTime.
  • Function-call forms Exists(...), Now(), Today().
• Runtime additions: Now, Today, DurationBetween and DifferenceBetween operators, plus case-insensitive as coercion for FHIR primitive types.

What's new in 0.5.0

• DQM (FHIR / QI-Core) measure package evaluation via the new cql_sdk.dqm package: a FHIR Measure resource model, QI-Core profile model-info, an ELM-first multi-library MeasurePackage loader, and proportion scoring for both patient (boolean) and episode-of-care (Encounter) basis.
• Runtime additions: list set operations (Union / Except / Intersect), value-set membership (InValueSet / AnyInValueSet), user-defined function parameter binding (OperandRef), and query with / without relationships.
• New public API: load_measure_package / evaluate_measure_package.

What's new in 0.4.3

• License changed from Apache-2.0 to MIT.
• Added Origins and Attribution, Acknowledgements, and Relationship to Firely CQL SDK sections to README.

What's new in 0.4.2

• Project URL metadata now points at the canonical github.com/microsoft/azure-healthcare-digital-quality-cql-sdk repository.
• Added Disclaimer section covering HEDIS® / NCQA licensing responsibilities for production use, and a note on third-party terminology content (LOINC, SNOMED CT, RxNorm, ICD, CPT).

What's new in 0.4.1

• README: surface the 0.3.0 and 0.4.0 release notes on the PyPI project page (no code changes).

What's new in 0.4.0

• Spark adapter fix: SparkInvocation.run now uses the library registered via from_elm_path instead of the first entry in the toolkit registry, which was the auto-registered synthetic FHIRHelpers. Fixes KeyError: "Definition '<name>' not found in library 'FHIRHelpers|4.0.1'.".
• SparkInvocation accepts an explicit default_library_identifier for callers constructing the toolkit directly.

What's new in 0.3.0

• Invocation toolkit auto-registers a synthetic FHIRHelpers library so measures that include FHIRHelpers resolve without an extra step.
• Public API consolidation around InvocationToolkit (register, has, validate, invoke) as the preferred entry point.
• Library registry de-duplicates id and id|version keys during iteration.

What's new in 0.2.1

• Internal: ruff and mypy --strict are now both clean (parser/translator refactors broke long lines into helpers, no behavior change). Aligns the package with the CI gates so downstream forks pass on a clean checkout.

What's new in 0.2.0

• Pure-Python CQL → ELM front end under cql_sdk.compiler.cql_to_elm — no Java required. Covers the CQL 1.5 subset used by typical CMS eCQM measures: library/using/include/codesystem/valueset/code/parameter/context/define, retrieves and queries with where/sort/return, all standard arithmetic and comparison operators, interval/list literals, casts, and fluent function calls (X.extension("...")).
• New public API: cql_sdk.api.load_library_from_cql and load_library_from_cql_text.
• New CLI command: cql-sdk compile <CQL_FILE> [--output ELM.json].

Why this SDK

• PostgreSQL-native execution for set-based clinical quality evaluation.
• Parameterized SQL over an indexed FHIR JSONB and terminology schema.
• Pure-Python CQL parser with ELM used as an internal intermediate form.
• Optional FHIR integration (retrieval, type conversion, terminology).
• Optional Spark / Microsoft Fabric integration (the same core package runs unchanged in both environments).
• A Typer-based CLI for inspecting, validating, packaging and running ELM.
• Designed around pre-generated ELM artifacts as a first-class workflow — no Java/CQL-to-ELM toolchain is required for normal execution.

Package layering

 cql_sdk
 ├── abstractions/   # Protocols / ABCs for operators, terminology, data, packaging
 ├── elm/            # ELM model + (de)serialization
 ├── runtime/        # RuntimeContext, operators, comparers, intervals, datetime
 ├── compiler/       # Expression planner, bindings, type manager
 ├── invocation/     # High-level toolkit / invoker / library registry (PUBLIC API)
 ├── fhir/           # Optional FHIR adapters
 ├── postgres/       # CQL-to-SQL compiler, executor, schema, and FHIR store
 ├── spark/          # Optional Spark / Fabric adapters
 ├── packaging/      # Library + resource packaging primitives
 ├── cli/            # Typer CLI (`cql-sdk`)
 └── api.py          # Top-level convenience facade (PUBLIC API)

The invocation toolkit and cql_sdk.api are the preferred entry points. Internal modules (compiler, low-level runtime) are available but not the recommended consumption path.

Quick start

Install (base)

uv sync

Install with optional extras

uv sync --extra fhir
uv sync --extra postgres   # pulls pg8000; required for PostgreSQL execution
uv sync --extra spark        # pulls pyspark; not required for base install
uv sync --extra dev --extra test

Run the local hello-world example

uv run python examples/hello_world/run.py

Load ELM and invoke a definition (Python)

from cql_sdk.api import load_library, invoke

library = load_library("examples/hello_world/HelloWorld.elm.json")
result = invoke(library, definition="Greeting")
print(result)

Compile a CQL source file (no Java required)

from cql_sdk.api import load_library_from_cql

library = load_library_from_cql("path/to/Measure.cql")
print(library.identifier)            # CMS122|11
print(list(library.definitions))     # ['Initial Population', 'Numerator', ...]

Or get the raw ELM JSON via the lower-level entry point:

from cql_sdk.compiler.cql_to_elm import compile_file
elm = compile_file("path/to/Measure.cql")

Execute CQL on PostgreSQL

from cql_sdk.api import execute_library_on_postgres, load_library_from_cql
from cql_sdk.postgres import PostgresFHIRStore

database_url = "postgresql://dq@localhost:5432/dq"
# Set PGPASSWORD through the process environment or a secret provider.
store = PostgresFHIRStore(database_url=database_url)
store.initialize()
store.load_value_sets()
store.replace_patient_bundle("patient-1", bundle)

library = load_library_from_cql("path/to/Measure.cql")
result = execute_library_on_postgres(
  library,
  definition="Initial Population",
  database_url=database_url,
  patient_id="patient-1",
  parameters={"Measurement Period": (period_start, period_end)},
)

Use compile_cql_to_sql(...) when SQL generation is needed without execution. All literal values, patient identifiers, JSON paths, and terminology values are emitted as bind parameters.

Use the CLI

uv run cql-sdk compile path/to/Measure.cql --output dist/Measure.elm.json
uv run cql-sdk inspect examples/hello_world/HelloWorld.elm.json
uv run cql-sdk validate examples/hello_world/HelloWorld.elm.json
uv run cql-sdk run examples/hello_world/HelloWorld.elm.json --definition Greeting
uv run cql-sdk package examples/hello_world --output dist/packages

Spark / Fabric usage

Spark support is opt-in:

uv sync --extra spark

from pyspark.sql import SparkSession
from cql_sdk.spark import SparkInvocation

spark = SparkSession.builder.getOrCreate()
invocation = SparkInvocation.from_elm_path(
    "examples/hello_world/HelloWorld.elm.json", spark=spark
)
df = invocation.run(definition="Greeting")
df.show()

Core modules never import pyspark — importing cql_sdk.spark is the only place Spark is required.

Development

uv sync --extra dev --extra test
uv run ruff check .
uv run mypy
uv run pytest -m "not spark"
uv run pytest -m spark            # requires `--extra spark`

See docs/development.md for more.

Documentation

• Architecture
• Public API
• Packaging
• Development

License

MIT. See LICENSE.

This license covers the SDK source code only. It does not grant rights to HEDIS® measure specifications (license from NCQA required for production use, see the Disclaimer section), nor to any third-party terminology content (LOINC, SNOMED CT, RxNorm, ICD, CPT, etc.).

Origins and Attribution

This project was inspired by and derived from concepts demonstrated in the Firely and NCQA CQL SDK project:

• https://github.com/FirelyTeam/firely-cql-sdk

The Firely CQL SDK is NCQA's and Firely's official SDK for working with Clinical Quality Language (CQL) on the .NET platform.

The Microsoft Azure Healthcare Digital Quality CQL SDK extends these concepts to support additional healthcare analytics scenarios, including cloud-native execution patterns, Python interoperability, Spark/Fabric integration, and Azure-based deployment models.

We are grateful to Firely and NCQA for their contributions to the CQL ecosystem and for advancing interoperable clinical quality measurement technologies.

The original Firely project and its contributors retain ownership of their respective intellectual property and code contributions. Please refer to the upstream repository for additional details and licensing information.

Relationship to Firely CQL SDK

This project is not a drop-in replacement for the Firely CQL SDK.

While portions of the architecture, compiler design concepts, and CQL execution patterns were informed by the Firely implementation, this SDK introduces additional capabilities focused on analytics, distributed execution, cloud-native deployment, and modern healthcare data platform integration.

Acknowledgements

Special thanks to:

• Firely
• NCQA
• HL7 Clinical Quality Language (CQL) Community
• FHIR Community Contributors

for advancing standards-based clinical quality measurement and interoperability.