Skip to content

Repository files navigation

go-cql

CI Go Reference codecov Go Report Card License: MIT

A native Clinical Quality Language (CQL) engine for Go, designed for evaluating CQL expressions against FHIR R4 resources.

Installation

go get github.com/gofhir/cql

Quick Start

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/gofhir/cql"
)

func main() {
	engine := cql.NewEngine(
		cql.WithTimeout(30 * time.Second),
	)

	cqlSource := `
		library Example version '1.0'
		using FHIR version '4.0.1'
		context Patient
		define IsAdult: AgeInYears() >= 18
	`

	patient := json.RawMessage(`{"resourceType": "Patient", "birthDate": "1990-01-01"}`)

	results, err := engine.EvaluateLibrary(context.Background(), cqlSource, patient, nil)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("IsAdult:", results["IsAdult"])
}

Conformance

1731/1731 (100%) — passes all official cqframework/cql-tests conformance suites.

Suite Tests Status
Aggregate Functions 50/50
Aggregate Operator 9/9
Arithmetic Functions 212/212
Comparison Operators 223/223
Conditional Operators 9/9
DateTime Operators 317/317
Errors and Messaging 4/4
Interval Operators 412/412
List Operators 212/212
Logical Operators 39/39
Nullological Operators 22/22
Query Expressions 12/12
String Operators 81/81
Type Operators 35/35
Types 28/28
Value Literals & Selectors 66/66

Run conformance tests locally:

go test ./conformance/... -v

Features

  • Full CQL parsing via ANTLR4 grammar
  • 100% conformance with the official CQL test suite
  • Expression evaluation with FHIR R4 context
  • Pluggable data and terminology providers
  • Compiled expression caching
  • Configurable timeouts and resource limits
  • Trace listener support for debugging

API

Engine

// Create engine with options
engine := cql.NewEngine(
    cql.WithDataProvider(dp),
    cql.WithTerminologyProvider(tp),
    cql.WithTimeout(30 * time.Second),
    cql.WithMaxDepth(100),
)

// Evaluate all definitions in a CQL library
results, err := engine.EvaluateLibrary(ctx, cqlSource, resource, params)

// Evaluate a single named expression
value, err := engine.EvaluateExpression(ctx, cqlSource, "ExpressionName", resource, params)

// Validate CQL syntax without evaluation
err := engine.Compile(cqlSource)

Options

Option Description Default
WithDataProvider Data provider for retrieve expressions nil
WithTerminologyProvider Terminology provider for valueset checks nil
WithModelInfo FHIR model information R4
WithTimeout Per-evaluation timeout 30s
WithMaxExpressionLen Maximum CQL source length 100KB
WithMaxRetrieveSize Maximum resources per retrieve 10000
WithMaxDepth Maximum recursion depth 100
WithTraceListener Trace listener for debugging nil

Error Handling

The engine returns typed errors for different failure modes:

Error Type Description
ErrSyntaxError CQL parse error
ErrEvaluation Runtime evaluation error
ErrTimeout Evaluation exceeded timeout
ErrTooCostly Expression exceeds size limits

License

MIT - Copyright (c) 2025 Roberto Araneda

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages