A native Clinical Quality Language (CQL) engine for Go, designed for evaluating CQL expressions against FHIR R4 resources.
go get github.com/gofhir/cqlpackage 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"])
}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- 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
// 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)| 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 |
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 |
MIT - Copyright (c) 2025 Roberto Araneda